Man Pages

elisp - phpMan elisp - phpMan

Command: man perldoc info search(apropos)  


File: elisp,  Node: Top,  Next: Introduction,  Prev: (dir),  Up: (dir)

Emacs Lisp
**********

This Info file contains edition 3.0 of the GNU Emacs Lisp Reference
Manual, corresponding to GNU Emacs version 23.1.

   This is edition 3.0 of the GNU Emacs Lisp Reference Manual,
corresponding to Emacs version 23.1.

   Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, 1999,
2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009  Free
Software Foundation, Inc.

     Permission is granted to copy, distribute and/or modify this
     document under the terms of the GNU Free Documentation License,
     Version 1.3 or any later version published by the Free Software
     Foundation; with the Invariant Sections being "GNU General Public
     License," with the Front-Cover texts being "A GNU Manual," and
     with the Back-Cover Texts as in (a) below.  A copy of the license
     is included in the section entitled "GNU Free Documentation
     License."

     (a) The FSF's Back-Cover Text is: "You have the freedom to copy and
     modify this GNU manual.  Buying copies from the FSF supports it in
     developing GNU and promoting software freedom."

* Menu:

* Introduction::            Introduction and conventions used.

* Lisp Data Types::         Data types of objects in Emacs 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.
* Hash Tables::             Very fast lookup-tables.
* 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::               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.
* Advising Functions::      Adding to the definition of a function.
* 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.
* 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 system-level windows.
* 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.
* Non-ASCII Characters::    Non-ASCII text in buffers and strings.
* 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.

* Processes::               Running and communicating with subprocesses.
* Display::	            Features for controlling the screen display.
* System Interface::        Getting the user id, system type, environment
                              variables, and other such things.

Appendices

* Antinews::                Info for users downgrading to Emacs 22.
* GNU Free Documentation License:: The license for this documentation.
* GPL::                     Conditions for copying and changing GNU Emacs.
* Tips::                    Advice and coding conventions for Emacs Lisp.
* GNU Emacs Internals::     Building and dumping Emacs;
                              internal data structures.
* Standard Errors::         List of all error symbols.
* Standard Buffer-Local Variables::
                            List of variables buffer-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::            Emacs Lisp is descended from Maclisp.
* Conventions::             How the manual is formatted.
* Version Info::            Which Emacs version is running?
* 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 when examples print text.
* 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 description of an imaginary
                                     function, `foo'.
* A Sample Variable Description::  A description of an imaginary
                                     variable, `electric-future-map'.

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 Emacs.
* Circular Objects::        Read syntax for circular structure.
* 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.
* 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.
* Char-Table Type::     One-dimensional sparse arrays indexed by characters.
* Bool-Vector Type::    One-dimensional arrays of `t' or `nil'.
* Hash Table Type::     Super-fast lookup tables.
* 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.
* Byte-Code Type::      A function written in Lisp, then compiled.
* Autoload Type::       A type used for automatically loading seldom-used
                          functions.

Character Type

* Basic Char Syntax::       Syntax for regular characters.
* General Escape Syntax::   How to specify characters by their codes.
* Ctl-Char Syntax::         Syntax for control characters.
* Meta-Char Syntax::        Syntax for meta-characters.
* Other Char Bits::         Syntax for hyper-, super-, and alt-characters.

Cons Cell and List Types

* Box Diagrams::            Drawing pictures of lists.
* Dotted Pair Notation::    A general syntax for cons cells.
* Association List Type::   A specially constructed list.

String Type

* Syntax for Strings::      How to specify Lisp strings.
* Non-ASCII in Strings::    International characters in strings.
* Nonprinting Characters::  Literal unprintable characters in strings.
* Text Props and Strings::  Strings with text properties.

Editing Types

* Buffer Type::             The basic object of editing.
* Marker Type::             A position in a buffer.
* Window Type::             Buffers are displayed in windows.
* Frame Type::              Windows subdivide frames.
* Terminal Type::           A terminal device displays frames.
* Window Configuration Type::  Recording the way a frame is subdivided.
* Frame Configuration Type::   Recording the status of all frames.
* Process Type::            A subprocess of Emacs running on the underlying OS.
* Stream Type::             Receive or send characters.
* Keymap Type::             What function a keystroke invokes.
* Overlay Type::            How an overlay is represented.
* Font Type::               Fonts for displaying text.

Numbers

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

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.
* Modifying Strings::       Altering the contents of an existing string.
* Text Comparison::         Comparing characters or strings.
* String Conversion::       Converting to and from characters and strings.
* Formatting Strings::      `format': Emacs's analogue of `printf'.
* Case Conversion::         Case conversion functions.
* Case Tables::		    Customizing case conversion.

Lists

* Cons Cells::              How lists are made out of cons cells.
* List-related Predicates:: Is this object a list?  Comparing two lists.
* List Elements::           Extracting the pieces of a list.
* Building Lists::          Creating list structure.
* List Variables::          Modifying lists stored in variables.
* 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.
* Rings::                   Managing a fixed-size ring of objects.

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 Emacs Lisp.
* Array Functions::         Functions specifically for arrays.
* Vectors::                 Special characteristics of Emacs Lisp vectors.
* Vector Functions::        Functions specifically for vectors.
* Char-Tables::             How to work with char-tables.
* Bool-Vectors::            How to work with bool-vectors.

Hash Tables

* Creating Hash::           Functions to create hash tables.
* Hash Access::             Reading and writing the hash table contents.
* Defining Hash::           Defining new comparison methods.
* Other Hash::              Miscellaneous.

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.
* Property Lists::          Each symbol has a property list
                              for recording miscellaneous information.

Property Lists

* Plists and Alists::       Comparison of the advantages of property
                              lists and association lists.
* Symbol Plists::           Functions to access symbols' property lists.
* Other Plists::            Accessing property lists stored elsewhere.

Evaluation

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

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 Indirection::    When a symbol appears as the car of a list,
			      we find the real function via the symbol.
* 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', `when', `unless'.
* 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 Emacs 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.
* Tips for Defining::       Things you should think about when you
                              define 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.
* File Local Variables::    Handling local variable lists in files.
* Directory Local Variables:: Local variables common to all files in a
                                directory.
* Frame-Local Variables::   Frame-local bindings for variables.
* Variable Aliases::        Variables that are aliases for other variables.
* Variables with Restricted Values::  Non-constant variables whose value can
                                        _not_ be an arbitrary Lisp object.

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 buffer-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.
* Obsolete Functions::      Declaring functions obsolete.
* Inline Functions::	    Defining functions that the compiler
                              will open code.
* Declaring Functions::	    Telling the compiler that a function is defined.
* Function Safety::         Determining whether a function is safe to call.
* 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.
* Indenting Macros::        Specifying how to indent macro calls.

Common Problems Using Macros

* Wrong Time::             Do the work in the expansion, not in the macro.
* Argument Evaluation::    The expansion should evaluate each macro arg once.
* Surprising Local Vars::  Local variable bindings in the expansion
                              require special care.
* Eval During Expansion::  Don't evaluate them; put them in the expansion.
* Repeated Expansion::     Avoid depending on how many times expansion is done.

Writing Customization Definitions

* Common Keywords::         Common keyword arguments for all kinds of
                              customization declarations.
* Group Definitions::       Writing customization group definitions.
* Variable Definitions::    Declaring user options.
* Customization Types::     Specifying the type of a user option.

Customization Types

* Simple Types::            Simple customization types: sexp, integer, number,
                              string, file, directory, alist.
* Composite Types::         Build new types from other types or data.
* Splicing into Lists::     Splice elements into list with `:inline'.
* Type Keywords::           Keyword-argument pairs in a customization type.
* Defining New Types::      Give your type a name.

Loading

* How Programs Do Loading:: The `load' function and others.
* Load Suffixes::           Details about the suffixes that `load' tries.
* Library Search::          Finding a library to load.
* Loading Non-ASCII::       Non-ASCII characters in Emacs Lisp files.
* Autoload::                Setting up a function to autoload.
* Repeated Loading::        Precautions about loading a file twice.
* Named Features::          Loading a library if it isn't already loaded.
* Where Defined::           Finding which file defined a certain symbol.
* Unloading::		    How to "unload" a library that was loaded.
* Hooks for Loading::	    Providing code to be run when
			      particular libraries are loaded.

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.
* Compiler Errors::         Handling compiler error messages.
* Byte-Code Objects::	    The data type used for byte-compiled functions.
* Disassembly::             Disassembling byte-code; how to read byte-code.

Advising Emacs Lisp Functions

* Simple Advice::           A simple example to explain the basics of advice.
* Defining Advice::         Detailed description of `defadvice'.
* Around-Advice::           Wrapping advice around a function's definition.
* Computed Advice::         ...is to `defadvice' as `fset' is to `defun'.
* Activation of Advice::    Advice doesn't do anything until you activate it.
* Enabling Advice::         You can enable or disable each piece of advice.
* Preactivation::           Preactivation is a way of speeding up the
                              loading of compiled advice.
* Argument Access in Advice:: How advice can access the function's arguments.
* Advising Primitives::     Accessing arguments when advising a primitive.
* Combined Definition::     How advice is implemented.

Debugging Lisp Programs

* Debugger::                How the Emacs Lisp debugger is implemented.
* Edebug::                  A source-level Emacs Lisp debugger.
* Syntax Errors::           How to find syntax errors.
* Test Coverage::           Ensuring you have tested all branches in your code.
* Compilation Errors::      How to find errors that show up in
                              byte compilation.

The Lisp Debugger

* Error Debugging::         Entering the debugger when an error happens.
* Infinite Loops::	    Stopping and debugging a program that doesn't exit.
* 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.

Edebug

* Using Edebug::	    Introduction to use of Edebug.
* Instrumenting::	    You must instrument your code
			      in order to debug it with Edebug.
* Edebug Execution Modes::  Execution modes, stopping more or less often.
* Jumping::		    Commands to jump to a specified place.
* Edebug Misc::		    Miscellaneous commands.
* Breaks::		    Setting breakpoints to make the program stop.
* Trapping Errors::	    Trapping errors with Edebug.
* Edebug Views::	    Views inside and outside of Edebug.
* Edebug Eval::		    Evaluating expressions within Edebug.
* Eval List::		    Expressions whose values are displayed
			      each time you enter Edebug.
* Printing in Edebug::	    Customization of printing.
* Trace Buffer::	    How to produce trace output in a buffer.
* Coverage Testing::	    How to test evaluation coverage.
* The Outside Context::	    Data that Edebug saves and restores.
* Edebug and Macros::       Specifying how to handle macro calls.
* Edebug Options::	    Option variables for customizing Edebug.

Breaks

* Breakpoints::             Breakpoints at stop points.
* Global Break Condition::  Breaking on an event.
* Source Breakpoints::      Embedding breakpoints in source code.

The Outside Context

* Checking Whether to Stop::When Edebug decides what to do.
* Edebug Display Update::   When Edebug updates the display.
* Edebug Recursive Edit::   When Edebug stops execution.

Edebug and Macros

* Instrumenting Macro Calls::The basic problem.
* Specification List::	    How to specify complex patterns of evaluation.
* Backtracking::	    What Edebug does when matching fails.
* Specification Examples::  To help understand specifications.

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.
* Output Variables::        Variables that control what the printing
                              functions do.

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.
* Minibuffer History::	    Recording previous minibuffer inputs
			      so the user can reuse them.
* Initial Input::           Specifying initial contents for the minibuffer.
* Completion::              How to invoke and customize completion.
* Yes-or-No Queries::       Asking a question with a simple answer.
* Multiple Queries::	    Asking a series of similar questions.
* Reading a Password::	    Reading a password from the terminal.
* Minibuffer Commands::     Commands used as key bindings in minibuffers.
* Minibuffer Contents::     How such commands access the minibuffer text.
* Minibuffer Windows::      Operating on the special minibuffer windows.
* Recursive Mini::          Whether recursive entry to minibuffer is allowed.
* 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 and
                              shell commands.
* Completion Styles::       Specifying rules for performing completion.
* Programmed Completion::   Writing your own completion-function.

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.
* Distinguish Interactive::     Making a command distinguish interactive calls.
* Command Loop Info::   Variables set by the command loop for you to examine.
* Adjusting Point::     Adjustment of point after a command.
* Input Events::	What input looks like when you read it.
* Reading Input::       How to read input events from the keyboard or mouse.
* Special Events::      Events processed immediately and individually.
* 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.

Input Events

* Keyboard Events::         Ordinary characters--keys with symbols on them.
* Function Keys::           Function keys--keys with names, not symbols.
* Mouse Events::            Overview of mouse events.
* Click Events::            Pushing and releasing a mouse button.
* Drag Events::             Moving the mouse before releasing the button.
* Button-Down Events::      A button was pushed and not yet released.
* Repeat Events::           Double and triple click (or drag, or down).
* Motion Events::           Just moving the mouse, not pushing a button.
* Focus Events::            Moving the mouse between frames.
* Misc Events::             Other events the system can generate.
* Event Examples::          Examples of the lists for mouse events.
* Classifying Events::      Finding the modifier keys in an event symbol.
                              Event types.
* Accessing Mouse::	    Functions to extract info from mouse events.
* Accessing Scroll::        Functions to get info from scroll bar events.
* Strings of Events::       Special considerations for putting
                              keyboard character events in a string.

Reading Input

* Key Sequence Input::      How to read one key sequence.
* Reading One Event::       How to read just one event.
* Event Mod::               How Emacs modifies events as they are read.
* Invoking the Input Method::   How reading an event uses the input method.
* Quoted Character Input::  Asking the user to specify a character.
* Event Input Misc::        How to reread or throw away input events.

Keymaps

* Key Sequences::           Key sequences as Lisp objects.
* Keymap Basics::           Basic concepts of 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.
* Prefix Keys::             Defining a key with a keymap as its definition.
* Active Keymaps::          How Emacs searches the active keymaps
                              for a key binding.
* Searching Keymaps::       A pseudo-Lisp summary of searching active maps.
* Controlling Active Maps:: Each buffer has a local keymap
                               to override the standard (global) bindings.
                               A minor mode can also override them.
* Key Lookup::              Finding a key's binding in one keymap.
* Functions for Key Lookup::    How to request key lookup.
* Changing Key Bindings::   Redefining a key in a keymap.
* Remapping Commands::      A keymap can translate one command to another.
* Translation Keymaps::     Keymaps for translating sequences of events.
* Key Binding Commands::    Interactive interfaces for redefining keys.
* Scanning Keymaps::        Looking through all keymaps, for printing help.
* Menu Keymaps::            Defining a menu as a keymap.

Menu Keymaps

* Defining Menus::          How to make a keymap that defines a menu.
* Mouse Menus::             How users actuate the menu with the mouse.
* Keyboard Menus::          How users actuate the menu with the keyboard.
* Menu Example::            Making a simple menu.
* Menu Bar::                How to customize the menu bar.
* Tool Bar::                A tool bar is a row of images.
* Modifying Menus::         How to add new items to a menu.

Defining Menus

* Simple Menu Items::       A simple kind of menu key binding,
                              limited in capabilities.
* Extended Menu Items::     More powerful menu item definitions
                              let you specify keywords to enable
                              various features.
* Menu Separators::         Drawing a horizontal line through a menu.
* Alias Menu Items::        Using command aliases in menu items.

Major and Minor Modes

* Hooks::              How to use hooks; how to write code that provides hooks.
* Major Modes::        Defining major modes.
* Minor Modes::        Defining minor modes.
* Mode Line Format::   Customizing the text that appears in the mode line.
* Imenu::              How a mode can provide a menu
                         of definitions in the buffer.
* Font Lock Mode::     How modes can highlight text according to syntax.
* Desktop Save Mode::  How modes can have buffer state saved between
                         Emacs sessions.

Hooks

* Running Hooks::      How to run a hook.
* Setting Hooks::      How to put functions on a hook, or remove them.

Major Modes

* Major Mode Basics::
* Major Mode Conventions::  Coding conventions for keymaps, etc.
* Auto Major Mode::         How Emacs chooses the major mode automatically.
* Mode Help::               Finding out how to use a mode.
* Derived Modes::           Defining a new major mode based on another major
                              mode.
* Generic Modes::           Defining a simple major mode that supports
                              comment syntax and Font Lock mode.
* Mode Hooks::              Hooks run at the end of major mode functions.
* Example Major Modes::     Text mode and Lisp modes.

Minor Modes

* Minor Mode Conventions::  Tips for writing a minor mode.
* Keymaps and Minor Modes:: How a minor mode can have its own keymap.
* Defining Minor Modes::    A convenient facility for defining minor modes.

Mode Line Format

* Mode Line Basics::        Basic ideas of mode line control.
* Mode Line Data::          The data structure that controls the mode line.
* Mode Line Top::           The top level variable, mode-line-format.
* Mode Line Variables::     Variables used in that data structure.
* %-Constructs::            Putting information into a mode line.
* Properties in Mode::      Using text properties in the mode line.
* Header Lines::            Like a mode line, but at the top.
* Emulating Mode Line::     Formatting text as the mode line would.

Font Lock Mode

* Font Lock Basics::        Overview of customizing Font Lock.
* Search-based Fontification::  Fontification based on regexps.
* Customizing Keywords::    Customizing search-based fontification.
* Other Font Lock Variables::   Additional customization facilities.
* Levels of Font Lock::     Each mode can define alternative levels
                              so that the user can select more or less.
* Precalculated Fontification:: How Lisp programs that produce the buffer
                                  contents can also specify how to fontify it.
* Faces for Font Lock::     Special faces specifically for Font Lock.
* Syntactic Font Lock::     Fontification based on syntax tables.
* Setting Syntax Properties::   Defining character syntax based on context
                                  using the Font Lock mechanism.
* Multiline Font Lock::     How to coerce Font Lock into properly
                              highlighting multiline constructs.

Multiline Font Lock Constructs

* Font Lock Multiline::     Marking multiline chunks with a text property.
* Region to Fontify::       Controlling which region gets refontified
                              after a buffer change.

Documentation

* Documentation Basics::    Good style for doc strings.
                              Where to put them.  How Emacs 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 Emacs 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 buffers without visiting.
* 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.
* Changing Files::          Renaming files, changing protection, etc.
* File Names::              Decomposing and expanding file names.
* Contents of Directories:: Getting a list of the files in a directory.
* Create/Delete Dirs::	    Creating and Deleting Directories.
* Magic File Names::	    Defining "magic" special handling
			      for certain file names.
* Format Conversion::       Conversion to and from various file formats.

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 symbolic link?
* Truenames::		    Eliminating symbolic links from a file name.
* File Attributes::         How large is it?  Any other names?  Etc.
* Locating Files::          How to find a file in standard places.

File Names

* File Name Components::    The directory part of a file name, and the rest.
* Relative File Names::     Some file names are relative to a current directory.
* Directory Names::         A directory's name as a directory
                              is different from its name as a file.
* 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.
* Standard File Names::     If your package uses a fixed file name,
                              how to handle various operating systems simply.

File Format Conversion

* Format Conversion Overview::   `insert-file-contents' and `write-region'.
* Format Conversion Round-Trip:: Using `format-alist'.
* Format Conversion Piecemeal::  Specifying non-paired conversion.

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 Emacs 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?
* Current Buffer::          Designating a buffer as current
                              so that primitives will access its contents.
* 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 Emacs'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.
* Indirect Buffers::        An indirect buffer shares text with some
                              other buffer.
* Swapping Text::           Swapping text between two buffers.
* Buffer Gap::              The gap in the buffer.

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-level functions for displaying a buffer
                              and choosing a window for it.
* Choosing Window::	    How to choose a window for displaying a buffer.
* Dedicated Windows::	    How to avoid displaying another buffer in
                              a specific window.
* Window Point::            Each window has its own location of point.
* Window Start and End::    Buffer positions indicating which text is
                              on-screen in a window.
* Textual Scrolling::       Moving text up and down through the window.
* Vertical Scrolling::      Moving the contents up and down on the window.
* Horizontal Scrolling::    Moving the contents sideways on the window.
* Size of Window::          Accessing the size of a window.
* Resizing Windows::        Changing the size of a window.
* Coordinates and Windows:: Converting coordinates to windows.
* Window Tree::             The layout and sizes of all windows in a frame.
* Window Configurations::   Saving and restoring the state of the screen.
* Window Parameters::       Associating additional information with windows.
* Window Hooks::            Hooks for scrolling, window size changes,
                              redisplay going past a certain point,
                              or window configuration changes.

Frames

* Creating Frames::	    Creating additional frames.
* Multiple Terminals::      Displaying on several different devices.
* Frame Parameters::	    Controlling frame size, position, font, etc.
* Terminal Parameters::     Parameters common for all frames on terminal.
* 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 windows;
			      lowering it makes the others hide it.
* Frame Configurations::    Saving the state of all frames.
* Mouse Tracking::	    Getting events that say when the mouse moves.
* Mouse Position::	    Asking where the mouse is, or moving it.
* Pop-Up Menus::	    Displaying a menu for the user to select from.
* Dialog Boxes::            Displaying a box to ask yes or no.
* Pointer Shape::           Specifying the shape of the mouse pointer.
* Window System Selections::Transferring text to and from other X clients.
* Drag and Drop::               Internals of Drag-and-Drop implementation.
* Color Names::	            Getting the definitions of color names.
* Text Terminal Colors::    Defining colors for text-only terminals.
* Resources::		    Getting resource values from the server.
* Display Feature Testing:: Determining the features of a terminal.

Frame Parameters

* Parameter Access::        How to change a frame's parameters.
* Initial Parameters::	    Specifying frame parameters when you make a frame.
* Window Frame Parameters:: List of frame parameters for window systems.
* Size and Position::       Changing the size and position of a frame.
* Geometry::                Parsing geometry specifications.

Window Frame Parameters

* Basic Parameters::        Parameters that are fundamental.
* Position Parameters::     The position of the frame on the screen.
* Size Parameters::         Frame's size.
* Layout Parameters::       Size of parts of the frame, and
                              enabling or disabling some parts.
* Buffer Parameters::       Which buffers have been or should be shown.
* Management Parameters::   Communicating with the window manager.
* Cursor Parameters::       Controlling the cursor appearance.
* Font and Color Parameters:: Fonts and colors for the frame text.

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.
* Marker Insertion Types::  Two ways a marker can relocate when you
                              insert where it points.
* Moving 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.
* Adaptive Fill::           Adaptive Fill mode chooses a fill prefix
                              from context.
* 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.
* Transposition::           Swapping two portions of a buffer.
* Registers::               How registers are implemented.  Accessing
                              the text or position stored in a register.
* Base 64::                 Conversion to or from base 64 encoding.
* MD5 Checksum::            Compute the MD5 "message digest"/"checksum".
* Atomic Changes::          Installing several buffer changes "atomically".
* 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.
* Yanking::                 How yanking is done.
* 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.

Text Properties

* Examining Properties::    Looking at the properties of one character.
* Changing Properties::	    Setting the properties of a range of text.
* Property Search::	    Searching for where a property changes value.
* Special Properties::	    Particular properties with special meanings.
* Format Properties::       Properties for representing formatting of text.
* Sticky Properties::       How inserted text gets properties from
                              neighboring text.
* Lazy Properties::         Computing text properties in a lazy fashion
                              only when text is examined.
* Clickable Text::          Using text properties to make regions of text
                              do something when you click on them.
* Fields::                  The `field' property defines
                              fields within the buffer.
* Not Intervals::	    Why text properties do not use
			      Lisp-visible text intervals.

Non-ASCII Characters

* Text Representations::    How Emacs represents text.
* Converting Representations::  Converting unibyte to multibyte and vice versa.
* Selecting a Representation::  Treating a byte sequence as unibyte or multi.
* Character Codes::         How unibyte and multibyte relate to
                                codes of individual characters.
* Character Properties::    Character attributes that define their
                                behavior and handling.
* Character Sets::          The space of possible character codes
                                is divided into various character sets.
* Scanning Charsets::       Which character sets are used in a buffer?
* Translation of Characters::   Translation tables are used for conversion.
* Coding Systems::          Coding systems are conversions for saving files.
* Input Methods::           Input methods allow users to enter various
                                non-ASCII characters without special keyboards.
* Locales::                 Interacting with the POSIX locale.

Coding Systems

* Coding System Basics::    Basic concepts.
* Encoding and I/O::        How file I/O functions handle coding systems.
* Lisp and Coding Systems:: Functions to operate on coding system names.
* User-Chosen Coding Systems::  Asking the user to choose a coding system.
* Default Coding Systems::  Controlling the default choices.
* Specifying Coding Systems::   Requesting a particular coding system
                                    for a single file operation.
* Explicit Encoding::       Encoding or decoding text without doing I/O.
* Terminal I/O Encoding::   Use of encoding for terminal I/O.
* MS-DOS File Types::       How DOS "text" and "binary" files
                                relate to coding systems.

Searching and Matching

* String Search::           Search for an exact match.
* Searching and Case::      Case-independent or case-significant searching.
* Regular Expressions::     Describing classes of strings.
* Regexp Search::           Searching for a match for a regexp.
* POSIX Regexps::           Searching POSIX-style for the longest match.
* Match Data::              Finding out which part of the text matched,
                              after a string or regexp search.
* Search and Replace::	    Commands that loop, searching and replacing.
* Standard Regexps::        Useful regexps for finding sentences, pages,...

Regular Expressions

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

Syntax of Regular Expressions

* Regexp Special::          Special characters in regular expressions.
* Char Classes::            Character classes used in regular expressions.
* Regexp Backslash::        Backslash-sequences in regular expressions.

The Match Data

* Replacing Match::	    Replacing a substring that was matched.
* Simple Match Data::       Accessing single items of match data,
			      such as where a particular subexpression started.
* Entire Match Data::       Accessing the entire match data at once, as a list.
* Saving Match Data::       Saving and restoring the match data.

Syntax Tables

* Syntax Basics::           Basic concepts of syntax tables.
* Syntax Descriptors::      How characters are classified.
* Syntax Table Functions::  How to create, examine and alter syntax tables.
* Syntax Properties::       Overriding syntax with text properties.
* Motion and Syntax::	    Moving over characters with certain syntaxes.
* 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.
* Categories::              Another way of classifying character syntax.

Syntax Descriptors

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

Parsing Expressions

* Motion via Parsing::      Motion functions that work by parsing.
* Position Parse::          Determining the syntactic state of a position.
* Parser State::            How Emacs represents a syntactic state.
* Low-Level Parsing::       Parsing across a specified region.
* Control Parsing::         Parameters that affect parsing.

Abbrevs and Abbrev Expansion

* Abbrev Mode::             Setting up Emacs for abbreviation.
* Abbrev Tables::           Creating and working with abbrev tables.
* Defining Abbrevs::        Specifying abbreviations and their expansions.
* Abbrev Files::            Saving abbrevs in files.
* Abbrev Expansion::        Controlling expansion; expansion subroutines.
* Standard Abbrev Tables::  Abbrev tables used by various major modes.
* Abbrev Properties::       How to read and set abbrev properties.
                            Which properties have which effect.
* Abbrev Table Properties:: How to read and set abbrev table properties.
                            Which properties have which effect.

Processes

* Subprocess Creation::     Functions that start subprocesses.
* Shell Arguments::         Quoting an argument to pass it to a shell.
* 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.
* Query Before Exit::       Whether to query if exiting will kill a process.
* System Processes::        Accessing other processes running on your system.
* Transaction Queues::      Transaction-based communication with subprocesses.
* Network::                 Opening network connections.
* Network Servers::         Network servers let Emacs accept net connections.
* Datagrams::               UDP network connections.
* Low-Level Network::       Lower-level but more general function
                              to create connections and servers.
* Misc Network::            Additional relevant functions for
                              network connections.
* Serial Ports::            Communicating with serial ports.
* Byte Packing::            Using bindat to pack and unpack binary data.

Receiving Output from Processes

* Process Buffers::         If no filter, output is put in a buffer.
* Filter Functions::        Filter functions accept output from the process.
* Decoding Output::         Filters can get unibyte or multibyte strings.
* Accepting Output::        How to wait until process output arrives.

Low-Level Network Access

* Network Processes::       Using `make-network-process'.
* Network Options::         Further control over network connections.
* Network Feature Testing:: Determining which network features work on
                              the machine you are using.

Packing and Unpacking Byte Arrays

* Bindat Spec::             Describing data layout.
* Bindat Functions::        Doing the unpacking and packing.
* Bindat Examples::         Samples of what bindat.el can do for you!

Emacs Display

* Refresh Screen::          Clearing the screen and redrawing everything on it.
* Forcing Redisplay::       Forcing redisplay.
* Truncation::              Folding or wrapping long text lines.
* The Echo Area::           Displaying messages at the bottom of the screen.
* Warnings::                Displaying warning messages for the user.
* Invisible Text::          Hiding part of the buffer text.
* Selective Display::       Hiding part of the buffer text (the old way).
* Temporary Displays::      Displays that go away automatically.
* Overlays::		    Use overlays to highlight parts of the buffer.
* Width::                   How wide a character or string is on the screen.
* Line Height::             Controlling the height of lines.
* Faces::		    A face defines a graphics style
                              for text characters: font, colors, etc.
* Fringes::                 Controlling window fringes.
* Scroll Bars::             Controlling vertical scroll bars.
* Display Property::        Enabling special display features.
* Images::                  Displaying images in Emacs buffers.
* Buttons::                 Adding clickable buttons to Emacs buffers.
* Abstract Display::        Emacs' Widget for Object Collections.
* Blinking::                How Emacs 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.
* Window Systems::          Which window system is being used.

The Echo Area

* Displaying Messages::     Explicitly displaying text in the echo area.
* Progress::                Informing user about progress of a long operation.
* Logging Messages::        Echo area messages are logged for the user.
* Echo Area Customization:: Controlling the echo area.

Reporting Warnings

* Warning Basics::          Warnings concepts and functions to report them.
* Warning Variables::       Variables programs bind to customize
                              their warnings.
* Warning Options::         Variables users set to control display of warnings.

Overlays

* Managing Overlays::       Creating and moving overlays.
* Overlay Properties::      How to read and set properties.
			    What properties do to the screen display.
* Finding Overlays::        Searching for overlays.

Faces

* Defining Faces::          How to define a face with `defface'.
* Face Attributes::         What is in a face?
* Attribute Functions::     Functions to examine and set face attributes.
* Displaying Faces::        How Emacs combines the faces specified for
                              a character.
* Face Remapping::         Remapping faces to alternative definitions.
* Face Functions::          How to define and examine faces.
* Auto Faces::              Hook for automatic face assignment.
* Font Selection::          Finding the best available font for a face.
* Font Lookup::             Looking up the names of available fonts
                              and information about them.
* Fontsets::                A fontset is a collection of fonts
                              that handle a range of character sets.
* Low-Level Font::          Lisp representation for character display fonts.

Fringes

* Fringe Size/Pos::         Specifying where to put the window fringes.
* Fringe Indicators::       Displaying indicator icons in the window fringes.
* Fringe Cursors::          Displaying cursors in the right fringe.
* Fringe Bitmaps::          Specifying bitmaps for fringe indicators.
* Customizing Bitmaps::     Specifying your own bitmaps to use in the fringes.
* Overlay Arrow::           Display of an arrow to indicate position.

The `display' Property

* Replacing Specs::         Display specs that replace the text.
* Specified Space::         Displaying one space with a specified width.
* Pixel Specification::     Specifying space width or height in pixels.
* Other Display Specs::     Displaying an image; magnifying text; moving it
                              up or down on the page; adjusting the width
                              of spaces within text.
* Display Margins::         Displaying text or images to the side of
                              the main text.

Images

* Image Formats::           Supported image formats.
* Image Descriptors::       How to specify an image for use in `:display'.
* XBM Images::              Special features for XBM format.
* XPM Images::              Special features for XPM format.
* GIF Images::              Special features for GIF format.
* TIFF Images::             Special features for TIFF format.
* PostScript Images::       Special features for PostScript format.
* Other Image Types::       Various other formats are supported.
* Defining Images::         Convenient ways to define an image for later use.
* Showing Images::          Convenient ways to display an image once
                              it is defined.
* Image Cache::             Internal mechanisms of image display.

Buttons

* Button Properties::       Button properties with special meanings.
* Button Types::            Defining common properties for classes of buttons.
* Making Buttons::          Adding buttons to Emacs buffers.
* Manipulating Buttons::    Getting and setting properties of buttons.
* Button Buffer Commands::  Buffer-wide commands and bindings for buttons.

Abstract Display

* Abstract Display Functions::  Functions in the Ewoc package.
* Abstract Display Example::    Example of using Ewoc.

Display Tables

* Display Table Format::    What a display table consists of.
* Active Display Table::    How Emacs selects a display table to use.
* Glyphs::                  How to define a glyph, and what glyphs mean.

Operating System Interface

* Starting Up::             Customizing Emacs startup processing.
* Getting Out::             How exiting works (permanent or temporary).
* System Environment::      Distinguish the name and kind of system.
* User Identification::     Finding the name and user id of the user.
* Time of Day::		    Getting the current time.
* Time Conversion::         Converting a time from numeric form to
                              calendrical data and vice versa.
* Time Parsing::            Converting a time from numeric form to text
                              and vice versa.
* Processor Run Time::      Getting the run time used by Emacs.
* Time Calculations::       Adding, subtracting, comparing times, etc.
* Timers::		    Setting a timer to call a function at a
                              certain time.
* Idle Timers::             Setting a timer to call a function when Emacs has
                              been idle for a certain length of time.
* Terminal Input::          Accessing and recording terminal input.
* Terminal Output::         Controlling and recording terminal output.
* Sound Output::            Playing sounds on the computer's speaker.
* X11 Keysyms::             Operating on key symbols for X Windows.
* Batch Mode::              Running Emacs without terminal interaction.
* Session Management::      Saving and restoring state with
                              X Session Management.

Starting Up Emacs

* Startup Summary::         Sequence of actions Emacs performs at startup.
* Init File::               Details on reading the init file.
* 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 Emacs

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

Terminal Input

* Input Modes::		    Options for how input is processed.
* Recording Input::	    Saving histories of recent or all input events.

Tips and Conventions

* Coding Conventions::      Conventions for clean and robust programs.
* Key Binding Conventions:: Which keys should be bound by which programs.
* Programming Tips::        Making Emacs code fit smoothly in Emacs.
* Compilation Tips::        Making compiled code run fast.
* Warning Tips::            Turning off compiler warnings.
* Documentation Tips::      Writing readable documentation strings.
* Comment Tips::	    Conventions for writing comments.
* Library Headers::         Standard headers for library packages.

GNU Emacs Internals

* Building Emacs::          How the dumped Emacs is made.
* Pure Storage::            A kludge to make preloaded Lisp functions sharable.
* Garbage Collection::      Reclaiming space for Lisp objects no longer used.
* Memory Usage::            Info about total size of Lisp objects made so far.
* Writing Emacs Primitives::  Writing C code for Emacs.
* Object Internals::        Data formats of buffers, windows, processes.

Object Internals

* Buffer Internals::        Components of a buffer structure.
* Window Internals::        Components of a window structure.
* Process Internals::       Components of a process structure.

File: elisp,  Node: Introduction,  Next: Lisp Data Types,  Prev: Top,  Up: Top

1 Introduction
**************

Most of the GNU Emacs text editor is written in the programming
language called Emacs Lisp.  You can write new code in Emacs Lisp and
install it as an extension to the editor.  However, Emacs 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 Emacs 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.  Emacs 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 attempts to be a full description of Emacs Lisp.  For a
beginner's introduction to Emacs Lisp, see `An Introduction to Emacs
Lisp Programming', by Bob Chassell, also published by the Free Software
Foundation.  This manual presumes considerable familiarity with the use
of Emacs for editing; see `The GNU Emacs Manual' for this basic
information.

   Generally speaking, the earlier chapters describe features of Emacs
Lisp that have counterparts in many programming languages, and later
chapters describe features that are peculiar to Emacs Lisp or relate
specifically to editing.

   This is edition 3.0 of the GNU Emacs Lisp Reference Manual,
corresponding to Emacs version 23.1.

* Menu:

* Caveats::             Flaws and a request for help.
* Lisp History::        Emacs Lisp is descended from Maclisp.
* Conventions::         How the manual is formatted.
* Version Info::        Which Emacs version is running?
* Acknowledgements::    The authors, editors, and sponsors of this manual.

File: elisp,  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 you are criticizing.

   Please send comments and corrections using `M-x report-emacs-bug'.

File: elisp,  Node: Lisp History,  Next: Conventions,  Prev: Caveats,  Up: Introduction

1.2 Lisp History
================

Lisp (LISt Processing language) was first developed in the late 1950s
at the Massachusetts Institute of Technology for research in artificial
intelligence.  The great power of the Lisp language makes it ideal 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 1960s 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.  In the meantime, Gerry
Sussman and Guy Steele at MIT developed a simplified but very powerful
dialect of Lisp, called Scheme.

   GNU Emacs Lisp is largely inspired by Maclisp, and a little by Common
Lisp.  If you know Common Lisp, you will notice many similarities.
However, many features of Common Lisp have been omitted or simplified
in order to reduce the memory requirements of GNU Emacs.  Sometimes the
simplifications are so drastic that a Common Lisp user might be very
confused.  We will occasionally point out how GNU Emacs Lisp differs
from Common Lisp.  If you don't know Common Lisp, don't worry about it;
this manual is self-contained.

   A certain amount of Common Lisp emulation is available via the `cl'
library.  *note Overview: (cl)Top.

   Emacs Lisp is not at all influenced by Scheme; but the GNU project
has an implementation of Scheme, called Guile.  We use Guile in all new
GNU software that calls for extensibility.

File: elisp,  Node: Conventions,  Next: Version Info,  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 when examples print text.
* 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: elisp,  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" 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 are formatted like this: `(list 1 2 3)'.
Names that represent metasyntactic variables, or arguments to a function
being described, are formatted like this: FIRST-NUMBER.

File: elisp,  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 write `()' when we wish to emphasize that it
means the empty list, and we write `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
     (setq foo-flag 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 the value `t'.

   In Emacs 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 Constant
Variables::.

 -- Function: booleanp object
     Return non-`nil' if OBJECT is one of the two canonical boolean
     values: `t' or `nil'.

File: elisp,  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 result of the evaluation of the expanded form.

     (third '(a b c))
          ==> (car (cdr (cdr '(a b c))))
          => c

   Sometimes to help describe one form we show another form that
produces identical results.  The exact equivalence of two forms is
indicated with `=='.

     (make-sparse-keymap) == (list 'keymap)

File: elisp,  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.

   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 with `=>'.

     (progn (prin1 'foo) (princ "\n") (prin1 'bar))
          -| foo
          -| bar
          => bar

File: elisp,  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: number-or-marker-p, x

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

1.3.6 Buffer Text Notation
--------------------------

Some examples describe modifications to the contents of a buffer, by
showing the "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 currently 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: elisp,  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: elisp,  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 argument
names.  These names are also used in the body of the description, to
stand for the values of the arguments.

   The appearance of the keyword `&optional' in the argument list
indicates that the subsequent arguments may be omitted (omitted
arguments default to `nil').  Do not write `&optional' when you call
the function.

   The keyword `&rest' (which must be followed by a single argument
name) indicates that any number of arguments can follow.  The single
argument name following `&rest' will receive, as its value, a list of
all the remaining arguments passed to the function.  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 argument 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.
Arguments named OBJECT may be of any type.  (*Note Lisp Data Types::,
for a list of Emacs object types.)  Arguments with other sorts of names
(e.g., NEW-FILE) are discussed specifically in the description of the
function.  In some sections, features common to the arguments 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 arguments 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 one (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, 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: elisp,  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 nearly all
variables can be set by the user, certain variables exist specifically
so that users can change them; these 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: elisp,  Node: Version Info,  Next: Acknowledgements,  Prev: Conventions,  Up: Introduction

1.4 Version Information
=======================

These facilities provide information about which version of Emacs is in
use.

 -- Command: emacs-version &optional here
     This function returns a string describing the version of Emacs
     that is running.  It is useful to include this string in bug
     reports.

          (emacs-version)
            => "GNU Emacs 23.1 (i686-pc-linux-gnu, GTK+ Version 2.14.4)
                       of 2009-06-01 on cyd.mit.edu"

     If HERE is non-`nil', it inserts the text in the buffer before
     point, and returns `nil'.  When this function is called
     interactively, it prints the same information in the echo area, but
     giving a prefix argument makes HERE non-`nil'.

 -- Variable: emacs-build-time
     The value of this variable indicates the time at which Emacs was
     built at the local site.  It is a list of three integers, like the
     value of `current-time' (*note Time of Day::).

          emacs-build-time
               => (18846 52016 156039)

 -- Variable: emacs-version
     The value of this variable is the version of Emacs being run.  It
     is a string such as `"23.1.1"'.  The last number in this string is
     not really part of the Emacs release version number; it is
     incremented each time you build Emacs in any given directory.  A
     value with four numeric components, such as `"22.0.91.1"',
     indicates an unreleased test version.

   The following two variables have existed since Emacs version 19.23:

 -- Variable: emacs-major-version
     The major version number of Emacs, as an integer.  For Emacs
     version 23.1, the value is 23.

 -- Variable: emacs-minor-version
     The minor version number of Emacs, as an integer.  For Emacs
     version 23.1, the value is 1.

File: elisp,  Node: Acknowledgements,  Prev: Version Info,  Up: Introduction

1.5 Acknowledgements
====================

This manual was 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.  Additional sections
were written by Miles Bader, Lars Brinkhoff, Chong Yidong, Kenichi
Handa, Lute Kamstra, Juri Linkov, Glenn Morris, Thien-Thi Nguyen, Dan
Nicolaescu, Martin Rudalics, Kim F. Storm, Luc Teirlinck, and Eli
Zaretskii.

   Corrections were supplied by Drew Adams, Juanma Barranquero, 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, Jesper
Harder, 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, Stefan Monnier, Skip
Montanaro, John Gardiner Myers, Thomas A. Peterson, Francesco Potorti,
Friedrich Pukelsheim, Arnold D. Robbins, Raul Rockwell, Jason Rumney,
Per Starba"ck, Shinichirou Sugou, Kimmo Suominen, Edward Tharp, Bill
Trost, Rickard Westman, Jean White, Eduard Wiebe, Matthew Wilding, Carl
Witty, Dale Worley, Rusty Wright, and David D. Zuhn.

File: elisp,  Node: Lisp Data Types,  Next: Numbers,  Prev: Introduction,  Up: Top

2 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 Emacs.  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", "float", "cons", "symbol", "string", "vector",
"hash-table", "subr", and "byte-code function", plus 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.

   Lisp is unlike many other languages in that its objects are
"self-typing": the primitive type of each 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 Emacs Lisp.  A Lisp
variable can have any type of value, and it remembers whatever value
you store in it, type and all.  (Actually, a small number of Emacs Lisp
variables can only take on values of a certain type.  *Note Variables
with Restricted Values::.)

   This chapter describes the purpose, printed representation, and read
syntax of each of the standard types in GNU 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.
* Programming Types::           Types found in all Lisp systems.
* Editing Types::               Types specific to Emacs.
* Circular Objects::            Read syntax for circular structure.
* Type Predicates::             Tests related to types.
* Equality Predicates::         Tests of equality between any two objects.

File: elisp,  Node: Printed Representation,  Next: Comments,  Up: Lisp Data Types

2.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.
Every data type has a unique printed representation.  The "read syntax"
of an object is the format of the input accepted by the Lisp reader
(the function `read') for that object.  This is not necessarily unique;
many kinds of object have more than one syntax.  *Note Read and Print::.

   In most cases, an object's printed representation is also a read
syntax for the object.  However, some types have no read syntax, since
it does not make sense to enter objects of these types as constants in
a Lisp program.  These objects are printed in "hash notation", which
consists of the characters `#<', a descriptive string (typically the
type name followed by the name of the object), and a closing `>'.  For
example:

     (current-buffer)
          => #<buffer objects.texi>

Hash notation cannot be read at all, so the Lisp reader signals the
error `invalid-read-syntax' whenever it encounters `#<'.

   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.

   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: elisp,  Node: Comments,  Next: Programming Types,  Prev: Printed Representation,  Up: Lisp Data Types

2.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
Emacs 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: elisp,  Node: Programming Types,  Next: Editing Types,  Prev: Comments,  Up: Lisp Data Types

2.3 Programming Types
=====================

There are two general categories of types in Emacs 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 Emacs 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.
* Char-Table Type::     One-dimensional sparse arrays indexed by characters.
* Bool-Vector Type::    One-dimensional arrays of `t' or `nil'.
* Hash Table Type::     Super-fast lookup tables.
* 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.
* Byte-Code Type::      A function written in Lisp, then compiled.
* Autoload Type::       A type used for automatically loading seldom-used
                        functions.

File: elisp,  Node: Integer Type,  Next: Floating Point Type,  Up: Programming Types

2.3.1 Integer Type
------------------

The range of values for integers in Emacs Lisp is -268435456 to
268435455 (29 bits; i.e., -2**28 to 2**28 - 1) on most machines.  (Some
machines may provide a wider range.)  It is important to note that the
Emacs Lisp arithmetic functions do not check for overflow.  Thus `(1+
268435455)' is -268435456 on most machines.

   The read syntax for integers is a sequence of (base ten) digits with
an optional sign at the beginning and an optional period at the end.
The printed representation produced by the Lisp interpreter never has a
leading `+' or a final `.'.

     -1               ; The integer -1.
     1                ; The integer 1.
     1.               ; Also the integer 1.
     +1               ; Also the integer 1.
     536870913        ; Also the integer 1 on a 29-bit implementation.

   *Note Numbers::, for more information.

File: elisp,  Node: Floating Point Type,  Next: Character Type,  Prev: Integer Type,  Up: Programming Types

2.3.2 Floating Point Type
-------------------------

Floating point numbers are the computer equivalent of scientific
notation; you can think of a floating point number as a fraction
together with a power of ten.  The precise number of significant
figures and the range of possible exponents is machine-specific; Emacs
uses the C data type `double' to store the value, and internally this
records a power of 2 rather than a power of 10.

   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: elisp,  Node: Character Type,  Next: Symbol Type,  Prev: Floating Point Type,  Up: Programming Types

2.3.3 Character Type
--------------------

A "character" in Emacs Lisp is nothing more than an integer.  In other
words, characters are represented by their character codes.  For
example, the character `A' is represented as the integer 65.

   Individual characters are used occasionally in programs, but it is
more common to work with _strings_, which are sequences composed of
characters.  *Note String Type::.

   Characters in strings and buffers are currently limited to the range
of 0 to 4194303--twenty two bits (*note Character Codes::).  Codes 0
through 127 are ASCII codes; the rest are non-ASCII (*note Non-ASCII
Characters::).  Characters that represent keyboard input have a much
wider range, to encode modifier keys such as Control, Meta and Shift.

   There are special functions for producing a human-readable textual
description of a character for the sake of messages.  *Note Describing
Characters::.

* Menu:

* Basic Char Syntax::      Syntax for regular characters.
* General Escape Syntax::  How to specify characters by their codes.
* Ctl-Char Syntax::        Syntax for control characters.
* Meta-Char Syntax::       Syntax for meta-characters.
* Other Char Bits::        Syntax for hyper-, super-, and alt-characters.

File: elisp,  Node: Basic Char Syntax,  Next: General Escape Syntax,  Up: Character Type

2.3.3.1 Basic Char Syntax
.........................

Since 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 not
clear programming.  You should _always_ use the special read syntax
formats that Emacs Lisp provides for characters.  These syntax formats
start with a question mark.

   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:

     ?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 open-paren character.  If the character is `\', you _must_ use a
second `\' to quote it: `?\\'.

   You can express the characters control-g, backspace, tab, newline,
vertical tab, formfeed, space, return, del, and escape as `?\a', `?\b',
`?\t', `?\n', `?\v', `?\f', `?\s', `?\r', `?\d', and `?\e',
respectively.  (`?\s' followed by a dash has a different meaning--it
applies the "super" modifier to the following character.)  Thus,

     ?\a => 7                 ; control-g, `C-g'
     ?\b => 8                 ; backspace, <BS>, `C-h'
     ?\t => 9                 ; tab, <TAB>, `C-i'
     ?\n => 10                ; newline, `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-['
     ?\s => 32                ; space character, <SPC>
     ?\\ => 92                ; backslash character, `\'
     ?\d => 127               ; delete character, <DEL>

   These sequences which start with backslash are also known as "escape
sequences", because backslash plays the role of an "escape character";
this terminology has nothing to do with the character <ESC>.  `\s' is
meant for use in character constants; in string constants, just write
the space.

   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.  You can 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' or `\s', instead of an actual
whitespace character such as a tab or a space.  (If you do write
backslash followed by a space, you should write an extra space after
the character constant to separate it from the following text.)

File: elisp,  Node: General Escape Syntax,  Next: Ctl-Char Syntax,  Prev: Basic Char Syntax,  Up: Character Type

2.3.3.2 General Escape Syntax
.............................

In addition to the specific escape sequences for special important
control characters, Emacs provides several types of escape syntax that
you can use to specify non-ASCII text characters.

   You can specify characters by their Unicode values.  `?\uNNNN'
represents a character that maps to the Unicode code point `U+NNNN' (by
convention, Unicode code points are given in hexadecimal).  There is a
slightly different syntax for specifying characters with code points
higher than `U+FFFF': `\U00NNNNNN' represents the character whose code
point is `U+NNNNNN'.  The Unicode Standard only defines code points up
to `U+10FFFF', so if you specify a code point higher than that, Emacs
signals an error.

   This peculiar and inconvenient syntax was adopted for compatibility
with other programming languages.  Unlike some other languages, Emacs
Lisp supports this syntax only in character literals and strings.

   The most general read syntax for a character represents the
character code in either octal or hex.  To use octal, write a question
mark followed by a backslash and the octal character code (up to three
octal digits); thus, `?\101' for the character `A', `?\001' for the
character `C-a', and `?\002' for the character `C-b'.  Although this
syntax can represent any ASCII character, it is preferred only when the
precise octal value is more important than the ASCII representation.

     ?\012 => 10         ?\n => 10         ?\C-j => 10
     ?\101 => 65         ?A => 65

   To use hex, write a question mark followed by a backslash, `x', and
the hexadecimal character code.  You can use any number of hex digits,
so you can represent any character code in this way.  Thus, `?\x41' for
the character `A', `?\x1' for the character `C-a', and `?\x8e0' for the
Latin-1 character `a' with grave accent.

File: elisp,  Node: Ctl-Char Syntax,  Next: Meta-Char Syntax,  Prev: General Escape Syntax,  Up: Character Type

2.3.3.3 Control-Character Syntax
................................

Control characters can 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':

     ?\^I => 9     ?\C-I => 9

   In strings and buffers, the only control characters allowed are those
that exist in ASCII; but for keyboard input purposes, you can turn any
character into a control character with `C-'.  The character codes for
these non-ASCII control characters include the 2**26 bit as well as the
code for the corresponding non-control character.  Ordinary terminals
have no way of generating non-ASCII control characters, but you can
generate them straightforwardly using X and other window systems.

   For historical reasons, Emacs treats the <DEL> character as the
control equivalent of `?':

     ?\^? => 127     ?\C-? => 127

As a result, it is currently not possible to represent the character
`Control-?', which is a meaningful input character under X, using
`\C-'.  It is not easy to change this, as various Lisp files refer to
<DEL> in this way.

   For representing control characters to be found in files or strings,
we recommend the `^' syntax; for control characters in keyboard input,
we prefer the `C-' syntax.  Which one you use does not affect the
meaning of the program, but may guide the understanding of people who
read it.

File: elisp,  Node: Meta-Char Syntax,  Next: Other Char Bits,  Prev: Ctl-Char Syntax,  Up: Character Type

2.3.3.4 Meta-Character Syntax
.............................

A "meta character" is a character typed with the <META> modifier key.
The integer that represents such a character has the 2**27 bit set.  We
use high bits for this and other modifiers to make possible a wide
range of basic character codes.

   In a string, the 2**7 bit attached to an ASCII character indicates a
meta character; thus, the meta characters that can fit in a string have
codes in the range from 128 to 255, and are the meta versions of the
ordinary ASCII characters.  (In Emacs versions 18 and older, this
convention was used for characters outside of strings as well.)

   The read syntax for meta characters uses `\M-'.  For example,
`?\M-A' stands for `M-A'.  You can use `\M-' together with octal
character codes (see below), with `\C-', or with any other syntax for a
character.  Thus, you can write `M-A' as `?\M-A', or as `?\M-\101'.
Likewise, you can write `C-M-b' as `?\M-\C-b', `?\C-\M-b', or
`?\M-\002'.

File: elisp,  Node: Other Char Bits,  Prev: Meta-Char Syntax,  Up: Character Type

2.3.3.5 Other Character Modifier Bits
.....................................

The case of a graphic character is indicated by its character code; for
example, ASCII distinguishes between the characters `a' and `A'.  But
ASCII has no way to represent whether a control character is upper case
or lower case.  Emacs uses the 2**25 bit to indicate that the shift key
was used in typing a control character.  This distinction is possible
only when you use X terminals or other special terminals; ordinary
terminals do not report the distinction to the computer in any way.
The Lisp syntax for the shift bit is `\S-'; thus, `?\C-\S-o' or
`?\C-\S-O' represents the shifted-control-o character.

   The X Window System defines three other modifier bits that can be set
in a character: "hyper", "super" and "alt".  The syntaxes for these
bits are `\H-', `\s-' and `\A-'.  (Case is significant in these
prefixes.)  Thus, `?\H-\M-\A-x' represents `Alt-Hyper-Meta-x'.  (Note
that `\s' with no following `-' represents the space character.)
Numerically, the bit values are 2**22 for alt, 2**23 for super and
2**24 for hyper.

File: elisp,  Node: Symbol Type,  Next: Sequence Type,  Prev: Character Type,  Up: Programming Types

2.3.4 Symbol Type
-----------------

A "symbol" in GNU Emacs Lisp is an object with a name.  The symbol name
serves as the printed representation of the symbol.  In ordinary Lisp
use, with one single obarray (*note Creating Symbols::), a symbol's
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 whose name starts with a colon (`:') is called a "keyword
symbol".  These symbols automatically act as constants, and are
normally used only by comparing an unknown symbol with a few specific
alternatives.

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

   Normally the Lisp reader interns all symbols (*note Creating
Symbols::).  To prevent interning, you can write `#:' before the name
of the symbol.

File: elisp,  Node: Sequence Type,  Next: Cons Cell Type,  Prev: Symbol Type,  Up: Programming Types

2.3.5 Sequence Types
--------------------

A "sequence" is a Lisp object that represents an ordered set of
elements.  There are two kinds of sequence in Emacs 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, char-tables and
bool-vectors.  Vectors can hold elements of any type, but string
elements must be characters, and bool-vector elements must be `t' or
`nil'.  Char-tables are like vectors except that they are indexed by
any valid character code.  The characters in a string can have text
properties like characters in a buffer (*note Text Properties::), but
vectors do not support text properties, even when their elements happen
to be characters.

   Lists, strings and the other array types 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.  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 generally 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: elisp,  Node: Cons Cell Type,  Next: Array Type,  Prev: Sequence Type,  Up: Programming Types

2.3.6 Cons Cell and List Types
------------------------------

A "cons cell" is an object that consists of two slots, called the CAR
slot and the CDR slot.  Each slot can "hold" or "refer to" any Lisp
object.  We also say that "the CAR of this cons cell is" whatever
object its CAR slot currently holds, and likewise for the CDR.

     A note to C programmers: in Lisp, we do not distinguish between
     "holding" a value and "pointing to" the value, because pointers in
     Lisp are implicit.

   A "list" is a series of cons cells, linked together so that the CDR
slot of each cons cell holds either the next cons cell or the empty
list.  The empty list is actually the symbol `nil'.  *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.

   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.  Here are examples of lists:

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

   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
slot of the cons cell holds the element, and its CDR slot refers to the
next cons cell of the list, which holds the next element in the list.
The CDR slot of the last cons cell is set to hold `nil'.

   The names CAR and CDR derive from the history of Lisp.  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 was named for its purpose, the construction of
cells.

* Menu:

* Box Diagrams::                Drawing pictures of lists.
* Dotted Pair Notation::        A general syntax for cons cells.
* Association List Type::       A specially constructed list.

File: elisp,  Node: Box Diagrams,  Next: Dotted Pair Notation,  Up: Cons Cell Type

2.3.6.1 Drawing Lists as Box Diagrams
.....................................

A list can be illustrated by a diagram in which the cons cells are
shown as pairs of boxes, like dominoes.  (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.)  This picture represents the three-element
list `(rose violet buttercup)':

         --- ---      --- ---      --- ---
        |   |   |--> |   |   |--> |   |   |--> nil
         --- ---      --- ---      --- ---
          |            |            |
          |            |            |
           --> rose     --> violet   --> buttercup

   In this diagram, each box represents a slot that can hold or refer to
any Lisp object.  Each pair of boxes represents a cons cell.  Each arrow
represents a reference to a Lisp object, either an atom or another cons
cell.

   In this example, the first box, which holds the CAR of the first
cons cell, refers to or "holds" `rose' (a symbol).  The second box,
holding 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 is
`violet', and its CDR is the third cons cell.  The CDR of the third
(and last) cons cell is `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 is the list `(A ())', or equivalently `(A nil)', depicted with
boxes and arrows:

         --- ---      --- ---
        |   |   |--> |   |   |--> nil
         --- ---      --- ---
          |            |
          |            |
           --> A        --> nil

   Here is a more complex illustration, showing the three-element list,
`((pine needles) oak maple)', the first element of which is a
two-element list:

         --- ---      --- ---      --- ---
        |   |   |--> |   |   |--> |   |   |--> nil
         --- ---      --- ---      --- ---
          |            |            |
          |            |            |
          |             --> oak      --> maple
          |
          |     --- ---      --- ---
           --> |   |   |--> |   |   |--> nil
                --- ---      --- ---
                 |            |
                 |            |
                  --> pine     --> needles

   The same list represented in the second box notation looks like this:

      --------------       --------------       --------------
     | car   | cdr  |     | car   | cdr  |     | car   | cdr  |
     |   o   |   o------->| oak   |   o------->| maple |  nil |
     |   |   |      |     |       |      |     |       |      |
      -- | ---------       --------------       --------------
         |
         |
         |        --------------       ----------------
         |       | car   | cdr  |     | car     | cdr  |
          ------>| pine  |   o------->| needles |  nil |
                 |       |      |     |         |      |
                  --------------       ----------------

File: elisp,  Node: Dotted Pair Notation,  Next: Association List Type,  Prev: Box Diagrams,  Up: Cons Cell Type

2.3.6.2 Dotted Pair Notation
............................

"Dotted pair notation" is a general 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 more general than list syntax
because the CDR does not have to be a list.  However, it is more
cumbersome in cases where list syntax would work.  In dotted pair
notation, the list `(1 2 3)' is written as `(1 .  (2 . (3 . nil)))'.
For `nil'-terminated lists, you can use either notation, but list
notation is usually clearer and more convenient.  When printing a list,
the dotted pair notation is only used if the CDR of a cons cell is not
a list.

   Here's an example using boxes to illustrate dotted pair notation.
This example shows the pair `(rose . violet)':

         --- ---
        |   |   |--> violet
         --- ---
          |
          |
           --> rose

   You can combine dotted pair notation with list notation to represent
conveniently a chain of cons cells with a non-`nil' final CDR.  You
write a dot after the last element of the list, followed by the CDR of
the final cons cell.  For example, `(rose violet . buttercup)' is
equivalent to `(rose . (violet . buttercup))'.  The object looks like
this:

         --- ---      --- ---
        |   |   |--> |   |   |--> buttercup
         --- ---      --- ---
          |            |
          |            |
           --> rose     --> violet

   The syntax `(rose . violet . buttercup)' is invalid because there is
nothing that it could mean.  If anything, it would say to put
`buttercup' in the CDR of a cons cell whose CDR is already used for
`violet'.

   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: elisp,  Node: Association List Type,  Prev: Dotted Pair Notation,  Up: Cons Cell Type

2.3.6.3 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.  *Note Hash Tables::, for another
kind of lookup table, which is much faster for handling a large number
of keys.

File: elisp,  Node: Array Type,  Next: String Type,  Prev: Cons Cell Type,  Up: Programming Types

2.3.7 Array Type
----------------

An "array" is composed of an arbitrary number of slots for holding or
referring to other Lisp objects, arranged in a contiguous block of
memory.  Accessing any element of an array takes approximately 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.)

   Emacs defines four types of array: strings, vectors, bool-vectors,
and char-tables.

   A string is an array of characters and a vector is an array of
arbitrary objects.  A bool-vector can hold only `t' or `nil'.  These
kinds of array may have any length up to the largest integer.
Char-tables are sparse arrays indexed by any valid character code; they
can hold arbitrary objects.

   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
largest possible index value is one less than the length of the array.
Once an array is created, its length is fixed.

   All Emacs Lisp arrays are one-dimensional.  (Most other programming
languages support multidimensional arrays, but they are not essential;
you can get the same effect with nested one-dimensional arrays.)  Each
type of array has its own read syntax; see the following sections for
details.

   The array type is a subset of the sequence type, and contains the
string type, the vector type, the bool-vector type, and the char-table
type.

File: elisp,  Node: String Type,  Next: Vector Type,  Prev: Array Type,  Up: Programming Types

2.3.8 String Type
-----------------

A "string" is an array of characters.  Strings are used for many
purposes in Emacs, 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.

   *Note Strings and Characters::, for functions that operate on
strings.

* Menu:

* Syntax for Strings::      How to specify Lisp strings.
* Non-ASCII in Strings::    International characters in strings.
* Nonprinting Characters::  Literal unprintable characters in strings.
* Text Props and Strings::  Strings with text properties.

File: elisp,  Node: Syntax for Strings,  Next: Non-ASCII in Strings,  Up: String Type

2.3.8.1 Syntax for Strings
..........................

The read syntax for a string is a double-quote, an arbitrary number of
characters, and another double-quote, `"like this"'.  To include a
double-quote in a string, precede it with a backslash; thus, `"\""' is
a string containing just a single double-quote character.  Likewise,
you can include a backslash by preceding it with another backslash,
like this: `"this \\ is a single embedded backslash"'.

   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.  An escaped space
`\ ' is likewise ignored.

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

File: elisp,  Node: Non-ASCII in Strings,  Next: Nonprinting Characters,  Prev: Syntax for Strings,  Up: String Type

2.3.8.2 Non-ASCII Characters in Strings
.......................................

You can include a non-ASCII international character in a string
constant by writing it literally.  There are two text representations
for non-ASCII characters in Emacs strings (and in buffers): unibyte and
multibyte.  If the string constant is read from a multibyte source,
such as a multibyte buffer or string, or a file that would be visited as
multibyte, then the character is read as a multibyte character, and that
makes the string multibyte.  If the string constant is read from a
unibyte source, then the character is read as unibyte and that makes the
string unibyte.

   You can also represent a multibyte non-ASCII character with its
character code: use a hex escape, `\xNNNNNNN', with as many digits as
necessary.  (Multibyte non-ASCII character codes are all greater than
256.)  Any character which is not a valid hex digit terminates this
construct.  If the next character in the string could be interpreted as
a hex digit, write `\ ' (backslash and space) to terminate the hex
escape--for example, `\x8e0\ ' represents one character, `a' with grave
accent.  `\ ' in a string constant is just like backslash-newline; it
does not contribute any character to the string, but it does terminate
the preceding hex escape.

   You can represent a unibyte non-ASCII character with its character
code, which must be in the range from 128 (0200 octal) to 255 (0377
octal).  If you write all such character codes in octal and the string
contains no other characters forcing it to be multibyte, this produces
a unibyte string.  However, using any hex escape in a string (even for
an ASCII character) forces the string to be multibyte.

   You can also specify characters in a string by their numeric values
in Unicode, using `\u' and `\U' (*note Character Type::).

   *Note Text Representations::, for more information about the two
text representations.

File: elisp,  Node: Nonprinting Characters,  Next: Text Props and Strings,  Prev: Non-ASCII in Strings,  Up: String Type

2.3.8.3 Nonprinting Characters in Strings
.........................................

You can use the same backslash escape-sequences in a string constant as
in character literals (but do not use the question mark that begins a
character constant).  For example, you can write a string containing the
nonprinting characters tab and `C-a', with commas and spaces between
them, like this: `"\t, \C-a"'.  *Note Character Type::, for a
description of the read syntax for characters.

   However, not all of the characters you can write with backslash
escape-sequences are valid in strings.  The only control characters that
a string can hold are the ASCII control characters.  Strings do not
distinguish case in ASCII control characters.

   Properly speaking, strings cannot hold meta characters; but when a
string is to be used as a key sequence, there is a special convention
that provides a way to represent meta versions of ASCII characters in a
string.  If you use the `\M-' syntax to indicate a meta character in a
string constant, this sets the 2**7 bit of the character in the string.
If the string is used in `define-key' or `lookup-key', this numeric
code is translated into the equivalent meta character.  *Note Character
Type::.

   Strings cannot hold characters that have the hyper, super, or alt
modifiers.

File: elisp,  Node: Text Props and Strings,  Prev: Nonprinting Characters,  Up: String Type

2.3.8.4 Text Properties in Strings
..................................

A string can hold properties for the characters it contains, in
addition to the characters themselves.  This enables programs that copy
text between strings and buffers to copy the text's properties with no
special effort.  *Note Text Properties::, for an explanation of what
text properties mean.  Strings with text properties use a special read
and print syntax:

     #("CHARACTERS" PROPERTY-DATA...)

where PROPERTY-DATA consists of zero or more elements, in groups of
three as follows:

     BEG END PLIST

The elements BEG and END are integers, and together specify a range of
indices in the string; PLIST is the property list for that range.  For
example,

     #("foo bar" 0 3 (face bold) 3 4 nil 4 7 (face italic))

represents a string whose textual contents are `foo bar', in which the
first three characters have a `face' property with value `bold', and
the last three have a `face' property with value `italic'.  (The fourth
character has no text properties, so its property list is `nil'.  It is
not actually necessary to mention ranges with `nil' as the property
list, since any characters not mentioned in any range will default to
having no properties.)

File: elisp,  Node: Vector Type,  Next: Char-Table Type,  Prev: String Type,  Up: Programming Types

2.3.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: elisp,  Node: Char-Table Type,  Next: Bool-Vector Type,  Prev: Vector Type,  Up: Programming Types

2.3.10 Char-Table Type
----------------------

A "char-table" is a one-dimensional array of elements of any type,
indexed by character codes.  Char-tables have certain extra features to
make them more useful for many jobs that involve assigning information
to character codes--for example, a char-table can have a parent to
inherit from, a default value, and a small number of extra slots to use
for special purposes.  A char-table can also specify a single value for
a whole character set.

   The printed representation of a char-table is like a vector except
that there is an extra `#^' at the beginning.

   *Note Char-Tables::, for special functions to operate on char-tables.
Uses of char-tables include:

   * Case tables (*note Case Tables::).

   * Character category tables (*note Categories::).

   * Display tables (*note Display Tables::).

   * Syntax tables (*note Syntax Tables::).

File: elisp,  Node: Bool-Vector Type,  Next: Hash Table Type,  Prev: Char-Table Type,  Up: Programming Types

2.3.11 Bool-Vector Type
-----------------------

A "bool-vector" is a one-dimensional array of elements that must be `t'
or `nil'.

   The printed representation of a bool-vector is like a string, except
that it begins with `#&' followed by the length.  The string constant
that follows actually specifies the contents of the bool-vector as a
bitmap--each "character" in the string contains 8 bits, which specify
the next 8 elements of the bool-vector (1 stands for `t', and 0 for
`nil').  The least significant bits of the character correspond to the
lowest indices in the bool-vector.

     (make-bool-vector 3 t)
          => #&3"^G"
     (make-bool-vector 3 nil)
          => #&3"^@"

These results make sense, because the binary code for `C-g' is 111 and
`C-@' is the character with code 0.

   If the length is not a multiple of 8, the printed representation
shows extra elements, but these extras really make no difference.  For
instance, in the next example, the two bool-vectors are equal, because
only the first 3 bits are used:

     (equal #&3"\377" #&3"\007")
          => t

File: elisp,  Node: Hash Table Type,  Next: Function Type,  Prev: Bool-Vector Type,  Up: Programming Types

2.3.12 Hash Table Type
----------------------

A hash table is a very fast kind of lookup table, somewhat like an
alist in that it maps keys to corresponding values, but much faster.
Hash tables have no read syntax, and print using hash notation.  *Note
Hash Tables::, for functions that operate on hash tables.

     (make-hash-table)
          => #<hash-table 'eql nil 0/65 0x83af980>

File: elisp,  Node: Function Type,  Next: Macro Type,  Prev: Hash Table Type,  Up: Programming Types

2.3.13 Function Type
--------------------

Lisp functions are executable code, just like functions in other
programming languages.  In Lisp, unlike most languages, functions are
also Lisp objects.  A non-compiled function in Lisp is a lambda
expression: that is, a list 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 can be called as a function even though it has no name; to
emphasize this, we also call it an "anonymous function" (*note
Anonymous Functions::).  A named function in Lisp is just 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: elisp,  Node: Macro Type,  Next: Primitive Function Type,  Prev: Function Type,  Up: Programming Types

2.3.14 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 argument-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
Emacs is concerned.  *Note Macros::, for an explanation of how to write
a macro.

   *Warning*: Lisp macros and keyboard macros (*note Keyboard Macros::)
are entirely different things.  When we use the word "macro" without
qualification, we mean a Lisp macro, not a keyboard macro.

File: elisp,  Node: Primitive Function Type,  Next: Byte-Code Type,  Prev: Macro Type,  Up: Programming Types

2.3.15 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 redefine a
primitive with a function written in Lisp.  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.  Therefore, *we
discourage redefinition of primitive functions*.

   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: elisp,  Node: Byte-Code Type,  Next: Autoload Type,  Prev: Primitive Function Type,  Up: Programming Types

2.3.16 Byte-Code Function Type
------------------------------

The byte compiler produces "byte-code function objects".  Internally, a
byte-code function object is much like a vector; however, 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 and read syntax for a byte-code function
object is like that for a vector, with an additional `#' before the
opening `['.

File: elisp,  Node: Autoload Type,  Prev: Byte-Code Type,  Up: Programming Types

2.3.17 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, where
it serves as a placeholder for the real definition.  The autoload
object says that the real definition is found in a file of Lisp code
that should be loaded when necessary.  It 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: elisp,  Node: Editing Types,  Next: Circular Objects,  Prev: Programming Types,  Up: Lisp Data Types

2.4 Editing Types
=================

The types in the previous section are used for general programming
purposes, and most of them are common to most Lisp dialects.  Emacs 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.
* Window Type::         Buffers are displayed in windows.
* Frame Type::          Windows subdivide frames.
* Terminal Type::       A terminal device displays frames.
* Window Configuration Type::   Recording the way a frame is subdivided.
* Frame Configuration Type::    Recording the status of all frames.
* Process Type::        A subprocess of Emacs running on the underlying OS.
* Stream Type::         Receive or send characters.
* Keymap Type::         What function a keystroke invokes.
* Overlay Type::        How an overlay is represented.
* Font Type::           Fonts for displaying text.

File: elisp,  Node: Buffer Type,  Next: Marker Type,  Up: Editing Types

2.4.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.  Each buffer has a designated
position called "point" (*note Positions::); most editing commands act
on the contents of the current buffer in the neighborhood of point.  At
any time, one buffer is the "current buffer".

   The contents of a buffer are much like a string, but buffers are not
used like strings in Emacs Lisp, and the available operations are
different.  For example, you can insert text efficiently into an
existing buffer, altering the buffer's contents, whereas "inserting"
text into a string requires concatenating substrings, and the result is
an entirely new string object.

   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::); and,

   * a list of buffer-local variable bindings (*note Buffer-Local
     Variables::).

   * overlays (*note Overlays::).

   * text properties for the text in the buffer (*note Text
     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, but presents it differently.  *Note Indirect Buffers::.

   Buffers have no read syntax.  They print in hash notation, showing
the buffer name.

     (current-buffer)
          => #<buffer objects.texi>

File: elisp,  Node: Marker Type,  Next: Window Type,  Prev: Buffer Type,  Up: Editing Types

2.4.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 10779 in objects.texi>

   *Note Markers::, for information on how to test, create, copy, and
move markers.

File: elisp,  Node: Window Type,  Next: Frame Type,  Prev: Marker Type,  Up: Editing Types

2.4.3 Window Type
-----------------

A "window" describes the portion of the terminal screen that Emacs uses
to display a buffer.  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 Emacs 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
window number and the name of the buffer being displayed.  The window
numbers exist to identify windows uniquely, since the buffer displayed
in any given window can change frequently.

     (selected-window)
          => #<window 1 on objects.texi>

   *Note Windows::, for a description of the functions that work on
windows.

File: elisp,  Node: Frame Type,  Next: Terminal Type,  Prev: Window Type,  Up: Editing Types

2.4.4 Frame Type
----------------

A "frame" is a screen area that contains one or more Emacs windows; we
also use the term "frame" to refer to the Lisp object that Emacs uses
to refer to the screen area.

   Frames have no read syntax.  They print in hash notation, giving the
frame's title, plus its address in core (useful to identify the frame
uniquely).

     (selected-frame)
          => #<frame emacsATpsilocin.org 0xdac80>

   *Note Frames::, for a description of the functions that work on
frames.

File: elisp,  Node: Terminal Type,  Next: Window Configuration Type,  Prev: Frame Type,  Up: Editing Types

2.4.5 Terminal Type
-------------------

A "terminal" is a device capable of displaying one or more Emacs frames
(*note Frame Type::).

   Terminals have no read syntax.  They print in hash notation giving
the terminal's ordinal number and its TTY device file name.

     (get-device-terminal nil)
          => #<terminal 1 on /dev/tty>

File: elisp,  Node: Window Configuration Type,  Next: Frame Configuration Type,  Prev: Terminal Type,  Up: Editing Types

2.4.6 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; their print syntax
looks like `#<window-configuration>'.  *Note Window Configurations::,
for a description of several functions related to window configurations.

File: elisp,  Node: Frame Configuration Type,  Next: Process Type,  Prev: Window Configuration Type,  Up: Editing Types

2.4.7 Frame Configuration Type
------------------------------

A "frame configuration" stores information about the positions, sizes,
and contents of the windows in all frames.  It is not a primitive
type--it is actually a list whose CAR is `frame-configuration' and
whose CDR is an alist.  Each alist element describes one frame, which
appears as the CAR of that element.

   *Note Frame Configurations::, for a description of several functions
related to frame configurations.

File: elisp,  Node: Process Type,  Next: Stream Type,  Prev: Frame Configuration Type,  Up: Editing Types

2.4.8 Process Type
------------------

The word "process" usually means a running program.  Emacs itself runs
in a process of this sort.  However, in Emacs Lisp, a process is a Lisp
object that designates a subprocess created by the Emacs process.
Programs such as shells, GDB, ftp, and compilers, running in
subprocesses of Emacs, extend the capabilities of Emacs.

   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:

     (process-list)
          => (#<process shell>)

   *Note Processes::, for information about functions that create,
delete, return information about, send input or signals to, and receive
output from processes.

File: elisp,  Node: Stream Type,  Next: Keymap Type,  Prev: Process Type,  Up: Editing Types

2.4.9 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: elisp,  Node: Keymap Type,  Next: Overlay Type,  Prev: Stream Type,  Up: Editing Types

2.4.10 Keymap Type
------------------

A "keymap" maps keys typed by the user to commands.  This mapping
controls how the user's command input is executed.  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: elisp,  Node: Overlay Type,  Next: Font Type,  Prev: Keymap Type,  Up: Editing Types

2.4.11 Overlay Type
-------------------

An "overlay" specifies properties that apply to a part of a buffer.
Each overlay applies to a specified range of the buffer, and contains a
property list (a list whose elements are alternating property names and
values).  Overlay properties are used to present parts of the buffer
temporarily in a different display style.  Overlays have no read
syntax, and print in hash notation, giving the buffer name and range of
positions.

   *Note Overlays::, for how to create and use overlays.

File: elisp,  Node: Font Type,  Prev: Overlay Type,  Up: Editing Types

2.4.12 Font Type
----------------

A "font" specifies how to display text on a graphical terminal.  There
are actually three separate font types--"font objects", "font specs",
and "font entities"--each of which has slightly different properties.
None of them have a read syntax; their print syntax looks like
`#<font-object>', `#<font-spec>', and `#<font-entity>' respectively.
*Note Low-Level Font::, for a description of these Lisp objects.

File: elisp,  Node: Circular Objects,  Next: Type Predicates,  Prev: Editing Types,  Up: Lisp Data Types

2.5 Read Syntax for Circular Objects
====================================

To represent shared or circular structures within a complex of Lisp
objects, you can use the reader constructs `#N=' and `#N#'.

   Use `#N=' before an object to label it for later reference;
subsequently, you can use `#N#' to refer the same object in another
place.  Here, N is some integer.  For example, here is how to make a
list in which the first element recurs as the third element:

     (#1=(a) b #1#)

This differs from ordinary syntax such as this

     ((a) b (a))

which would result in a list whose first and third elements look alike
but are not the same Lisp object.  This shows the difference:

     (prog1 nil
       (setq x '(#1=(a) b #1#)))
     (eq (nth 0 x) (nth 2 x))
          => t
     (setq x '((a) b (a)))
     (eq (nth 0 x) (nth 2 x))
          => nil

   You can also use the same syntax to make a circular structure, which
appears as an "element" within itself.  Here is an example:

     #1=(a #1#)

This makes a list whose second element is the list itself.  Here's how
you can see that it really works:

     (prog1 nil
       (setq x '#1=(a #1#)))
     (eq x (cadr x))
          => t

   The Lisp printer can produce this syntax to record circular and
shared structure in a Lisp object, if you bind the variable
`print-circle' to a non-`nil' value.  *Note Output Variables::.

File: elisp,  Node: Type Predicates,  Next: Equality Predicates,  Prev: Circular Objects,  Up: Lisp Data Types

2.6 Type Predicates
===================

The Emacs 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: number-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 handle only 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.

`atom'
     *Note atom: List-related Predicates.

`arrayp'
     *Note arrayp: Array Functions.

`bool-vector-p'
     *Note bool-vector-p: Bool-Vectors.

`bufferp'
     *Note bufferp: Buffer Basics.

`byte-code-function-p'
     *Note byte-code-function-p: Byte-Code Type.

`case-table-p'
     *Note case-table-p: Case Tables.

`char-or-string-p'
     *Note char-or-string-p: Predicates for Strings.

`char-table-p'
     *Note char-table-p: Char-Tables.

`commandp'
     *Note commandp: Interactive Call.

`consp'
     *Note consp: List-related Predicates.

`display-table-p'
     *Note display-table-p: Display Tables.

`floatp'
     *Note floatp: Predicates on Numbers.

`fontp'
     *Note Low-Level Font::.

`frame-configuration-p'
     *Note frame-configuration-p: Frame Configurations.

`frame-live-p'
     *Note frame-live-p: Deleting Frames.

`framep'
     *Note framep: Frames.

`functionp'
     *Note functionp: Functions.

`hash-table-p'
     *Note hash-table-p: Other Hash.

`integer-or-marker-p'
     *Note integer-or-marker-p: Predicates on Markers.

`integerp'
     *Note integerp: Predicates on Numbers.

`keymapp'
     *Note keymapp: Creating Keymaps.

`keywordp'
     *Note Constant Variables::.

`listp'
     *Note listp: List-related Predicates.

`markerp'
     *Note markerp: Predicates on Markers.

`wholenump'
     *Note wholenump: Predicates on Numbers.

`nlistp'
     *Note nlistp: List-related Predicates.

`numberp'
     *Note numberp: Predicates on Numbers.

`number-or-marker-p'
     *Note number-or-marker-p: Predicates on Markers.

`overlayp'
     *Note overlayp: Overlays.

`processp'
     *Note processp: Processes.

`sequencep'
     *Note sequencep: Sequence Functions.

`stringp'
     *Note stringp: Predicates for Strings.

`subrp'
     *Note subrp: Function Cells.

`symbolp'
     *Note symbolp: Symbols.

`syntax-table-p'
     *Note syntax-table-p: Syntax Tables.

`user-variable-p'
     *Note user-variable-p: Defining Variables.

`vectorp'
     *Note vectorp: Vectors.

`window-configuration-p'
     *Note window-configuration-p: Window Configurations.

`window-live-p'
     *Note window-live-p: Deleting Windows.

`windowp'
     *Note windowp: Basic Windows.

`booleanp'
     *Note booleanp: nil and t.

`string-or-null-p'
     *Note string-or-null-p: Predicates for Strings.

   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 the symbols `bool-vector', `buffer',
     `char-table', `compiled-function', `cons', `float', `font-entity',
     `font-object', `font-spec', `frame', `hash-table', `integer',
     `marker', `overlay', `process', `string', `subr', `symbol',
     `vector', `window', or `window-configuration'.

          (type-of 1)
               => integer
          (type-of 'nil)
               => symbol
          (type-of '())    ; `()' is `nil'.
               => symbol
          (type-of '(x))
               => cons

File: elisp,  Node: Equality Predicates,  Prev: Type Predicates,  Up: Lisp Data Types

2.7 Equality Predicates
=======================

Here we describe functions that test for equality between any two
objects.  Other functions test equality of contents 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.

     `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, meaning
     that a change in the contents of one will be reflected by the same
     change in the contents of the other.

          (eq 'foo 'foo)
               => t

          (eq 456 456)
               => t

          (eq "asdf" "asdf")
               => nil

          (eq "" "")
               => t
          ;; This exception occurs because Emacs Lisp
          ;; makes just one multibyte empty string, to save space.

          (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

     The `make-symbol' function returns an uninterned symbol, distinct
     from the symbol that is used if you write the name in a Lisp
     expression.  Distinct symbols with the same name are not `eq'.
     *Note Creating Symbols::.

          (eq (make-symbol "foo") 'foo)
               => nil

 -- 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 or contents 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, but does not take account
     of text properties--it compares only the characters in the
     strings.  Use `equal-including-properties' to also compare text
     properties.  For technical reasons, a unibyte string and a
     multibyte string are `equal' if and only if they contain the same
     sequence of character codes and all these codes are either in the
     range 0 through 127 (ASCII) or 160 through 255
     (`eight-bit-graphic').  (*note Text Representations::).

          (equal "asdf" "ASDF")
               => nil

     However, two distinct buffers are never considered `equal', even if
     their textual contents are the same.

   The test for equality is implemented recursively; for example, given
two cons cells X and Y, `(equal X Y)' returns `t' if and only if both
the expressions below return `t':

     (equal (car X) (car Y))
     (equal (cdr X) (cdr Y))

   Because of this recursive method, circular lists may therefore cause
infinite recursion (leading to an error).

 -- Function: equal-including-properties object1 object2
     This function behaves like `equal' in all cases but also requires
     that for two strings to be equal, they have the same text
     properties.

          (equal "asdf" (propertize "asdf" '(asdf t)))
               => t
          (equal-including-properties "asdf"
                                      (propertize "asdf" '(asdf t)))
               => nil

File: elisp,  Node: Numbers,  Next: Strings and Characters,  Prev: Lisp Data Types,  Up: Top

3 Numbers
*********

GNU Emacs supports two numeric data types: "integers" and "floating
point numbers".  Integers are whole numbers such as -3, 0, 7, 13, and
511.  Their values are exact.  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 that is multiplied by 1.5.
Floating point values are not exact; they have a fixed, limited amount
of precision.

* Menu:

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

File: elisp,  Node: Integer Basics,  Next: Float Basics,  Up: Numbers

3.1 Integer Basics
==================

The range of values for an integer depends on the machine.  The minimum
range is -268435456 to 268435455 (29 bits; i.e., -2**28 to 2**28 - 1),
but some machines may provide a wider range.  Many examples in this
chapter assume an integer has 29 bits.

   The Lisp reader reads an integer as a sequence of digits with
optional initial sign and optional final period.

      1               ; The integer 1.
      1.              ; The integer 1.
     +1               ; Also the integer 1.
     -1               ; The integer -1.
      536870913       ; Also the integer 1, due to overflow.
      0               ; The integer 0.
     -0               ; The integer 0.

   The syntax for integers in bases other than 10 uses `#' followed by
a letter that specifies the radix: `b' for binary, `o' for octal, `x'
for hex, or `RADIXr' to specify radix RADIX.  Case is not significant
for the letter that specifies the radix.  Thus, `#bINTEGER' reads
INTEGER in binary, and `#RADIXrINTEGER' reads INTEGER in radix RADIX.
Allowed values of RADIX run from 2 to 36.  For example:

     #b101100 => 44
     #o54 => 44
     #x2c => 44
     #24r1k => 44

   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 29-bit binary, the decimal integer 5 looks like this:

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

     1 1111  1111 1111  1111 1111  1111 1111

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

     1 1111  1111 1111  1111 1111  1111 1011

   In this implementation, the largest 29-bit binary integer value is
268,435,455 in decimal.  In binary, it looks like this:

     0 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 268,435,455, the value is the
negative integer -268,435,456:

     (+ 1 268435455)
          => -268435456
          => 1 0000  0000 0000  0000 0000  0000 0000

   Many of the functions described in this chapter accept markers for
arguments in place of numbers.  (*Note Markers::.)  Since the actual
arguments to such functions may be either numbers or markers, we often
give these arguments the name NUMBER-OR-MARKER.  When the argument
value is a marker, its position value is used and its buffer is ignored.

 -- Variable: most-positive-fixnum
     The value of this variable is the largest integer that Emacs Lisp
     can handle.

 -- Variable: most-negative-fixnum
     The value of this variable is the smallest integer that Emacs Lisp
     can handle.  It is negative.

   *Note max-char: Character Codes, for the maximum value of a valid
character codepoint.

File: elisp,  Node: Float Basics,  Next: Predicates on Numbers,  Prev: Integer Basics,  Up: Numbers

3.2 Floating Point Basics
=========================

Floating point numbers are useful for representing numbers that are not
integral.  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 you are using.

   The read-syntax 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, `(/ 0.0 0.0)' returns a NaN.
For practical purposes, there's no significant difference between
different NaN values in Emacs Lisp, and there's no rule for precisely
which NaN value should be used in a particular case, so Emacs Lisp
doesn't try to distinguish them (but it does report the sign, if you
print it).  Here are the read syntaxes for these special floating point
values:

positive infinity
     `1.0e+INF'

negative infinity
     `-1.0e+INF'

Not-a-number
     `0.0e+NaN' or `-0.0e+NaN'.

   To test whether a floating point value is a NaN, compare it with
itself using `='.  That returns `nil' for a NaN, and `t' for any other
floating point value.

   The value `-0.0' is distinguishable from ordinary zero in IEEE
floating point, but Emacs Lisp `equal' and `=' consider them equal
values.

   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.

          (logb 10)
               => 3
          (logb 10.0e20)
               => 69

File: elisp,  Node: Predicates on Numbers,  Next: Comparison of Numbers,  Prev: Float Basics,  Up: Numbers

3.3 Type Predicates for Numbers
===============================

The functions in this section test for numbers, or for a specific type
of number.  The functions `integerp' and `floatp' can take any type of
Lisp object as argument (they would not be of much use otherwise), but
the `zerop' predicate requires a number as its argument.  See also
`integer-or-marker-p' and `number-or-marker-p', in *note Predicates on
Markers::.

 -- Function: floatp object
     This predicate tests whether its argument is a floating point
     number and returns `t' if so, `nil' otherwise.

     `floatp' does not exist in Emacs versions 18 and earlier.

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

 -- Function: numberp object
     This predicate tests whether its argument is a number (either
     integer or floating point), and returns `t' if so, `nil' otherwise.

 -- Function: wholenump object
     The `wholenump' predicate (whose name comes from the phrase
     "whole-number-p") tests to see whether its argument is a
     nonnegative integer, and returns `t' if so, `nil' otherwise.  0 is
     considered non-negative.

     `natnump' is an obsolete synonym for `wholenump'.

 -- Function: zerop number
     This predicate tests whether its argument is zero, and returns `t'
     if so, `nil' otherwise.  The argument must be a number.

     `(zerop x)' is equivalent to `(= x 0)'.

File: elisp,  Node: Comparison of Numbers,  Next: Numeric Conversions,  Prev: Predicates on Numbers,  Up: Numbers

3.4 Comparison of Numbers
=========================

To test numbers for numerical equality, you should normally use `=',
not `eq'.  There can be many distinct floating point number objects
with the same numeric value.  If you use `eq' to compare them, then you
test whether two values are the same _object_.  By contrast, `='
compares only the numeric values of the objects.

   At present, each integer value has a unique Lisp object in Emacs
Lisp.  Therefore, `eq' is equivalent to `=' where integers are
concerned.  It is sometimes convenient to use `eq' for comparing an
unknown value with an integer, because `eq' does not report an error if
the unknown value is not a number--it accepts arguments of any type.
By contrast, `=' signals an error if the arguments are not numbers or
markers.  However, it is a good idea to use `=' if you can, even for
comparing integers, just in case we change the representation of
integers in a future Emacs version.

   Sometimes it is useful to compare numbers with `equal'; it treats
two numbers as equal if they have the same data type (both integers, or
both floating point) and the same value.  By contrast, `=' can treat an
integer and a floating point number as equal.  *Note Equality
Predicates::.

   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:

     (defvar 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.  Emacs
     Lisp can have just one integer object for any given value because
     it has a limited range of integer values.

 -- Function: = number-or-marker1 number-or-marker2
     This function tests whether its arguments are numerically equal,
     and returns `t' if so, `nil' otherwise.

 -- Function: eql value1 value2
     This function acts like `eq' except when both arguments are
     numbers.  It compares numbers by type and numeric value, so that
     `(eql 1.0 1)' returns `nil', but `(eql 1.0 1.0)' and `(eql 1 1)'
     both return `t'.

 -- Function: /= number-or-marker1 number-or-marker2
     This function tests whether its arguments are numerically equal,
     and returns `t' if they are not, and `nil' if they are.

 -- Function: < number-or-marker1 number-or-marker2
     This function tests whether its first argument is strictly less
     than its second argument.  It returns `t' if so, `nil' otherwise.

 -- Function: <= number-or-marker1 number-or-marker2
     This function tests whether its first argument is less than or
     equal to its second argument.  It returns `t' if so, `nil'
     otherwise.

 -- Function: > number-or-marker1 number-or-marker2
     This function tests whether its first argument is strictly greater
     than its second argument.  It returns `t' if so, `nil' otherwise.

 -- Function: >= number-or-marker1 number-or-marker2
     This function tests whether its first argument is greater than or
     equal to its second argument.  It returns `t' if so, `nil'
     otherwise.

 -- Function: max number-or-marker &rest numbers-or-markers
     This function returns the largest of its arguments.  If any of the
     arguments is floating-point, the value is returned as floating
     point, even if it was given as an integer.

          (max 20)
               => 20
          (max 1 2.5)
               => 2.5
          (max 1 3 2.5)
               => 3.0

 -- Function: min number-or-marker &rest numbers-or-markers
     This function returns the smallest of its arguments.  If any of
     the arguments is floating-point, the value is returned as floating
     point, even if it was given as an integer.

          (min -4 1)
               => -4

 -- Function: abs number
     This function returns the absolute value of NUMBER.

File: elisp,  Node: Numeric Conversions,  Next: Arithmetic Operations,  Prev: Comparison of Numbers,  Up: Numbers

3.5 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.  All accept an argument NUMBER
and an optional argument DIVISOR.  Both arguments may be integers or
floating point numbers.  DIVISOR may also be `nil'.  If DIVISOR is
`nil' or omitted, these functions convert NUMBER to an integer, or
return it unchanged if it already is an integer.  If DIVISOR is
non-`nil', they divide NUMBER by DIVISOR and convert the result to an
integer.  An `arith-error' results if DIVISOR is 0.

 -- Function: truncate number &optional divisor
     This returns NUMBER, converted to an integer by rounding towards
     zero.

          (truncate 1.2)
               => 1
          (truncate 1.7)
               => 1
          (truncate -1.2)
               => -1
          (truncate -1.7)
               => -1

 -- Function: floor number &optional divisor
     This returns NUMBER, converted to an integer by rounding downward
     (towards negative infinity).

     If DIVISOR is specified, this uses the kind of division operation
     that corresponds to `mod', rounding downward.

          (floor 1.2)
               => 1
          (floor 1.7)
               => 1
          (floor -1.2)
               => -2
          (floor -1.7)
               => -2
          (floor 5.99 3)
               => 1

 -- Function: ceiling number &optional divisor
     This returns NUMBER, converted to an integer by rounding upward
     (towards positive infinity).

          (ceiling 1.2)
               => 2
          (ceiling 1.7)
               => 2
          (ceiling -1.2)
               => -1
          (ceiling -1.7)
               => -1

 -- Function: round number &optional divisor
     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.

          (round 1.2)
               => 1
          (round 1.7)
               => 2
          (round -1.2)
               => -1
          (round -1.7)
               => -2

File: elisp,  Node: Arithmetic Operations,  Next: Rounding Operations,  Prev: Numeric Conversions,  Up: Numbers

3.6 Arithmetic Operations
=========================

Emacs 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 Emacs Lisp, arithmetic functions do
not check for overflow.  Thus `(1+ 268435455)' may evaluate to
-268435456, depending on your hardware.

 -- Function: 1+ number-or-marker
     This function returns NUMBER-OR-MARKER plus 1.  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

 -- Function: 1- number-or-marker
     This function returns NUMBER-OR-MARKER minus 1.

 -- Function: + &rest numbers-or-markers
     This function adds its arguments together.  When given no
     arguments, `+' returns 0.

          (+)
               => 0
          (+ 1)
               => 1
          (+ 1 2 3 4)
               => 10

 -- Function: - &optional number-or-marker &rest more-numbers-or-markers
     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 MORE-NUMBERS-OR-MARKERS from NUMBER-OR-MARKER, cumulatively.
     If there are no arguments, the result is 0.

          (- 10 1 2 3 4)
               => 0
          (- 10)
               => -10
          (-)
               => 0

 -- Function: * &rest numbers-or-markers
     This function multiplies its arguments together, and returns the
     product.  When given no arguments, `*' returns 1.

          (*)
               => 1
          (* 1)
               => 1
          (* 1 2 3 4)
               => 24

 -- Function: / dividend divisor &rest divisors
     This function divides DIVIDEND by DIVISOR and returns the
     quotient.  If there are additional arguments DIVISORS, then it
     divides DIVIDEND by each divisor in turn.  Each argument may be a
     number or a marker.

     If all the arguments are integers, then the result is an integer
     too.  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 you divide an integer by 0, an `arith-error' error is signaled.
     (*Note Errors::.)  Floating point division by zero returns either
     infinity or a NaN if your machine supports IEEE floating point;
     otherwise, it signals an `arith-error' error.

          (/ 6 2)
               => 3
          (/ 5 2)
               => 2
          (/ 5.0 2)
               => 2.5
          (/ 5 2.0)
               => 2.5
          (/ 5.0 2.0)
               => 2.5
          (/ 25 3 2)
               => 4
          (/ -17 6)
               => -2   (could in theory 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: elisp,  Node: Rounding Operations,  Next: Bitwise Operations,  Prev: Arithmetic Operations,  Up: Numbers

3.7 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 float
     This function rounds FLOAT to the next lower integral value, and
     returns that value as a floating point number.

 -- Function: fceiling float
     This function rounds FLOAT to the next higher integral value, and
     returns that value as a floating point number.

 -- Function: ftruncate float
     This function rounds FLOAT towards zero to an integral value, and
     returns that value as a floating point number.

 -- Function: fround float
     This function rounds FLOAT to the nearest integral value, and
     returns that value as a floating point number.

File: elisp,  Node: Bitwise Operations,  Next: Math Functions,  Prev: Rounding Operations,  Up: Numbers

3.8 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 Emacs 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 Emacs 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
     268,435,455 produces -2 on a 29-bit machine:

          (lsh 268435455 1)          ; left shift
               => -2

     In binary, in the 29-bit implementation, the argument looks like
     this:

          ;; Decimal 268,435,455
          0 1111  1111 1111  1111 1111  1111 1111

     which becomes the following when left shifted:

          ;; Decimal -2
          1 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.
          1 1111  1111 1111  1111 1111  1111 1010
               =>
          1 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) => 268435453
          ;; Decimal -6 becomes decimal 268,435,453.
          1 1111  1111 1111  1111 1111  1111 1010
               =>
          0 1111  1111 1111  1111 1111  1111 1101

     Here are other examples:

                             ;               29-bit binary values

          (lsh 5 2)          ;   5  =  0 0000  0000 0000  0000 0000  0000 0101
               => 20         ;      =  0 0000  0000 0000  0000 0000  0001 0100
          (ash 5 2)
               => 20
          (lsh -5 2)         ;  -5  =  1 1111  1111 1111  1111 1111  1111 1011
               => -20        ;      =  1 1111  1111 1111  1111 1111  1110 1100
          (ash -5 2)
               => -20
          (lsh 5 -2)         ;   5  =  0 0000  0000 0000  0000 0000  0000 0101
               => 1          ;      =  0 0000  0000 0000  0000 0000  0000 0001
          (ash 5 -2)
               => 1
          (lsh -5 -2)        ;  -5  =  1 1111  1111 1111  1111 1111  1111 1011
               => 134217726  ;      =  0 0111  1111 1111  1111 1111  1111 1110
          (ash -5 -2)        ;  -5  =  1 1111  1111 1111  1111 1111  1111 1011
               => -2         ;      =  1 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.

                             ;                29-bit binary values

          (logand 14 13)     ; 14  =  0 0000  0000 0000  0000 0000  0000 1110
                             ; 13  =  0 0000  0000 0000  0000 0000  0000 1101
               => 12         ; 12  =  0 0000  0000 0000  0000 0000  0000 1100

          (logand 14 13 4)   ; 14  =  0 0000  0000 0000  0000 0000  0000 1110
                             ; 13  =  0 0000  0000 0000  0000 0000  0000 1101
                             ;  4  =  0 0000  0000 0000  0000 0000  0000 0100
               => 4          ;  4  =  0 0000  0000 0000  0000 0000  0000 0100

          (logand)
               => -1         ; -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.

                             ;               29-bit binary values

          (logior 12 5)      ; 12  =  0 0000  0000 0000  0000 0000  0000 1100
                             ;  5  =  0 0000  0000 0000  0000 0000  0000 0101
               => 13         ; 13  =  0 0000  0000 0000  0000 0000  0000 1101

          (logior 12 5 7)    ; 12  =  0 0000  0000 0000  0000 0000  0000 1100
                             ;  5  =  0 0000  0000 0000  0000 0000  0000 0101
                             ;  7  =  0 0000  0000 0000  0000 0000  0000 0111
               => 15         ; 15  =  0 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.

                             ;               29-bit binary values

          (logxor 12 5)      ; 12  =  0 0000  0000 0000  0000 0000  0000 1100
                             ;  5  =  0 0000  0000 0000  0000 0000  0000 0101
               => 9          ;  9  =  0 0000  0000 0000  0000 0000  0000 1001

          (logxor 12 5 7)    ; 12  =  0 0000  0000 0000  0000 0000  0000 1100
                             ;  5  =  0 0000  0000 0000  0000 0000  0000 0101
                             ;  7  =  0 0000  0000 0000  0000 0000  0000 0111
               => 14         ; 14  =  0 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  =  0 0000  0000 0000  0000 0000  0000 0101
          ;; becomes
          ;; -6  =  1 1111  1111 1111  1111 1111  1111 1010

File: elisp,  Node: Math Functions,  Next: Random Numbers,  Prev: Bitwise Operations,  Up: Numbers

3.9 Standard Mathematical Functions
===================================

These mathematical functions allow integers as well as floating point
numbers as arguments.

 -- Function: sin arg
 -- Function: cos arg
 -- Function: tan arg
     These are the ordinary trigonometric functions, with argument
     measured in radians.

 -- Function: asin arg
     The value of `(asin ARG)' is a number between -pi/2 and pi/2
     (inclusive) whose sine is ARG; if, however, ARG is out of range
     (outside [-1, 1]), it signals a `domain-error' error.

 -- Function: acos arg
     The value of `(acos ARG)' is a number between 0 and pi (inclusive)
     whose cosine is ARG; if, however, ARG is out of range (outside
     [-1, 1]), it signals a `domain-error' error.

 -- Function: atan y &optional x
     The value of `(atan Y)' is a number between -pi/2 and pi/2
     (exclusive) whose tangent is Y.  If the optional second argument X
     is given, the value of `(atan y x)' is the angle in radians
     between the vector `[X, Y]' and the `X' axis.

 -- Function: exp arg
     This is the exponential function; it returns e to the power ARG.  e
     is a fundamental mathematical constant also called the base of
     natural logarithms.

 -- Function: log arg &optional base
     This function returns the logarithm of ARG, with base BASE.  If
     you don't specify BASE, the base e is used.  If ARG is negative,
     it signals a `domain-error' error.

 -- Function: log10 arg
     This function returns the logarithm of ARG, with base 10.  If ARG
     is negative, it signals a `domain-error' error.  `(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, overflow causes truncation, so watch out.

 -- Function: sqrt arg
     This returns the square root of ARG.  If ARG is negative, it
     signals a `domain-error' error.

File: elisp,  Node: Random Numbers,  Prev: Math Functions,  Up: Numbers

3.10 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 Emacs, pseudo-random numbers are generated from a "seed" number.
Starting from any given seed, the `random' function always generates
the same sequence of numbers.  Emacs always starts with the same seed
value, so the sequence of values of `random' is actually the same in
each Emacs run!  For example, in one operating system, the first call
to `(random)' after you start Emacs always returns -1457731, and the
second one always returns -7692030.  This repeatability is helpful for
debugging.

   If you want random numbers that don't always come out the same,
execute `(random t)'.  This chooses a new seed based on the current
time of day and on Emacs's process ID number.

 -- Function: random &optional limit
     This function returns a pseudo-random integer.  Repeated calls
     return a series of pseudo-random integers.

     If LIMIT is a positive integer, the value is chosen to be
     nonnegative and less than LIMIT.

     If LIMIT is `t', it means to choose a new seed based on the
     current time of day and on Emacs's process ID number.

     On some machines, any integer representable in Lisp may be the
     result of `random'.  On other machines, the result can never be
     larger than a certain maximum or less than a certain (negative)
     minimum.

File: elisp,  Node: Strings and Characters,  Next: Lists,  Prev: Numbers,  Up: Top

4 Strings and Characters
************************

A string in Emacs 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, Emacs
Lisp has many functions expressly for manipulating them.  Emacs Lisp
programs use strings more often than individual characters.

   *Note Strings of Events::, for special considerations for strings of
keyboard character events.

* Menu:

* Basics: 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.
* Modifying Strings::         Altering the contents of an existing string.
* Text Comparison::           Comparing characters or strings.
* String Conversion::         Converting to and from characters and strings.
* Formatting Strings::        `format': Emacs's analogue of `printf'.
* Case Conversion::           Case conversion functions.
* Case Tables::		      Customizing case conversion.

File: elisp,  Node: String Basics,  Next: Predicates for Strings,  Up: Strings and Characters

4.1 String and Character Basics
===============================

Characters are represented in Emacs Lisp as integers; whether an
integer is a character or not is determined only by how it is used.
Thus, strings really contain integers.  *Note Character Codes::, for
details about character representation in Emacs.

   The length of a string (like any array) is fixed, and cannot be
altered once the string exists.  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.)

   Since strings are arrays, and therefore sequences as well, you can
operate on them with the general array and sequence 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::).

   There are two text representations for non-ASCII characters in Emacs
strings (and in buffers): unibyte and multibyte (*note Text
Representations::).  For most Lisp programming, you don't need to be
concerned with these two representations.

   Sometimes key sequences are represented as unibyte strings.  When a
unibyte string is a key sequence, string elements in the range 128 to
255 represent meta characters (which are large integers) rather than
character codes in the range 128 to 255.  Strings cannot hold
characters that have the hyper, super or alt modifiers; they can hold
ASCII control characters, but no other control characters.  They do not
distinguish case in ASCII control characters.  If you want to store
such characters in a sequence, such as a key sequence, you must use a
vector instead of a string.  *Note Character Type::, for more
information about keyboard input characters.

   Strings are useful for holding regular expressions.  You can also
match regular expressions against strings with `string-match' (*note
Regexp Search::).  The functions `match-string' (*note Simple Match
Data::) and `replace-match' (*note Replacing Match::) are useful for
decomposing and modifying strings after matching regular expressions
against them.

   Like a buffer, a string can contain text properties for the
characters in it, as well as the characters themselves.  *Note Text
Properties::.  All the Lisp primitives that copy text from strings to
buffers or other strings also copy the properties of the characters
being copied.

   *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.
*Note Non-ASCII Characters::, for functions to convert between text
representations and to encode and decode character codes.

File: elisp,  Node: Predicates for Strings,  Next: Creating Strings,  Prev: String Basics,  Up: Strings and Characters

4.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: string-or-null-p object
     This function returns `t' if OBJECT is a string or `nil'.  It
     returns `nil' otherwise.

 -- Function: char-or-string-p object
     This function returns `t' if OBJECT is a string or a character
     (i.e., an integer), `nil' otherwise.

File: elisp,  Node: Creating Strings,  Next: Modifying Strings,  Prev: Predicates for Strings,  Up: Strings and Characters

4.3 Creating Strings
====================

The following functions create strings, either from scratch, or by
putting strings together, or by taking them apart.

 -- Function: make-string count character
     This function returns a string made up of COUNT repetitions of
     CHARACTER.  If COUNT is negative, an error is signaled.

          (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: string &rest characters
     This returns a string containing the characters CHARACTERS.

          (string ?a ?b ?c)
               => "abc"

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

     In the above example, the index for `a' is 0, the index for `b' is
     1, and the index for `c' is 2.  The index 3--which is the the
     fourth character in the string--marks the character position up to
     which the substring is copied.  Thus, `abc' is copied from the
     string `"abcdefg"'.

     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 for END, 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 text properties, the
     properties are copied into the new string also.  *Note Text
     Properties::.

     `substring' also accepts a vector for the first argument.  For
     example:

          (substring [a b (c) "d"] 1 3)
               => [b (c)]

     A `wrong-type-argument' error is signaled if START is not an
     integer or if END is neither an integer nor `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: substring-no-properties string &optional start end
     This works like `substring' but discards all text properties from
     the value.  Also, START may be omitted or `nil', which is
     equivalent to 0.  Thus, `(substring-no-properties STRING)' returns
     a copy of STRING, with all text properties removed.

 -- 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 121) [122])
               => "abcxyz"
          ;; `nil' is an empty sequence.
          (concat "abc" nil "-def")
               => "abc-def"
          (concat "The " "quick brown " "fox.")
               => "The quick brown fox."
          (concat)
               => ""

     This function always constructs a new string that is not `eq' to
     any existing string, except when the result is the empty string (to
     save space, Emacs makes only one empty multibyte string).

     For information about other concatenation functions, see the
     description of `mapconcat' in *note Mapping Functions::, `vconcat'
     in *note Vector Functions::, and `append' in *note Building
     Lists::.  For concatenating individual command-line arguments into
     a string to be used as a shell command, see *note
     combine-and-quote-strings: Shell Arguments.

 -- Function: split-string string &optional separators omit-nulls
     This function splits STRING into substrings based on the regular
     expression SEPARATORS (*note Regular Expressions::).  Each match
     for SEPARATORS defines a splitting point; the substrings between
     splitting points are made into a list, which is returned.

     If OMIT-NULLS is `nil' (or omitted), the result contains null
     strings whenever there are two consecutive matches for SEPARATORS,
     or a match is adjacent to the beginning or end of STRING.  If
     OMIT-NULLS is `t', these null strings are omitted from the result.

     If SEPARATORS is `nil' (or omitted), the default is the value of
     `split-string-default-separators'.

     As a special case, when SEPARATORS is `nil' (or omitted), null
     strings are always omitted from the result.  Thus:

          (split-string "  two words ")
               => ("two" "words")

     The result is not `("" "two" "words" "")', which would rarely be
     useful.  If you need such a result, use an explicit value for
     SEPARATORS:

          (split-string "  two words "
                        split-string-default-separators)
               => ("" "two" "words" "")

     More examples:

          (split-string "Soup is good food" "o")
               => ("S" "up is g" "" "d f" "" "d")
          (split-string "Soup is good food" "o" t)
               => ("S" "up is g" "d f" "d")
          (split-string "Soup is good food" "o+")
               => ("S" "up is g" "d f" "d")

     Empty matches do count, except that `split-string' will not look
     for a final empty match when it already reached the end of the
     string using a non-empty match or when STRING is empty:

          (split-string "aooob" "o*")
               => ("" "a" "" "b" "")
          (split-string "ooaboo" "o*")
               => ("" "" "a" "b" "")
          (split-string "" "")
               => ("")

     However, when SEPARATORS can match the empty string, OMIT-NULLS is
     usually `t', so that the subtleties in the three previous examples
     are rarely relevant:

          (split-string "Soup is good food" "o*" t)
               => ("S" "u" "p" " " "i" "s" " " "g" "d" " " "f" "d")
          (split-string "Nice doggy!" "" t)
               => ("N" "i" "c" "e" " " "d" "o" "g" "g" "y" "!")
          (split-string "" "" t)
               => nil

     Somewhat odd, but predictable, behavior can occur for certain
     "non-greedy" values of SEPARATORS that can prefer empty matches
     over non-empty matches.  Again, such values rarely occur in
     practice:

          (split-string "ooo" "o*" t)
               => nil
          (split-string "ooo" "\\|o+" t)
               => ("o" "o" "o")

     If you need to split a string that is a shell command, where
     individual arguments could be quoted, see *note
     split-string-and-unquote: Shell Arguments.

 -- Variable: split-string-default-separators
     The default value of SEPARATORS for `split-string'.  Its usual
     value is `"[ \f\t\n\r\v]+"'.

File: elisp,  Node: Modifying Strings,  Next: Text Comparison,  Prev: Creating Strings,  Up: Strings and Characters

4.4 Modifying Strings
=====================

The most basic way to alter the contents of an existing string is with
`aset' (*note Array Functions::).  `(aset STRING IDX CHAR)' stores CHAR
into STRING at index IDX.  Each character occupies one or more bytes,
and if CHAR needs a different number of bytes from the character
already present at that index, `aset' signals an error.

   A more powerful function is `store-substring':

 -- Function: store-substring string idx obj
     This function alters part of the contents of the string STRING, by
     storing OBJ starting at index IDX.  The argument OBJ may be either
     a character or a (smaller) string.

     Since it is impossible to change the length of an existing string,
     it is an error if OBJ doesn't fit within STRING's actual length,
     or if any new character requires a different number of bytes from
     the character currently present at that point in STRING.

   To clear out a string that contained a password, use `clear-string':

 -- Function: clear-string string
     This makes STRING a unibyte string and clears its contents to
     zeros.  It may also change STRING's length.

File: elisp,  Node: Text Comparison,  Next: String Conversion,  Prev: Modifying Strings,  Up: Strings and Characters

4.5 Comparison of Characters and Strings
========================================

 -- Function: char-equal character1 character2
     This function returns `t' if the arguments represent the same
     character, `nil' otherwise.  This function ignores differences in
     case if `case-fold-search' is non-`nil'.

          (char-equal ?x ?x)
               => t
          (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.  Symbols are also allowed as arguments, in which
     case their print names are used.  Case is always significant,
     regardless of `case-fold-search'.

          (string= "abc" "abc")
               => t
          (string= "abc" "ABC")
               => nil
          (string= "ab" "ABC")
               => nil

     The function `string=' ignores the text properties of the two
     strings.  When `equal' (*note Equality Predicates::) compares two
     strings, it uses `string='.

     For technical reasons, a unibyte and a multibyte string are
     `equal' if and only if they contain the same sequence of character
     codes and all these codes are either in the range 0 through 127
     (ASCII) or 160 through 255 (`eight-bit-graphic').  However, when a
     unibyte string is converted to a multibyte string, all characters
     with codes in the range 160 through 255 are converted to
     characters with higher codes, whereas ASCII characters remain
     unchanged.  Thus, a unibyte string and its conversion to multibyte
     are only `equal' if the string is all ASCII.  Character codes 160
     through 255 are not entirely proper in multibyte text, even though
     they can occur.  As a consequence, the situation where a unibyte
     and a multibyte string are `equal' without both being all ASCII is
     a technical oddity that very few Emacs Lisp programmers ever get
     confronted with.  *Note Text Representations::.

 -- 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.  It
     scans both the strings at the same time to find the first pair of
     corresponding characters that do not match.  If the lesser
     character of these 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 according to their character
     codes.  Keep in mind that lower case letters have higher numeric
     values in the ASCII character set than their upper case
     counterparts; digits and many punctuation characters have a lower
     numeric value than upper case letters.  An ASCII character is less
     than any non-ASCII character; a unibyte non-ASCII character is
     always less than any multibyte non-ASCII character (*note Text
     Representations::).

          (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

     Symbols are also allowed as arguments, in which case their print
     names are used.

 -- Function: string-lessp string1 string2
     `string-lessp' is another name for `string<'.

 -- Function: compare-strings string1 start1 end1 string2 start2 end2
          &optional ignore-case
     This function compares the specified part of STRING1 with the
     specified part of STRING2.  The specified part of STRING1 runs
     from index START1 up to index END1 (`nil' means the end of the
     string).  The specified part of STRING2 runs from index START2 up
     to index END2 (`nil' means the end of the string).

     The strings are both converted to multibyte for the comparison
     (*note Text Representations::) so that a unibyte string and its
     conversion to multibyte are always regarded as equal.  If
     IGNORE-CASE is non-`nil', then case is ignored, so that upper case
     letters can be equal to lower case letters.

     If the specified portions of the two strings match, the value is
     `t'.  Otherwise, the value is an integer which indicates how many
     leading characters agree, and which string is less.  Its absolute
     value is one plus the number of characters that agree at the
     beginning of the two strings.  The sign is negative if STRING1 (or
     its specified portion) is less.

 -- Function: assoc-string key alist &optional case-fold
     This function works like `assoc', except that KEY must be a string
     or symbol, and comparison is done using `compare-strings'.
     Symbols are converted to strings before testing.  If CASE-FOLD is
     non-`nil', it ignores case differences.  Unlike `assoc', this
     function can also match elements of the alist that are strings or
     symbols rather than conses.  In particular, ALIST can be a list of
     strings or symbols rather than an actual alist.  *Note Association
     Lists::.

   See also the function `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: elisp,  Node: String Conversion,  Next: Formatting Strings,  Prev: Text Comparison,  Up: Strings and Characters

4.6 Conversion of Characters and Strings
========================================

This section describes functions for converting between characters,
strings and integers.  `format' (*note Formatting Strings::) 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.  The
functions `string-make-multibyte' and `string-make-unibyte' convert the
text representation of a string (*note Converting Representations::).

   *Note Documentation::, for functions that produce textual
descriptions of text characters and general input events
(`single-key-description' and `text-char-description').  These are used
primarily for making help messages.

 -- Function: char-to-string character
     This function returns a new string containing one character,
     CHARACTER.  This function is semi-obsolete because the function
     `string' is more general.  *Note Creating Strings::.

 -- Function: string-to-char string
     This function returns the first character in STRING.  If the
     string is empty, the function returns 0.  The value is also 0 when
     the first character of STRING is the null character, ASCII code 0.

          (string-to-char "ABC")
               => 65

          (string-to-char "xyz")
               => 120
          (string-to-char "")
               => 0
          (string-to-char "\000")
               => 0

     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 base-ten
     representation of NUMBER, which may be an integer or a floating
     point number.  The returned value starts with a minus 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 of the characters in
     STRING.  If BASE is non-`nil', it must be an integer between 2 and
     16 (inclusive), and integers are converted in that base.  If BASE
     is `nil', then base ten is used.  Floating point conversion only
     works in base ten; we have not implemented other radices for
     floating point numbers, because that would be much more work and
     does not seem useful.  If STRING looks like an integer but its
     value is too large to fit into a Lisp integer, `string-to-number'
     returns a floating point result.

     The parsing skips spaces and tabs at the beginning of STRING, then
     reads as much of STRING as it can interpret as a number in the
     given base.  (On some systems it ignores other whitespace at the
     beginning, not just spaces and tabs.)  If the first character after
     the ignored whitespace is neither a digit in the given base, nor a
     plus or minus sign, nor the leading dot of a floating point number,
     this function returns 0.

          (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 "1e5")
               => 100000.0

     `string-to-int' is an obsolete alias for this function.

   Here are some other functions that can convert to or from a string:

`concat'
     `concat' can convert a vector or a list into a string.  *Note
     Creating Strings::.

`vconcat'
     `vconcat' can convert a string into a vector.  *Note Vector
     Functions::.

`append'
     `append' can convert a string into a list.  *Note Building Lists::.

File: elisp,  Node: Formatting Strings,  Next: Case Conversion,  Prev: String Conversion,  Up: Strings and Characters

4.7 Formatting Strings
======================

"Formatting" means constructing a string by substituting computed
values at various places in a constant string.  This constant string
controls how the other values are printed, as well as where they
appear; it is called a "format string".

   Formatting is often useful for computing messages to be displayed.
In fact, the functions `message' and `error' provide the same
formatting feature described here; they differ from `format' only in
how they use the result of formatting.

 -- Function: format string &rest objects
     This function returns a new string that is made by copying STRING
     and then replacing any format specification in the copy with
     encodings of the corresponding OBJECTS.  The arguments OBJECTS are
     the computed values to be formatted.

     The characters in STRING, other than the format specifications,
     are copied directly into the output, including their text
     properties, if any.

   A format specification is a sequence of characters beginning with a
`%'.  Thus, if there is a `%d' in STRING, the `format' function
replaces it with the printed representation of one of the values to be
formatted (one of the arguments OBJECTS).  For example:

     (format "The value of fill-column is %d." fill-column)
          => "The value of fill-column is 72."

   Since `format' interprets `%' characters as format specifications,
you should _never_ pass an arbitrary string as the first argument.
This is particularly true when the string is generated by some Lisp
code.  Unless the string is _known_ to never include any `%'
characters, pass `"%s"', described below, as the first argument, and
the string as the second, like this:

       (format "%s" ARBITRARY-STRING)

   If STRING contains more than one format specification, the format
specifications correspond to successive values from OBJECTS.  Thus, the
first format specification in STRING uses the first such value, the
second format specification uses the second such value, and so on.  Any
extra format specifications (those for which there are no corresponding
values) cause an error.  Any extra values to be formatted are ignored.

   Certain format specifications require values of particular types.  If
you supply a value that doesn't fit the requirements, an error is
signaled.

   Here is a table of valid format specifications:

`%s'
     Replace the specification with the printed representation of the
     object, made without quoting (that is, using `princ', not
     `prin1'--*note Output Functions::).  Thus, strings are represented
     by their contents alone, with no `"' characters, and symbols appear
     without `\' characters.

     If the object is a string, its text properties are copied into the
     output.  The text properties of the `%s' itself are also copied,
     but those of the object take priority.

`%S'
     Replace the specification with the printed representation of the
     object, made with quoting (that is, using `prin1'--*note Output
     Functions::).  Thus, strings are enclosed in `"' characters, and
     `\' characters appear where necessary before special characters.

`%o'
     Replace the specification with the base-eight representation of an
     integer.

`%d'
     Replace the specification with the base-ten representation of an
     integer.

`%x'
`%X'
     Replace the specification with the base-sixteen representation of
     an integer.  `%x' uses lower case and `%X' uses upper case.

`%c'
     Replace the specification with the character which is the value
     given.

`%e'
     Replace the specification with the exponential notation for a
     floating point number.

`%f'
     Replace the specification with the decimal-point notation for a
     floating point number.

`%g'
     Replace the specification with notation for a floating point
     number, using either exponential notation or decimal-point
     notation, whichever is shorter.

`%%'
     Replace the specification with a single `%'.  This format
     specification is unusual in that it does not use a value.  For
     example, `(format "%% %d" 30)' returns `"% 30"'.

   Any other format character results in an `Invalid format operation'
error.

   Here are several examples:

     (format "The name of this buffer is %s." (buffer-name))
          => "The name of this buffer is strings.texi."

     (format "The buffer object prints as %s." (current-buffer))
          => "The buffer object prints as strings.texi."

     (format "The octal value of %d is %o,
              and the hex value is %x." 18 18 18)
          => "The octal value of 18 is 22,
              and the hex value is 12."

   A specification can have a "width", which is a decimal number
between the `%' and the specification character.  If the printed
representation of the object contains fewer characters than this width,
`format' extends it with padding.  The width specifier is ignored for
the `%%' specification.  Any padding introduced by the width specifier
normally consists of spaces inserted on the left:

     (format "%5d is padded on the left with spaces" 123)
          => "  123 is padded on the left with spaces"

If the width is too small, `format' does not truncate the object's
printed representation.  Thus, you can use a width to specify a minimum
spacing between columns with no risk of losing information.  In the
following three examples, `%7s' specifies a minimum width of 7.  In the
first case, the string inserted in place of `%7s' has only 3 letters,
and needs 4 blank spaces as padding.  In the second case, the string
`"specification"' is 13 letters wide but is not truncated.

     (format "The word `%7s' actually has %d letters in it."
             "foo" (length "foo"))
          => "The word `    foo' actually has 3 letters in it."
     (format "The word `%7s' actually has %d letters in it."
             "specification" (length "specification"))
          => "The word `specification' actually has 13 letters in it."

   Immediately after the `%' and before the optional width specifier,
you can also put certain "flag characters".

   The flag `+' inserts a plus sign before a positive number, so that
it always has a sign.  A space character as flag inserts a space before
a positive number.  (Otherwise, positive numbers start with the first
digit.)  These flags are useful for ensuring that positive numbers and
negative numbers use the same number of columns.  They are ignored
except for `%d', `%e', `%f', `%g', and if both flags are used, `+'
takes precedence.

   The flag `#' specifies an "alternate form" which depends on the
format in use.  For `%o', it ensures that the result begins with a `0'.
For `%x' and `%X', it prefixes the result with `0x' or `0X'.  For `%e',
`%f', and `%g', the `#' flag means include a decimal point even if the
precision is zero.

   The flag `-' causes the padding inserted by the width specifier, if
any, to be inserted on the right rather than the left.  The flag `0'
ensures that the padding consists of `0' characters instead of spaces,
inserted on the left.  These flags are ignored for specification
characters for which they do not make sense: `%s', `%S' and `%c' accept
the `0' flag, but still pad with _spaces_ on the left.  If both `-' and
`0' are present and valid, `-' takes precedence.

     (format "%06d is padded on the left with zeros" 123)
          => "000123 is padded on the left with zeros"

     (format "%-6d is padded on the right" 123)
          => "123    is padded on the right"

     (format "The word `%-7s' actually has %d letters in it."
             "foo" (length "foo"))
          => "The word `foo    ' actually has 3 letters in it."

   All the specification characters allow an optional "precision"
before the character (after the width, if present).  The precision is a
decimal-point `.' followed by a digit-string.  For the floating-point
specifications (`%e', `%f', `%g'), the precision specifies how many
decimal places to show; if zero, the decimal-point itself is also
omitted.  For `%s' and `%S', the precision truncates the string to the
given width, so `%.3s' shows only the first three characters of the
representation for OBJECT.  Precision has no effect for other
specification characters.

File: elisp,  Node: Case Conversion,  Next: Case Tables,  Prev: Formatting Strings,  Up: Strings and Characters

4.8 Case Conversion in Lisp
===========================

The character case functions change the case of single characters or of
the contents of strings.  The functions normally convert only
alphabetic characters (the letters `A' through `Z' and `a' through `z',
as well as non-ASCII letters); other characters are not altered.  You
can specify a different case conversion mapping by specifying a case
table (*note Case Tables::).

   These functions do not modify the strings that are passed to them as
arguments.

   The examples below use the characters `X' and `x' which have ASCII
codes 88 and 120 respectively.

 -- Function: downcase string-or-char
     This function converts STRING-OR-CHAR, which should be either a
     character or a string, to lower case.

     When STRING-OR-CHAR is a string, this function returns a new
     string in which each letter in the argument that is upper case is
     converted to lower case.  When STRING-OR-CHAR is a character, this
     function returns the corresponding lower case character (an
     integer); if the original character is lower case, or is not a
     letter, the return value is equal to the original character.

          (downcase "The cat in the hat")
               => "the cat in the hat"

          (downcase ?X)
               => 120

 -- Function: upcase string-or-char
     This function converts STRING-OR-CHAR, which should be either a
     character or a string, to upper case.

     When STRING-OR-CHAR is a string, this function returns a new
     string in which each letter in the argument that is lower case is
     converted to upper case.  When STRING-OR-CHAR is a character, this
     function returns the corresponding upper case character (an an
     integer); if the original character is upper case, or is not a
     letter, the return value is equal to the original character.

          (upcase "The cat in the hat")
               => "THE CAT IN THE HAT"

          (upcase ?x)
               => 88

 -- Function: capitalize string-or-char
     This function capitalizes strings or characters.  If
     STRING-OR-CHAR is a string, the function returns a new string
     whose contents are a copy of STRING-OR-CHAR in which each word has
     been capitalized.  This means that the first character of each
     word is converted to upper case, and the rest are converted to
     lower case.

     The definition of a word is any sequence of consecutive characters
     that are assigned to the word constituent syntax class in the
     current syntax table (*note Syntax Class Table::).

     When STRING-OR-CHAR is a character, this function does the same
     thing as `upcase'.

          (capitalize "The cat in the hat")
               => "The Cat In The Hat"

          (capitalize "THE 77TH-HATTED CAT")
               => "The 77th-Hatted Cat"

          (capitalize ?x)
               => 88

 -- Function: upcase-initials string-or-char
     If STRING-OR-CHAR is a string, this function capitalizes the
     initials of the words in STRING-OR-CHAR, without altering any
     letters other than the initials.  It returns a new string whose
     contents are a copy of STRING-OR-CHAR, in which each word has had
     its initial letter converted to upper case.

     The definition of a word is any sequence of consecutive characters
     that are assigned to the word constituent syntax class in the
     current syntax table (*note Syntax Class Table::).

     When the argument to `upcase-initials' is a character,
     `upcase-initials' has the same result as `upcase'.

          (upcase-initials "The CAT in the hAt")
               => "The CAT In The HAt"

   *Note Text Comparison::, for functions that compare strings; some of
them ignore case differences, or can optionally ignore case differences.

File: elisp,  Node: Case Tables,  Prev: Case Conversion,  Up: Strings and Characters

4.9 The Case Table
==================

You can customize case conversion by installing a special "case table".
A case table specifies the mapping between upper case and lower case
letters.  It affects both the case conversion functions for Lisp
objects (see the previous section) and those that apply to text in the
buffer (*note Case Changes::).  Each buffer has a case table; there is
also a standard case table which is used to initialize the case table
of new buffers.

   A case table is a char-table (*note Char-Tables::) whose subtype is
`case-table'.  This char-table maps each character into the
corresponding lower case character.  It has three extra slots, which
hold related tables:

UPCASE
     The upcase table maps each character into the corresponding upper
     case character.

CANONICALIZE
     The canonicalize table maps all of a set of case-related characters
     into a particular member of that set.

EQUIVALENCES
     The equivalences table maps each one of a set of case-related
     characters into the next character in that set.

   In simple cases, all you need to specify is the mapping to
lower-case; the three related tables will be calculated automatically
from that one.

   For some languages, upper and lower case letters are not in
one-to-one correspondence.  There may be two different lower case
letters with the same upper case equivalent.  In these cases, you need
to specify the maps for both lower case and upper case.

   The extra table CANONICALIZE maps each character to a canonical
equivalent; any two characters that are related by case-conversion have
the same canonical equivalent character.  For example, since `a' and
`A' are related by case-conversion, they should have the same canonical
equivalent character (which should be either `a' for both of them, or
`A' for both of them).

   The extra table EQUIVALENCES is a map that cyclically permutes each
equivalence class (of characters with the same canonical equivalent).
(For ordinary ASCII, this would map `a' into `A' and `A' into `a', and
likewise for each set of equivalent characters.)

   When constructing a case table, you can provide `nil' for
CANONICALIZE; then Emacs fills in this slot from the lower case and
upper case mappings.  You can also provide `nil' for EQUIVALENCES; then
Emacs fills in this slot from CANONICALIZE.  In a case table that is
actually in use, those components are non-`nil'.  Do not try to specify
EQUIVALENCES without also specifying CANONICALIZE.

   Here are the functions for working with case tables:

 -- Function: case-table-p object
     This predicate returns non-`nil' if OBJECT is a valid case table.

 -- Function: set-standard-case-table table
     This function makes TABLE the standard case table, so that it will
     be used in any buffers created subsequently.

 -- Function: standard-case-table
     This returns the standard case table.

 -- Function: current-case-table
     This function returns the current buffer's case table.

 -- Function: set-case-table table
     This sets the current buffer's case table to TABLE.

 -- Macro: with-case-table table body...
     The `with-case-table' macro saves the current case table, makes
     TABLE the current case table, evaluates the BODY forms, and
     finally restores the case table.  The return value is the value of
     the last form in BODY.  The case table is restored even in case of
     an abnormal exit via `throw' or error (*note Nonlocal Exits::).

   Some language environments modify the case conversions of ASCII
characters; for example, in the Turkish language environment, the ASCII
character `I' is downcased into a Turkish "dotless i".  This can
interfere with code that requires ordinary ASCII case conversion, such
as implementations of ASCII-based network protocols.  In that case, use
the `with-case-table' macro with the variable ASCII-CASE-TABLE, which
stores the unmodified case table for the ASCII character set.

 -- Variable: ascii-case-table
     The case table for the ASCII character set.  This should not be
     modified by any language environment settings.

   The following three functions are convenient subroutines for packages
that define non-ASCII character sets.  They modify the specified case
table CASE-TABLE; they also modify the standard syntax table.  *Note
Syntax Tables::.  Normally you would use these functions to change the
standard case table.

 -- Function: set-case-syntax-pair uc lc case-table
     This function specifies a pair of corresponding letters, one upper
     case and one lower case.

 -- Function: set-case-syntax-delims l r case-table
     This function makes characters L and R a matching pair of
     case-invariant delimiters.

 -- Function: set-case-syntax char syntax case-table
     This function makes CHAR case-invariant, with syntax SYNTAX.

 -- Command: describe-buffer-case-table
     This command displays a description of the contents of the current
     buffer's case table.

File: elisp,  Node: Lists,  Next: Sequences Arrays Vectors,  Prev: Strings and Characters,  Up: Top

5 Lists
*******

A "list" represents a sequence of zero or more elements (which may be
any Lisp objects).  The important difference between lists and vectors
is that two or more lists can share part of their structure; in
addition, you can insert or delete elements in a list without copying
the whole list.

* Menu:

* Cons Cells::          How lists are made out of cons cells.
* List-related Predicates::        Is this object a list?  Comparing two lists.
* List Elements::       Extracting the pieces of a list.
* Building Lists::      Creating list structure.
* List Variables::      Modifying lists stored in variables.
* 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.
* Rings::               Managing a fixed-size ring of objects.

File: elisp,  Node: Cons Cells,  Next: List-related Predicates,  Up: Lists

5.1 Lists and Cons Cells
========================

Lists in Lisp are not a primitive data type; they are built up from
"cons cells".  A cons cell is a data object that represents an ordered
pair.  That is, it has two slots, and each slot "holds", or "refers
to", some Lisp object.  One slot is known as the CAR, and the other is
known as the CDR.  (These names are traditional; see *note Cons Cell
Type::.)  CDR is pronounced "could-er."

   We say that "the CAR of this cons cell is" whatever object its CAR
slot currently holds, and likewise for the CDR.

   A list is a series of cons cells "chained together," so that each
cell refers to the next one.  There is one cons cell for each element of
the list.  By convention, the CARs of the cons cells hold the elements
of the list, and the CDRs are used to chain the list: the CDR slot of
each cons cell refers to the following cons cell.  The CDR of the last
cons cell is `nil'.  This asymmetry between the CAR and the CDR is
entirely a matter of convention; at the level of cons cells, the CAR
and CDR slots have the same characteristics.

   Since `nil' is the conventional value to put in the CDR of the last
cons cell in the list, we call that case a "true list".

   In Lisp, we consider the symbol `nil' a list as well as a symbol; it
is the list with no elements.  For convenience, the symbol `nil' is
considered to have `nil' as its CDR (and also as its CAR).  Therefore,
the CDR of a true list is always a true list.

   If the CDR of a list's last cons cell is some other value, neither
`nil' nor another cons cell, we call the structure a "dotted list",
since its printed representation would use `.'.  There is one other
possibility: some cons cell's CDR could point to one of the previous
cons cells in the list.  We call that structure a "circular list".

   For some purposes, it does not matter whether a list is true,
circular or dotted.  If the program doesn't look far enough down the
list to see the CDR of the final cons cell, it won't care.  However,
some functions that operate on lists demand true lists and signal
errors if given a dotted list.  Most functions that try to find the end
of a list enter infinite loops if given a circular list.

   Because most cons cells are used as part of lists, the phrase "list
structure" has come to mean any structure made out of cons cells.

   The CDR of any nonempty true list L is a list containing all the
elements of L except the first.

   *Note Cons Cell Type::, for the read and print syntax of cons cells
and lists, and for "box and arrow" illustrations of lists.

File: elisp,  Node: List-related Predicates,  Next: List Elements,  Prev: Cons Cells,  Up: Lists

5.2 Predicates on Lists
=======================

The following predicates test whether a Lisp object is an atom, whether
it is a cons cell or is a list, or whether it is the distinguished
object `nil'.  (Many of these predicates can be defined in terms of the
others, but they are used so often that it is worth having all of them.)

 -- Function: consp object
     This function returns `t' if OBJECT is a cons cell, `nil'
     otherwise.  `nil' is not a cons cell, although it _is_ a list.

 -- Function: atom object
     This function returns `t' if OBJECT is an atom, `nil' otherwise.
     All objects except cons cells are atoms.  The symbol `nil' is an
     atom and is also a list; it is the only Lisp object that is both.

          (atom OBJECT) == (not (consp OBJECT))

 -- Function: listp object
     This function returns `t' if OBJECT is a cons cell or `nil'.
     Otherwise, it returns `nil'.

          (listp '(1))
               => t
          (listp '())
               => t

 -- Function: nlistp object
     This function is the opposite of `listp': it returns `t' if OBJECT
     is not a list.  Otherwise, it returns `nil'.

          (listp OBJECT) == (not (nlistp OBJECT))

 -- Function: null object
     This function returns `t' if OBJECT is `nil', and returns `nil'
     otherwise.  This function is identical to `not', but as a matter
     of clarity we use `null' when OBJECT is considered a list and
     `not' when it is considered a truth value (see `not' in *note
     Combining Conditions::).

          (null '(1))
               => nil
          (null '())
               => t

File: elisp,  Node: List Elements,  Next: Building Lists,  Prev: List-related Predicates,  Up: Lists

5.3 Accessing Elements of Lists
===============================

 -- Function: car cons-cell
     This function returns the value referred to by the first slot of
     the cons cell CONS-CELL.  In other words, it returns the CAR of
     CONS-CELL.

     As a special case, if CONS-CELL is `nil', this function returns
     `nil'.  Therefore, any list is a valid argument.  An error is
     signaled if the argument is not a cons cell or `nil'.

          (car '(a b c))
               => a
          (car '())
               => nil

 -- Function: cdr cons-cell
     This function returns the value referred to by the second slot of
     the cons cell CONS-CELL.  In other words, it returns the CDR of
     CONS-CELL.

     As a special case, if CONS-CELL is `nil', this function returns
     `nil'; therefore, any list is a valid argument.  An error is
     signaled if the argument is not a cons cell or `nil'.

          (cdr '(a b c))
               => (b c)
          (cdr '())
               => nil

 -- Function: car-safe object
     This function lets you take the CAR of a cons cell while avoiding
     errors for other data types.  It returns the CAR of OBJECT if
     OBJECT is a cons cell, `nil' otherwise.  This is in contrast to
     `car', which signals an error if OBJECT is not a list.

          (car-safe OBJECT)
          ==
          (let ((x OBJECT))
            (if (consp x)
                (car x)
              nil))

 -- Function: cdr-safe object
     This function lets you take the CDR of a cons cell while avoiding
     errors for other data types.  It returns the CDR of OBJECT if
     OBJECT is a cons cell, `nil' otherwise.  This is in contrast to
     `cdr', which signals an error if OBJECT is not a list.

          (cdr-safe OBJECT)
          ==
          (let ((x OBJECT))
            (if (consp x)
                (cdr x)
              nil))

 -- Macro: pop listname
     This macro is a way of examining the CAR of a list, and taking it
     off the list, all at once.

     It operates on the list which is stored in the symbol LISTNAME.
     It removes this element from the list by setting LISTNAME to the
     CDR of its old value--but it also returns the CAR of that list,
     which is the element being removed.

          x
               => (a b c)
          (pop x)
               => a
          x
               => (b c)

 -- Function: nth n list
     This function returns the Nth element of LIST.  Elements are
     numbered starting with zero, so the CAR of LIST is element number
     zero.  If the length of LIST is N or less, the value is `nil'.

     If N is negative, `nth' returns the first element of LIST.

          (nth 2 '(1 2 3 4))
               => 3
          (nth 10 '(1 2 3 4))
               => nil
          (nth -3 '(1 2 3 4))
               => 1

          (nth n x) == (car (nthcdr n x))

     The function `elt' is similar, but applies to any kind of sequence.
     For historical reasons, it takes its arguments in the opposite
     order.  *Note Sequence Functions::.

 -- Function: nthcdr n list
     This function returns the Nth CDR of LIST.  In other words, it
     skips past the first N links of LIST and returns what follows.

     If N is zero or negative, `nthcdr' returns all of LIST.  If the
     length of LIST is N or less, `nthcdr' returns `nil'.

          (nthcdr 1 '(1 2 3 4))
               => (2 3 4)
          (nthcdr 10 '(1 2 3 4))
               => nil
          (nthcdr -3 '(1 2 3 4))
               => (1 2 3 4)

 -- Function: last list &optional n
     This function returns the last link of LIST.  The `car' of this
     link is the list's last element.  If LIST is null, `nil' is
     returned.  If N is non-`nil', the Nth-to-last link is returned
     instead, or the whole of LIST if N is bigger than LIST's length.

 -- Function: safe-length list
     This function returns the length of LIST, with no risk of either
     an error or an infinite loop.  It generally returns the number of
     distinct cons cells in the list.  However, for circular lists, the
     value is just an upper bound; it is often too large.

     If LIST is not `nil' or a cons cell, `safe-length' returns 0.

   The most common way to compute the length of a list, when you are not
worried that it may be circular, is with `length'.  *Note Sequence
Functions::.

 -- Function: caar cons-cell
     This is the same as `(car (car CONS-CELL))'.

 -- Function: cadr cons-cell
     This is the same as `(car (cdr CONS-CELL))' or `(nth 1 CONS-CELL)'.

 -- Function: cdar cons-cell
     This is the same as `(cdr (car CONS-CELL))'.

 -- Function: cddr cons-cell
     This is the same as `(cdr (cdr CONS-CELL))' or `(nthcdr 2
     CONS-CELL)'.

 -- Function: butlast x &optional n
     This function returns the list X with the last element, or the
     last N elements, removed.  If N is greater than zero it makes a
     copy of the list so as not to damage the original list.  In
     general, `(append (butlast X N) (last X N))' will return a list
     equal to X.

 -- Function: nbutlast x &optional n
     This is a version of `butlast' that works by destructively
     modifying the `cdr' of the appropriate element, rather than making
     a copy of the list.

File: elisp,  Node: Building Lists,  Next: List Variables,  Prev: List Elements,  Up: Lists

5.4 Building Cons Cells and Lists
=================================

Many functions build lists, as lists reside at the very heart of Lisp.
`cons' is the fundamental list-building function; however, it is
interesting to note that `list' is used more times in the source code
for Emacs than `cons'.

 -- Function: cons object1 object2
     This function is the most basic function for building new list
     structure.  It creates a new cons cell, making OBJECT1 the CAR,
     and OBJECT2 the CDR.  It then returns the new cons cell.  The
     arguments OBJECT1 and OBJECT2 may be any Lisp objects, but most
     often OBJECT2 is a list.

          (cons 1 '(2))
               => (1 2)
          (cons 1 '())
               => (1)
          (cons 1 2)
               => (1 . 2)

     `cons' is often used to add a single element to the front of a
     list.  This is called "consing the element onto the list".  (1)
     For example:

          (setq list (cons newelt list))

     Note that there is no conflict between the variable named `list'
     used in this example and the function named `list' described below;
     any symbol can serve both purposes.

 -- Function: list &rest objects
     This function creates a list with OBJECTS as its elements.  The
     resulting list is always `nil'-terminated.  If no OBJECTS are
     given, the empty list is returned.

          (list 1 2 3 4 5)
               => (1 2 3 4 5)
          (list 1 2 '(3 4 5) 'foo)
               => (1 2 (3 4 5) foo)
          (list)
               => nil

 -- Function: make-list length object
     This function creates a list of LENGTH elements, in which each
     element is OBJECT.  Compare `make-list' with `make-string' (*note
     Creating Strings::).

          (make-list 3 'pigs)
               => (pigs pigs pigs)
          (make-list 0 'pigs)
               => nil
          (setq l (make-list 3 '(a b))
               => ((a b) (a b) (a b))
          (eq (car l) (cadr l))
               => t

 -- Function: append &rest sequences
     This function returns a list containing all the elements of
     SEQUENCES.  The SEQUENCES may be lists, vectors, bool-vectors, or
     strings, but the last one should usually be a list.  All arguments
     except the last one are copied, so none of the arguments is
     altered.  (See `nconc' in *note Rearrangement::, for a way to join
     lists with no copying.)

     More generally, the final argument to `append' may be any Lisp
     object.  The final argument is not copied or converted; it becomes
     the CDR of the last cons cell in the new list.  If the final
     argument is itself a list, then its elements become in effect
     elements of the result list.  If the final element is not a list,
     the result is a dotted list since its final CDR is not `nil' as
     required in a true list.

   Here is an example of using `append':

     (setq trees '(pine oak))
          => (pine oak)
     (setq more-trees (append '(maple birch) trees))
          => (maple birch pine oak)

     trees
          => (pine oak)
     more-trees
          => (maple birch pine oak)
     (eq trees (cdr (cdr more-trees)))
          => t

   You can see how `append' works by looking at a box diagram.  The
variable `trees' is set to the list `(pine oak)' and then the variable
`more-trees' is set to the list `(maple birch pine oak)'.  However, the
variable `trees' continues to refer to the original list:

     more-trees                trees
     |                           |
     |     --- ---      --- ---   -> --- ---      --- ---
      --> |   |   |--> |   |   |--> |   |   |--> |   |   |--> nil
           --- ---      --- ---      --- ---      --- ---
            |            |            |            |
            |            |            |            |
             --> maple    -->birch     --> pine     --> oak

   An empty sequence contributes nothing to the value returned by
`append'.  As a consequence of this, a final `nil' argument forces a
copy of the previous argument:

     trees
          => (pine oak)
     (setq wood (append trees nil))
          => (pine oak)
     wood
          => (pine oak)
     (eq wood trees)
          => nil

This once was the usual way to copy a list, before the function
`copy-sequence' was invented.  *Note Sequences Arrays Vectors::.

   Here we show the use of vectors and strings as arguments to `append':

     (append [a b] "cd" nil)
          => (a b 99 100)

   With the help of `apply' (*note Calling Functions::), we can append
all the lists in a list of lists:

     (apply 'append '((a b c) nil (x y z) nil))
          => (a b c x y z)

   If no SEQUENCES are given, `nil' is returned:

     (append)
          => nil

   Here are some examples where the final argument is not a list:

     (append '(x y) 'z)
          => (x y . z)
     (append '(x y) [z])
          => (x y . [z])

The second example shows that when the final argument is a sequence but
not a list, the sequence's elements do not become elements of the
resulting list.  Instead, the sequence becomes the final CDR, like any
other non-list final argument.

 -- Function: reverse list
     This function creates a new list whose elements are the elements of
     LIST, but in reverse order.  The original argument LIST is _not_
     altered.

          (setq x '(1 2 3 4))
               => (1 2 3 4)
          (reverse x)
               => (4 3 2 1)
          x
               => (1 2 3 4)

 -- Function: copy-tree tree &optional vecp
     This function returns a copy of the tree `tree'.  If TREE is a
     cons cell, this makes a new cons cell with the same CAR and CDR,
     then recursively copies the CAR and CDR in the same way.

     Normally, when TREE is anything other than a cons cell,
     `copy-tree' simply returns TREE.  However, if VECP is non-`nil',
     it copies vectors too (and operates recursively on their elements).

 -- Function: number-sequence from &optional to separation
     This returns a list of numbers starting with FROM and incrementing
     by SEPARATION, and ending at or just before TO.  SEPARATION can be
     positive or negative and defaults to 1.  If TO is `nil' or
     numerically equal to FROM, the value is the one-element list
     `(FROM)'.  If TO is less than FROM with a positive SEPARATION, or
     greater than FROM with a negative SEPARATION, the value is `nil'
     because those arguments specify an empty sequence.

     If SEPARATION is 0 and TO is neither `nil' nor numerically equal
     to FROM, `number-sequence' signals an error, since those arguments
     specify an infinite sequence.

     All arguments can be integers or floating point numbers.  However,
     floating point arguments can be tricky, because floating point
     arithmetic is inexact.  For instance, depending on the machine, it
     may quite well happen that `(number-sequence 0.4 0.6 0.2)' returns
     the one element list `(0.4)', whereas `(number-sequence 0.4 0.8
     0.2)' returns a list with three elements.  The Nth element of the
     list is computed by the exact formula `(+ FROM (* N SEPARATION))'.
     Thus, if one wants to make sure that TO is included in the list,
     one can pass an expression of this exact type for TO.
     Alternatively, one can replace TO with a slightly larger value (or
     a slightly more negative value if SEPARATION is negative).

     Some examples:

          (number-sequence 4 9)
               => (4 5 6 7 8 9)
          (number-sequence 9 4 -1)
               => (9 8 7 6 5 4)
          (number-sequence 9 4 -2)
               => (9 7 5)
          (number-sequence 8)
               => (8)
          (number-sequence 8 5)
               => nil
          (number-sequence 5 8 -1)
               => nil
          (number-sequence 1.5 6 2)
               => (1.5 3.5 5.5)

   ---------- Footnotes ----------

   (1) There is no strictly equivalent way to add an element to the end
of a list.  You can use `(append LISTNAME (list NEWELT))', which
creates a whole new list by copying LISTNAME and adding NEWELT to its
end.  Or you can use `(nconc LISTNAME (list NEWELT))', which modifies
LISTNAME by following all the CDRs and then replacing the terminating
`nil'.  Compare this to adding an element to the beginning of a list
with `cons', which neither copies nor modifies the list.

File: elisp,  Node: List Variables,  Next: Modifying Lists,  Prev: Building Lists,  Up: Lists

5.5 Modifying List Variables
============================

These functions, and one macro, provide convenient ways to modify a
list which is stored in a variable.

 -- Macro: push newelt listname
     This macro provides an alternative way to write `(setq LISTNAME
     (cons NEWELT LISTNAME))'.

          (setq l '(a b))
               => (a b)
          (push 'c l)
               => (c a b)
          l
               => (c a b)

   Two functions modify lists that are the values of variables.

 -- Function: add-to-list symbol element &optional append compare-fn
     This function sets the variable SYMBOL by consing ELEMENT onto the
     old value, if ELEMENT is not already a member of that value.  It
     returns the resulting list, whether updated or not.  The value of
     SYMBOL had better be a list already before the call.
     `add-to-list' uses COMPARE-FN to compare ELEMENT against existing
     list members; if COMPARE-FN is `nil', it uses `equal'.

     Normally, if ELEMENT is added, it is added to the front of SYMBOL,
     but if the optional argument APPEND is non-`nil', it is added at
     the end.

     The argument SYMBOL is not implicitly quoted; `add-to-list' is an
     ordinary function, like `set' and unlike `setq'.  Quote the
     argument yourself if that is what you want.

   Here's a scenario showing how to use `add-to-list':

     (setq foo '(a b))
          => (a b)

     (add-to-list 'foo 'c)     ;; Add `c'.
          => (c a b)

     (add-to-list 'foo 'b)     ;; No effect.
          => (c a b)

     foo                       ;; `foo' was changed.
          => (c a b)

   An equivalent expression for `(add-to-list 'VAR VALUE)' is this:

     (or (member VALUE VAR)
         (setq VAR (cons VALUE VAR)))

 -- Function: add-to-ordered-list symbol element &optional order
     This function sets the variable SYMBOL by inserting ELEMENT into
     the old value, which must be a list, at the position specified by
     ORDER.  If ELEMENT is already a member of the list, its position
     in the list is adjusted according to ORDER.  Membership is tested
     using `eq'.  This function returns the resulting list, whether
     updated or not.

     The ORDER is typically a number (integer or float), and the
     elements of the list are sorted in non-decreasing numerical order.

     ORDER may also be omitted or `nil'.  Then the numeric order of
     ELEMENT stays unchanged if it already has one; otherwise, ELEMENT
     has no numeric order.  Elements without a numeric list order are
     placed at the end of the list, in no particular order.

     Any other value for ORDER removes the numeric order of ELEMENT if
     it already has one; otherwise, it is equivalent to `nil'.

     The argument SYMBOL is not implicitly quoted;
     `add-to-ordered-list' is an ordinary function, like `set' and
     unlike `setq'.  Quote the argument yourself if that is what you
     want.

     The ordering information is stored in a hash table on SYMBOL's
     `list-order' property.

   Here's a scenario showing how to use `add-to-ordered-list':

     (setq foo '())
          => nil

     (add-to-ordered-list 'foo 'a 1)     ;; Add `a'.
          => (a)

     (add-to-ordered-list 'foo 'c 3)     ;; Add `c'.
          => (a c)

     (add-to-ordered-list 'foo 'b 2)     ;; Add `b'.
          => (a b c)

     (add-to-ordered-list 'foo 'b 4)     ;; Move `b'.
          => (a c b)

     (add-to-ordered-list 'foo 'd)       ;; Append `d'.
          => (a c b d)

     (add-to-ordered-list 'foo 'e)       ;; Add `e'.
          => (a c b e d)

     foo                       ;; `foo' was changed.
          => (a c b e d)

File: elisp,  Node: Modifying Lists,  Next: Sets And Lists,  Prev: List Variables,  Up: Lists

5.6 Modifying Existing List Structure
=====================================

You can modify the CAR and CDR contents of a cons cell with the
primitives `setcar' and `setcdr'.  We call these "destructive"
operations because they change existing list structure.

     Common Lisp note: Common Lisp uses functions `rplaca' and `rplacd'
     to alter list structure; they change structure the same way as
     `setcar' and `setcdr', but the Common Lisp functions return the
     cons cell while `setcar' and `setcdr' return the new CAR or CDR.

* Menu:

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

File: elisp,  Node: Setcar,  Next: Setcdr,  Up: Modifying Lists

5.6.1 Altering List Elements with `setcar'
------------------------------------------

Changing the CAR of a cons cell is done with `setcar'.  When used on a
list, `setcar' replaces one element of a list with a different element.

 -- Function: setcar cons object
     This function stores OBJECT as the new CAR of CONS, replacing its
     previous CAR.  In other words, it changes the CAR slot of CONS to
     refer to OBJECT.  It returns the value OBJECT.  For example:

          (setq x '(1 2))
               => (1 2)
          (setcar x 4)
               => 4
          x
               => (4 2)

   When a cons cell is part of the shared structure of several lists,
storing a new CAR into the cons changes one element of each of these
lists.  Here is an example:

     ;; Create two lists that are partly shared.
     (setq x1 '(a b c))
          => (a b c)
     (setq x2 (cons 'z (cdr x1)))
          => (z b c)

     ;; Replace the CAR of a shared link.
     (setcar (cdr x1) 'foo)
          => foo
     x1                           ; Both lists are changed.
          => (a foo c)
     x2
          => (z foo c)

     ;; Replace the CAR of a link that is not shared.
     (setcar x1 'baz)
          => baz
     x1                           ; Only one list is changed.
          => (baz foo c)
     x2
          => (z foo c)

   Here is a graphical depiction of the shared structure of the two
lists in the variables `x1' and `x2', showing why replacing `b' changes
them both:

             --- ---        --- ---      --- ---
     x1---> |   |   |----> |   |   |--> |   |   |--> nil
             --- ---        --- ---      --- ---
              |        -->   |            |
              |       |      |            |
               --> a  |       --> b        --> c
                      |
            --- ---   |
     x2--> |   |   |--
            --- ---
             |
             |
              --> z

   Here is an alternative form of box diagram, showing the same
relationship:

     x1:
      --------------       --------------       --------------
     | car   | cdr  |     | car   | cdr  |     | car   | cdr  |
     |   a   |   o------->|   b   |   o------->|   c   |  nil |
     |       |      |  -->|       |      |     |       |      |
      --------------  |    --------------       --------------
                      |
     x2:              |
      --------------  |
     | car   | cdr  | |
     |   z   |   o----
     |       |      |
      --------------

File: elisp,  Node: Setcdr,  Next: Rearrangement,  Prev: Setcar,  Up: Modifying Lists

5.6.2 Altering the CDR of a List
--------------------------------

The lowest-level primitive for modifying a CDR is `setcdr':

 -- Function: setcdr cons object
     This function stores OBJECT as the new CDR of CONS, replacing its
     previous CDR.  In other words, it changes the CDR slot of CONS to
     refer to OBJECT.  It returns the value OBJECT.

   Here is an example of replacing the CDR of a list with a different
list.  All but the first element of the list are removed in favor of a
different sequence of elements.  The first element is unchanged,
because it resides in the CAR of the list, and is not reached via the
CDR.

     (setq x '(1 2 3))
          => (1 2 3)
     (setcdr x '(4))
          => (4)
     x
          => (1 4)

   You can delete elements from the middle of a list by altering the
CDRs of the cons cells in the list.  For example, here we delete the
second element, `b', from the list `(a b c)', by changing the CDR of
the first cons cell:

     (setq x1 '(a b c))
          => (a b c)
     (setcdr x1 (cdr (cdr x1)))
          => (c)
     x1
          => (a c)

   Here is the result in box notation:

                        --------------------
                       |                    |
      --------------   |   --------------   |    --------------
     | car   | cdr  |  |  | car   | cdr  |   -->| car   | cdr  |
     |   a   |   o-----   |   b   |   o-------->|   c   |  nil |
     |       |      |     |       |      |      |       |      |
      --------------       --------------        --------------

The second cons cell, which previously held the element `b', still
exists and its CAR is still `b', but it no longer forms part of this
list.

   It is equally easy to insert a new element by changing CDRs:

     (setq x1 '(a b c))
          => (a b c)
     (setcdr x1 (cons 'd (cdr x1)))
          => (d b c)
     x1
          => (a d b c)

   Here is this result in box notation:

      --------------        -------------       -------------
     | car  | cdr   |      | car  | cdr  |     | car  | cdr  |
     |   a  |   o   |   -->|   b  |   o------->|   c  |  nil |
     |      |   |   |  |   |      |      |     |      |      |
      --------- | --   |    -------------       -------------
                |      |
          -----         --------
         |                      |
         |    ---------------   |
         |   | car   | cdr   |  |
          -->|   d   |   o------
             |       |       |
              ---------------

File: elisp,  Node: Rearrangement,  Prev: Setcdr,  Up: Modifying Lists

5.6.3 Functions that Rearrange Lists
------------------------------------

Here are some functions that rearrange lists "destructively" by
modifying the CDRs of their component cons cells.  We call these
functions "destructive" because they chew up the original lists passed
to them as arguments, relinking their cons cells to form a new list that
is the returned value.

   See `delq', in *note Sets And Lists::, for another function that
modifies cons cells.

 -- Function: nconc &rest lists
     This function returns a list containing all the elements of LISTS.
     Unlike `append' (*note Building Lists::), the LISTS are _not_
     copied.  Instead, the last CDR of each of the LISTS is changed to
     refer to the following list.  The last of the LISTS is not
     altered.  For example:

          (setq x '(1 2 3))
               => (1 2 3)
          (nconc x '(4 5))
               => (1 2 3 4 5)
          x
               => (1 2 3 4 5)

     Since the last argument of `nconc' is not itself modified, it is
     reasonable to use a constant list, such as `'(4 5)', as in the
     above example.  For the same reason, the last argument need not be
     a list:

          (setq x '(1 2 3))
               => (1 2 3)
          (nconc x 'z)
               => (1 2 3 . z)
          x
               => (1 2 3 . z)

     However, the other arguments (all but the last) must be lists.

     A common pitfall is to use a quoted constant list as a non-last
     argument to `nconc'.  If you do this, your program will change
     each time you run it!  Here is what happens:

          (defun add-foo (x)            ; We want this function to add
            (nconc '(foo) x))           ;   `foo' to the front of its arg.

          (symbol-function 'add-foo)
               => (lambda (x) (nconc (quote (foo)) x))

          (setq xx (add-foo '(1 2)))    ; It seems to work.
               => (foo 1 2)
          (setq xy (add-foo '(3 4)))    ; What happened?
               => (foo 1 2 3 4)
          (eq xx xy)
               => t

          (symbol-function 'add-foo)
               => (lambda (x) (nconc (quote (foo 1 2 3 4) x)))

 -- Function: nreverse list
     This function reverses the order of the elements of LIST.  Unlike
     `reverse', `nreverse' alters its argument by reversing the CDRs in
     the cons cells forming the list.  The cons cell that used to be
     the last one in LIST becomes the first cons cell of the value.

     For example:

          (setq x '(a b c))
               => (a b c)
          x
               => (a b c)
          (nreverse x)
               => (c b a)
          ;; The cons cell that was first is now last.
          x
               => (a)

     To avoid confusion, we usually store the result of `nreverse' back
     in the same variable which held the original list:

          (setq x (nreverse x))

     Here is the `nreverse' of our favorite example, `(a b c)',
     presented graphically:

          Original list head:                       Reversed list:
           -------------        -------------        ------------
          | car  | cdr  |      | car  | cdr  |      | car | cdr  |
          |   a  |  nil |<--   |   b  |   o  |<--   |   c |   o  |
          |      |      |   |  |      |   |  |   |  |     |   |  |
           -------------    |   --------- | -    |   -------- | -
                            |             |      |            |
                             -------------        ------------

 -- Function: sort list predicate
     This function sorts LIST stably, though destructively, and returns
     the sorted list.  It compares elements using PREDICATE.  A stable
     sort is one in which elements with equal sort keys maintain their
     relative order before and after the sort.  Stability is important
     when successive sorts are used to order elements according to
     different criteria.

     The argument PREDICATE must be a function that accepts two
     arguments.  It is called with two elements of LIST.  To get an
     increasing order sort, the PREDICATE should return non-`nil' if the
     first element is "less than" the second, or `nil' if not.

     The comparison function PREDICATE must give reliable results for
     any given pair of arguments, at least within a single call to
     `sort'.  It must be "antisymmetric"; that is, if A is less than B,
     B must not be less than A.  It must be "transitive"--that is, if A
     is less than B, and B is less than C, then A must be less than C.
     If you use a comparison function which does not meet these
     requirements, the result of `sort' is unpredictable.

     The destructive aspect of `sort' is that it rearranges the cons
     cells forming LIST by changing CDRs.  A nondestructive sort
     function would create new cons cells to store the elements in their
     sorted order.  If you wish to make a sorted copy without
     destroying the original, copy it first with `copy-sequence' and
     then sort.

     Sorting does not change the CARs of the cons cells in LIST; the
     cons cell that originally contained the element `a' in LIST still
     has `a' in its CAR after sorting, but it now appears in a
     different position in the list due to the change of CDRs.  For
     example:

          (setq nums '(1 3 2 6 5 4 0))
               => (1 3 2 6 5 4 0)
          (sort nums '<)
               => (0 1 2 3 4 5 6)
          nums
               => (1 2 3 4 5 6)

     *Warning*: Note that the list in `nums' no longer contains 0; this
     is the same cons cell that it was before, but it is no longer the
     first one in the list.  Don't assume a variable that formerly held
     the argument now holds the entire sorted list!  Instead, save the
     result of `sort' and use that.  Most often we store the result
     back into the variable that held the original list:

          (setq nums (sort nums '<))

     *Note Sorting::, for more functions that perform sorting.  See
     `documentation' in *note Accessing Documentation::, for a useful
     example of `sort'.

File: elisp,  Node: Sets And Lists,  Next: Association Lists,  Prev: Modifying Lists,  Up: Lists

5.7 Using Lists as Sets
=======================

A list can represent an unordered mathematical set--simply consider a
value an element of a set if it appears in the list, and ignore the
order of the list.  To form the union of two sets, use `append' (as
long as you don't mind having duplicate elements).  You can remove
`equal' duplicates using `delete-dups'.  Other useful functions for
sets include `memq' and `delq', and their `equal' versions, `member'
and `delete'.

     Common Lisp note: Common Lisp has functions `union' (which avoids
     duplicate elements) and `intersection' for set operations, but GNU
     Emacs Lisp does not have them.  You can write them in Lisp if you
     wish.

 -- Function: memq object list
     This function tests to see whether OBJECT is a member of LIST.  If
     it is, `memq' returns a list starting with the first occurrence of
     OBJECT.  Otherwise, it returns `nil'.  The letter `q' in `memq'
     says that it uses `eq' to compare OBJECT against the elements of
     the list.  For example:

          (memq 'b '(a b c b a))
               => (b c b a)
          (memq '(2) '((1) (2)))    ; `(2)' and `(2)' are not `eq'.
               => nil

 -- Function: delq object list
     This function destructively removes all elements `eq' to OBJECT
     from LIST.  The letter `q' in `delq' says that it uses `eq' to
     compare OBJECT against the elements of the list, like `memq' and
     `remq'.

   When `delq' deletes elements from the front of the list, it does so
simply by advancing down the list and returning a sublist that starts
after those elements:

     (delq 'a '(a b c)) == (cdr '(a b c))

   When an element to be deleted appears in the middle of the list,
removing it involves changing the CDRs (*note Setcdr::).

     (setq sample-list '(a b c (4)))
          => (a b c (4))
     (delq 'a sample-list)
          => (b c (4))
     sample-list
          => (a b c (4))
     (delq 'c sample-list)
          => (a b (4))
     sample-list
          => (a b (4))

   Note that `(delq 'c sample-list)' modifies `sample-list' to splice
out the third element, but `(delq 'a sample-list)' does not splice
anything--it just returns a shorter list.  Don't assume that a variable
which formerly held the argument LIST now has fewer elements, or that
it still holds the original list!  Instead, save the result of `delq'
and use that.  Most often we store the result back into the variable
that held the original list:

     (setq flowers (delq 'rose flowers))

   In the following example, the `(4)' that `delq' attempts to match
and the `(4)' in the `sample-list' are not `eq':

     (delq '(4) sample-list)
          => (a c (4))

     If you want to delete elements that are `equal' to a given value,
     use `delete' (see below).

 -- Function: remq object list
     This function returns a copy of LIST, with all elements removed
     which are `eq' to OBJECT.  The letter `q' in `remq' says that it
     uses `eq' to compare OBJECT against the elements of `list'.

          (setq sample-list '(a b c a b c))
               => (a b c a b c)
          (remq 'a sample-list)
               => (b c b c)
          sample-list
               => (a b c a b c)

 -- Function: memql object list
     The function `memql' tests to see whether OBJECT is a member of
     LIST, comparing members with OBJECT using `eql', so floating point
     elements are compared by value.  If OBJECT is a member, `memql'
     returns a list starting with its first occurrence in LIST.
     Otherwise, it returns `nil'.

     Compare this with `memq':

          (memql 1.2 '(1.1 1.2 1.3))  ; `1.2' and `1.2' are `eql'.
               => (1.2 1.3)
          (memq 1.2 '(1.1 1.2 1.3))  ; `1.2' and `1.2' are not `eq'.
               => nil

   The following three functions are like `memq', `delq' and `remq',
but use `equal' rather than `eq' to compare elements.  *Note Equality
Predicates::.

 -- Function: member object list
     The function `member' tests to see whether OBJECT is a member of
     LIST, comparing members with OBJECT using `equal'.  If OBJECT is a
     member, `member' returns a list starting with its first occurrence
     in LIST.  Otherwise, it returns `nil'.

     Compare this with `memq':

          (member '(2) '((1) (2)))  ; `(2)' and `(2)' are `equal'.
               => ((2))
          (memq '(2) '((1) (2)))    ; `(2)' and `(2)' are not `eq'.
               => nil
          ;; Two strings with the same contents are `equal'.
          (member "foo" '("foo" "bar"))
               => ("foo" "bar")

 -- Function: delete object sequence
     If `sequence' is a list, this function destructively removes all
     elements `equal' to OBJECT from SEQUENCE.  For lists, `delete' is
     to `delq' as `member' is to `memq': it uses `equal' to compare
     elements with OBJECT, like `member'; when it finds an element that
     matches, it cuts the element out just as `delq' would.

     If `sequence' is a vector or string, `delete' returns a copy of
     `sequence' with all elements `equal' to `object' removed.

     For example:

          (setq l '((2) (1) (2)))
          (delete '(2) l)
               => ((1))
          l
               => ((2) (1))
          ;; If you want to change `l' reliably,
          ;; write `(setq l (delete elt l))'.
          (setq l '((2) (1) (2)))
          (delete '(1) l)
               => ((2) (2))
          l
               => ((2) (2))
          ;; In this case, it makes no difference whether you set `l',
          ;; but you should do so for the sake of the other case.
          (delete '(2) [(2) (1) (2)])
               => [(1)]

 -- Function: remove object sequence
     This function is the non-destructive counterpart of `delete'.  It
     returns a copy of `sequence', a list, vector, or string, with
     elements `equal' to `object' removed.  For example:

          (remove '(2) '((2) (1) (2)))
               => ((1))
          (remove '(2) [(2) (1) (2)])
               => [(1)]

     Common Lisp note: The functions `member', `delete' and `remove' in
     GNU Emacs Lisp are derived from Maclisp, not Common Lisp.  The
     Common Lisp versions do not use `equal' to compare elements.

 -- Function: member-ignore-case object list
     This function is like `member', except that OBJECT should be a
     string and that it ignores differences in letter-case and text
     representation: upper-case and lower-case letters are treated as
     equal, and unibyte strings are converted to multibyte prior to
     comparison.

 -- Function: delete-dups list
     This function destructively removes all `equal' duplicates from
     LIST, stores the result in LIST and returns it.  Of several
     `equal' occurrences of an element in LIST, `delete-dups' keeps the
     first one.

   See also the function `add-to-list', in *note List Variables::, for
a way to add an element to a list stored in a variable and used as a
set.

File: elisp,  Node: Association Lists,  Next: Rings,  Prev: Sets And Lists,  Up: Lists

5.8 Association Lists
=====================

An "association list", or "alist" for short, records a mapping from
keys to values.  It is a list of cons cells called "associations": the
CAR of each cons cell is the "key", and the CDR is the "associated
value".(1)

   Here is an example of an alist.  The key `pine' is associated with
the value `cones'; the key `oak' is associated with `acorns'; and the
key `maple' is associated with `seeds'.

     ((pine . cones)
      (oak . acorns)
      (maple . seeds))

   Both the values and the keys in an alist may be any Lisp objects.
For example, in the following alist, the symbol `a' is associated with
the number `1', and the string `"b"' is associated with the _list_ `(2
3)', which is the CDR of the alist element:

     ((a . 1) ("b" 2 3))

   Sometimes it is better to design an alist to store the associated
value in the CAR of the CDR of the element.  Here is an example of such
an alist:

     ((rose red) (lily white) (buttercup yellow))

Here we regard `red' as the value associated with `rose'.  One
advantage of this kind of alist is that you can store other related
information--even a list of other items--in the CDR of the CDR.  One
disadvantage is that you cannot use `rassq' (see below) to find the
element containing a given value.  When neither of these considerations
is important, the choice is a matter of taste, as long as you are
consistent about it for any given alist.

   The same alist shown above could be regarded as having the
associated value in the CDR of the element; the value associated with
`rose' would be the list `(red)'.

   Association lists are often used to record information that you might
otherwise keep on a stack, since new associations may be added easily to
the front of the list.  When searching an association list for an
association with a given key, the first one found is returned, if there
is more than one.

   In Emacs Lisp, it is _not_ an error if an element of an association
list is not a cons cell.  The alist search functions simply ignore such
elements.  Many other versions of Lisp signal errors in such cases.

   Note that property lists are similar to association lists in several
respects.  A property list behaves like an association list in which
each key can occur only once.  *Note Property Lists::, for a comparison
of property lists and association lists.

 -- Function: assoc key alist
     This function returns the first association for KEY in ALIST,
     comparing KEY against the alist elements using `equal' (*note
     Equality Predicates::).  It returns `nil' if no association in
     ALIST has a CAR `equal' to KEY.  For example:

          (setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
               => ((pine . cones) (oak . acorns) (maple . seeds))
          (assoc 'oak trees)
               => (oak . acorns)
          (cdr (assoc 'oak trees))
               => acorns
          (assoc 'birch trees)
               => nil

     Here is another example, in which the keys and values are not
     symbols:

          (setq needles-per-cluster
                '((2 "Austrian Pine" "Red Pine")
                  (3 "Pitch Pine")
                  (5 "White Pine")))

          (cdr (assoc 3 needles-per-cluster))
               => ("Pitch Pine")
          (cdr (assoc 2 needles-per-cluster))
               => ("Austrian Pine" "Red Pine")

   The function `assoc-string' is much like `assoc' except that it
ignores certain differences between strings.  *Note Text Comparison::.

 -- Function: rassoc value alist
     This function returns the first association with value VALUE in
     ALIST.  It returns `nil' if no association in ALIST has a CDR
     `equal' to VALUE.

     `rassoc' is like `assoc' except that it compares the CDR of each
     ALIST association instead of the CAR.  You can think of this as
     "reverse `assoc'," finding the key for a given value.

 -- Function: assq key alist
     This function is like `assoc' in that it returns the first
     association for KEY in ALIST, but it makes the comparison using
     `eq' instead of `equal'.  `assq' returns `nil' if no association
     in ALIST has a CAR `eq' to KEY.  This function is used more often
     than `assoc', since `eq' is faster than `equal' and most alists
     use symbols as keys.  *Note Equality Predicates::.

          (setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
               => ((pine . cones) (oak . acorns) (maple . seeds))
          (assq 'pine trees)
               => (pine . cones)

     On the other hand, `assq' is not usually useful in alists where the
     keys may not be symbols:

          (setq leaves
                '(("simple leaves" . oak)
                  ("compound leaves" . horsechestnut)))

          (assq "simple leaves" leaves)
               => nil
          (assoc "simple leaves" leaves)
               => ("simple leaves" . oak)

 -- Function: rassq value alist
     This function returns the first association with value VALUE in
     ALIST.  It returns `nil' if no association in ALIST has a CDR `eq'
     to VALUE.

     `rassq' is like `assq' except that it compares the CDR of each
     ALIST association instead of the CAR.  You can think of this as
     "reverse `assq'," finding the key for a given value.

     For example:

          (setq trees '((pine . cones) (oak . acorns) (maple . seeds)))

          (rassq 'acorns trees)
               => (oak . acorns)
          (rassq 'spores trees)
               => nil

     `rassq' cannot search for a value stored in the CAR of the CDR of
     an element:

          (setq colors '((rose red) (lily white) (buttercup yellow)))

          (rassq 'white colors)
               => nil

     In this case, the CDR of the association `(lily white)' is not the
     symbol `white', but rather the list `(white)'.  This becomes
     clearer if the association is written in dotted pair notation:

          (lily white) == (lily . (white))

 -- Function: assoc-default key alist &optional test default
     This function searches ALIST for a match for KEY.  For each
     element of ALIST, it compares the element (if it is an atom) or
     the element's CAR (if it is a cons) against KEY, by calling TEST
     with two arguments: the element or its CAR, and KEY.  The
     arguments are passed in that order so that you can get useful
     results using `string-match' with an alist that contains regular
     expressions (*note Regexp Search::).  If TEST is omitted or `nil',
     `equal' is used for comparison.

     If an alist element matches KEY by this criterion, then
     `assoc-default' returns a value based on this element.  If the
     element is a cons, then the value is the element's CDR.
     Otherwise, the return value is DEFAULT.

     If no alist element matches KEY, `assoc-default' returns `nil'.

 -- Function: copy-alist alist
     This function returns a two-level deep copy of ALIST: it creates a
     new copy of each association, so that you can alter the
     associations of the new alist without changing the old one.

          (setq needles-per-cluster
                '((2 . ("Austrian Pine" "Red Pine"))
                  (3 . ("Pitch Pine"))
                  (5 . ("White Pine"))))
          =>
          ((2 "Austrian Pine" "Red Pine")
           (3 "Pitch Pine")
           (5 "White Pine"))

          (setq copy (copy-alist needles-per-cluster))
          =>
          ((2 "Austrian Pine" "Red Pine")
           (3 "Pitch Pine")
           (5 "White Pine"))

          (eq needles-per-cluster copy)
               => nil
          (equal needles-per-cluster copy)
               => t
          (eq (car needles-per-cluster) (car copy))
               => nil
          (cdr (car (cdr needles-per-cluster)))
               => ("Pitch Pine")
          (eq (cdr (car (cdr needles-per-cluster)))
              (cdr (car (cdr copy))))
               => t

     This example shows how `copy-alist' makes it possible to change
     the associations of one copy without affecting the other:

          (setcdr (assq 3 copy) '("Martian Vacuum Pine"))
          (cdr (assq 3 needles-per-cluster))
               => ("Pitch Pine")

 -- Function: assq-delete-all key alist
     This function deletes from ALIST all the elements whose CAR is
     `eq' to KEY, much as if you used `delq' to delete each such
     element one by one.  It returns the shortened alist, and often
     modifies the original list structure of ALIST.  For correct
     results, use the return value of `assq-delete-all' rather than
     looking at the saved value of ALIST.

          (setq alist '((foo 1) (bar 2) (foo 3) (lose 4)))
               => ((foo 1) (bar 2) (foo 3) (lose 4))
          (assq-delete-all 'foo alist)
               => ((bar 2) (lose 4))
          alist
               => ((foo 1) (bar 2) (lose 4))

 -- Function: rassq-delete-all value alist
     This function deletes from ALIST all the elements whose CDR is
     `eq' to VALUE.  It returns the shortened alist, and often modifies
     the original list structure of ALIST.  `rassq-delete-all' is like
     `assq-delete-all' except that it compares the CDR of each ALIST
     association instead of the CAR.

   ---------- Footnotes ----------

   (1) This usage of "key" is not related to the term "key sequence";
it means a value used to look up an item in a table.  In this case, the
table is the alist, and the alist associations are the items.

File: elisp,  Node: Rings,  Prev: Association Lists,  Up: Lists

5.9 Managing a Fixed-Size Ring of Objects
=========================================

This section describes functions for operating on rings.  A "ring" is a
fixed-size data structure that supports insertion, deletion, rotation,
and modulo-indexed reference and traversal.

 -- Function: make-ring size
     This returns a new ring capable of holding SIZE objects.  SIZE
     should be an integer.

 -- Function: ring-p object
     This returns `t' if OBJECT is a ring, `nil' otherwise.

 -- Function: ring-size ring
     This returns the maximum capacity of the RING.

 -- Function: ring-length ring
     This returns the number of objects that RING currently contains.
     The value will never exceed that returned by `ring-size'.

 -- Function: ring-elements ring
     This returns a list of the objects in RING, in order, newest first.

 -- Function: ring-copy ring
     This returns a new ring which is a copy of RING.  The new ring
     contains the same (`eq') objects as RING.

 -- Function: ring-empty-p ring
     This returns `t' if RING is empty, `nil' otherwise.

   The newest element in the ring always has index 0.  Higher indices
correspond to older elements.  Indices are computed modulo the ring
length.  Index -1 corresponds to the oldest element, -2 to the
next-oldest, and so forth.

 -- Function: ring-ref ring index
     This returns the object in RING found at index INDEX.  INDEX may
     be negative or greater than the ring length.  If RING is empty,
     `ring-ref' signals an error.

 -- Function: ring-insert ring object
     This inserts OBJECT into RING, making it the newest element, and
     returns OBJECT.

     If the ring is full, insertion removes the oldest element to make
     room for the new element.

 -- Function: ring-remove ring &optional index
     Remove an object from RING, and return that object.  The argument
     INDEX specifies which item to remove; if it is `nil', that means
     to remove the oldest item.  If RING is empty, `ring-remove'
     signals an error.

 -- Function: ring-insert-at-beginning ring object
     This inserts OBJECT into RING, treating it as the oldest element.
     The return value is not significant.

     If the ring is full, this function removes the newest element to
     make room for the inserted element.

   If you are careful not to exceed the ring size, you can use the ring
as a first-in-first-out queue.  For example:

     (let ((fifo (make-ring 5)))
       (mapc (lambda (obj) (ring-insert fifo obj))
             '(0 one "two"))
       (list (ring-remove fifo) t
             (ring-remove fifo) t
             (ring-remove fifo)))
          => (0 t one t "two")

File: elisp,  Node: Sequences Arrays Vectors,  Next: Hash Tables,  Prev: Lists,  Up: Top

6 Sequences, Arrays, and Vectors
********************************

Recall that the "sequence" type is the union of two other Lisp types:
lists and arrays.  In other words, any list is a sequence, and any
array is a sequence.  The common property that all sequences have is
that each is an ordered collection of elements.

   An "array" is a fixed-length object with a slot for each of its
elements.  All the elements are accessible in constant time.  The four
types of arrays are strings, vectors, char-tables and bool-vectors.

   A list is a sequence of elements, but it is not a single primitive
object; it is made of cons cells, one cell per element.  Finding the
Nth element requires looking through N cons cells, so elements farther
from the beginning of the list take longer to access.  But it is
possible to add elements to the list, or remove elements.

   The following diagram shows the relationship between these types:

               _____________________________________________
              |                                             |
              |          Sequence                           |
              |  ______   ________________________________  |
              | |      | |                                | |
              | | List | |             Array              | |
              | |      | |    ________       ________     | |
              | |______| |   |        |     |        |    | |
              |          |   | Vector |     | String |    | |
              |          |   |________|     |________|    | |
              |          |  ____________   _____________  | |
              |          | |            | |             | | |
              |          | | Char-table | | Bool-vector | | |
              |          | |____________| |_____________| | |
              |          |________________________________| |
              |_____________________________________________|

* Menu:

* Sequence Functions::    Functions that accept any kind of sequence.
* Arrays::                Characteristics of arrays in Emacs Lisp.
* Array Functions::       Functions specifically for arrays.
* Vectors::               Special characteristics of Emacs Lisp vectors.
* Vector Functions::      Functions specifically for vectors.
* Char-Tables::           How to work with char-tables.
* Bool-Vectors::          How to work with bool-vectors.

File: elisp,  Node: Sequence Functions,  Next: Arrays,  Up: Sequences Arrays Vectors

6.1 Sequences
=============

In Emacs Lisp, a "sequence" is either a list or an array.  The common
property of all sequences is that they are ordered collections of
elements.  This section describes functions that accept any kind of
sequence.

 -- Function: sequencep object
     Returns `t' if OBJECT is a list, vector, string, bool-vector, or
     char-table, `nil' otherwise.

 -- Function: length sequence
     This function returns the number of elements in SEQUENCE.  If
     SEQUENCE is a dotted list, a `wrong-type-argument' error is
     signaled.  Circular lists may cause an infinite loop.  For a
     char-table, the value returned is always one more than the maximum
     Emacs character code.

     *Note Definition of safe-length::, for the related function
     `safe-length'.

          (length '(1 2 3))
              => 3
          (length ())
              => 0
          (length "foobar")
              => 6
          (length [1 2 3])
              => 3
          (length (make-bool-vector 5 nil))
              => 5

See also `string-bytes', in *note Text Representations::.

 -- Function: elt sequence index
     This function returns the element of SEQUENCE indexed by INDEX.
     Legitimate values of INDEX are integers ranging from 0 up to one
     less than the length of SEQUENCE.  If SEQUENCE is a list,
     out-of-range values behave as for `nth'.  *Note Definition of
     nth::.  Otherwise, out-of-range values trigger an
     `args-out-of-range' error.

          (elt [1 2 3 4] 2)
               => 3
          (elt '(1 2 3 4) 2)
               => 3
          ;; We use `string' to show clearly which character `elt' returns.
          (string (elt "1234" 2))
               => "3"
          (elt [1 2 3 4] 4)
               error--> Args out of range: [1 2 3 4], 4
          (elt [1 2 3 4] -1)
               error--> Args out of range: [1 2 3 4], -1

     This function generalizes `aref' (*note Array Functions::) and
     `nth' (*note Definition of nth::).

 -- Function: copy-sequence sequence
     Returns a copy of SEQUENCE.  The copy is the same type of object
     as the original sequence, and it has the same elements in the same
     order.

     Storing a new element into the copy does not affect the original
     SEQUENCE, and vice versa.  However, the elements of the new
     sequence are not copies; they are identical (`eq') to the elements
     of the original.  Therefore, changes made within these elements, as
     found via the copied sequence, are also visible in the original
     sequence.

     If the sequence is a string with text properties, the property
     list in the copy is itself a copy, not shared with the original's
     property list.  However, the actual values of the properties are
     shared.  *Note Text Properties::.

     This function does not work for dotted lists.  Trying to copy a
     circular list may cause an infinite loop.

     See also `append' in *note Building Lists::, `concat' in *note
     Creating Strings::, and `vconcat' in *note Vector Functions::, for
     other ways to copy sequences.

          (setq bar '(1 2))
               => (1 2)
          (setq x (vector 'foo bar))
               => [foo (1 2)]
          (setq y (copy-sequence x))
               => [foo (1 2)]

          (eq x y)
               => nil
          (equal x y)
               => t
          (eq (elt x 1) (elt y 1))
               => t

          ;; Replacing an element of one sequence.
          (aset x 0 'quux)
          x => [quux (1 2)]
          y => [foo (1 2)]

          ;; Modifying the inside of a shared element.
          (setcar (aref x 1) 69)
          x => [quux (69 2)]
          y => [foo (69 2)]

File: elisp,  Node: Arrays,  Next: Array Functions,  Prev: Sequence Functions,  Up: Sequences Arrays Vectors

6.2 Arrays
==========

An "array" object has slots that hold a number of other Lisp objects,
called the elements of the array.  Any element of an array may be
accessed in constant time.  In contrast, the time to access an element
of a list is proportional to the position of that element in the list.

   Emacs defines four types of array, all one-dimensional: "strings"
(*note String Type::), "vectors" (*note Vector Type::), "bool-vectors"
(*note Bool-Vector Type::), and "char-tables" (*note Char-Table
Type::).  Vectors and char-tables can hold elements of any type, but
strings can only hold characters, and bool-vectors can only hold `t'
and `nil'.

   All four kinds of array share these characteristics:

   * 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 length of the array is fixed once you create it; you cannot
     change the length of an existing array.

   * For purposes of evaluation, the array is a constant--in other
     words, it evaluates to itself.

   * The elements of an array may be referenced or changed with the
     functions `aref' and `aset', respectively (*note Array
     Functions::).

   When you create an array, other than a char-table, you must specify
its length.  You cannot specify the length of a char-table, because that
is determined by the range of character codes.

   In principle, if you want an array of text characters, you could use
either a string or a vector.  In practice, we always choose strings for
such applications, for four reasons:

   * They occupy one-fourth the space of a vector of the same elements.

   * Strings are printed in a way that shows the contents more clearly
     as text.

   * Strings can hold text properties.  *Note Text Properties::.

   * Many of the specialized editing and I/O facilities of Emacs accept
     only strings.  For example, you cannot insert a vector of
     characters into a buffer the way you can insert a string.  *Note
     Strings and Characters::.

   By contrast, for an array of keyboard input characters (such as a key
sequence), a vector may be necessary, because many keyboard input
characters are outside the range that will fit in a string.  *Note Key
Sequence Input::.

File: elisp,  Node: Array Functions,  Next: Vectors,  Prev: Arrays,  Up: Sequences Arrays Vectors

6.3 Functions that Operate on Arrays
====================================

In this section, we describe the functions that accept all types of
arrays.

 -- Function: arrayp object
     This function returns `t' if OBJECT is an array (i.e., a vector, a
     string, a bool-vector or a char-table).

          (arrayp [a])
               => t
          (arrayp "asdf")
               => t
          (arrayp (syntax-table))    ;; A char-table.
               => t

 -- Function: aref array index
     This function returns the INDEXth element of ARRAY.  The first
     element is at index zero.

          (setq primes [2 3 5 7 11 13])
               => [2 3 5 7 11 13]
          (aref primes 4)
               => 11
          (aref "abcdefg" 1)
               => 98           ; `b' is ASCII code 98.

     See also the function `elt', in *note Sequence Functions::.

 -- Function: aset array index object
     This function sets the INDEXth element of ARRAY to be OBJECT.  It
     returns OBJECT.

          (setq w [foo bar baz])
               => [foo bar baz]
          (aset w 0 'fu)
               => fu
          w
               => [fu bar baz]

          (setq x "asdfasfd")
               => "asdfasfd"
          (aset x 3 ?Z)
               => 90
          x
               => "asdZasfd"

     If ARRAY is a string and OBJECT is not a character, a
     `wrong-type-argument' error results.  The function converts a
     unibyte string to multibyte if necessary to insert a character.

 -- Function: fillarray array object
     This function fills the array ARRAY with OBJECT, so that each
     element of ARRAY is OBJECT.  It returns ARRAY.

          (setq a [a b c d e f g])
               => [a b c d e f g]
          (fillarray a 0)
               => [0 0 0 0 0 0 0]
          a
               => [0 0 0 0 0 0 0]
          (setq s "When in the course")
               => "When in the course"
          (fillarray s ?-)
               => "------------------"

     If ARRAY is a string and OBJECT is not a character, a
     `wrong-type-argument' error results.

   The general sequence functions `copy-sequence' and `length' are
often useful for objects known to be arrays.  *Note Sequence
Functions::.

File: elisp,  Node: Vectors,  Next: Vector Functions,  Prev: Array Functions,  Up: Sequences Arrays Vectors

6.4 Vectors
===========

A "vector" is a general-purpose array whose elements can be any Lisp
objects.  (By contrast, the elements of a string can only be
characters.  *Note Strings and Characters::.)  Vectors are used in
Emacs for many purposes: as key sequences (*note Key Sequences::), as
symbol-lookup tables (*note Creating Symbols::), as part of the
representation of a byte-compiled function (*note Byte Compilation::),
and more.

   In Emacs Lisp, the indices of the elements of a vector start from
zero and count up from there.

   Vectors are printed with square brackets surrounding the elements.
Thus, a vector whose elements are the symbols `a', `b' and `a' is
printed as `[a b a]'.  You can write vectors in the same way in Lisp
input.

   A vector, like a string or a number, is considered a constant for
evaluation: the result of evaluating it is the same vector.  This does
not evaluate or even examine the elements of the vector.  *Note
Self-Evaluating Forms::.

   Here are examples illustrating these principles:

     (setq avector [1 two '(three) "four" [five]])
          => [1 two (quote (three)) "four" [five]]
     (eval avector)
          => [1 two (quote (three)) "four" [five]]
     (eq avector (eval avector))
          => t

File: elisp,  Node: Vector Functions,  Next: Char-Tables,  Prev: Vectors,  Up: Sequences Arrays Vectors

6.5 Functions for Vectors
=========================

Here are some functions that relate to vectors:

 -- Function: vectorp object
     This function returns `t' if OBJECT is a vector.

          (vectorp [a])
               => t
          (vectorp "asdf")
               => nil

 -- Function: vector &rest objects
     This function creates and returns a vector whose elements are the
     arguments, OBJECTS.

          (vector 'foo 23 [bar baz] "rats")
               => [foo 23 [bar baz] "rats"]
          (vector)
               => []

 -- Function: make-vector length object
     This function returns a new vector consisting of LENGTH elements,
     each initialized to OBJECT.

          (setq sleepy (make-vector 9 'Z))
               => [Z Z Z Z Z Z Z Z Z]

 -- Function: vconcat &rest sequences
     This function returns a new vector containing all the elements of
     SEQUENCES.  The arguments SEQUENCES may be true lists, vectors,
     strings or bool-vectors.  If no SEQUENCES are given, an empty
     vector is returned.

     The value is a newly constructed vector that is not `eq' to any
     existing vector.

          (setq a (vconcat '(A B C) '(D E F)))
               => [A B C D E F]
          (eq a (vconcat a))
               => nil
          (vconcat)
               => []
          (vconcat [A B C] "aa" '(foo (6 7)))
               => [A B C 97 97 foo (6 7)]

     The `vconcat' function also allows byte-code function objects as
     arguments.  This is a special feature to make it easy to access
     the entire contents of a byte-code function object.  *Note
     Byte-Code Objects::.

     For other concatenation functions, see `mapconcat' in *note
     Mapping Functions::, `concat' in *note Creating Strings::, and
     `append' in *note Building Lists::.

   The `append' function also provides a way to convert a vector into a
list with the same elements:

     (setq avector [1 two (quote (three)) "four" [five]])
          => [1 two (quote (three)) "four" [five]]
     (append avector nil)
          => (1 two (quote (three)) "four" [five])

File: elisp,  Node: Char-Tables,  Next: Bool-Vectors,  Prev: Vector Functions,  Up: Sequences Arrays Vectors

6.6 Char-Tables
===============

A char-table is much like a vector, except that it is indexed by
character codes.  Any valid character code, without modifiers, can be
used as an index in a char-table.  You can access a char-table's
elements with `aref' and `aset', as with any array.  In addition, a
char-table can have "extra slots" to hold additional data not
associated with particular character codes.  Like vectors, char-tables
are constants when evaluated, and can hold elements of any type.

   Each char-table has a "subtype", a symbol, which serves two purposes:

   * The subtype provides an easy way to tell what the char-table is
     for.  For instance, display tables are char-tables with
     `display-table' as the subtype, and syntax tables are char-tables
     with `syntax-table' as the subtype.  The subtype can be queried
     using the function `char-table-subtype', described below.

   * The subtype controls the number of "extra slots" in the
     char-table.  This number is specified by the subtype's
     `char-table-extra-slots' symbol property, which should be an
     integer between 0 and 10.  If the subtype has no such symbol
     property, the char-table has no extra slots.  *Note Property
     Lists::, for information about symbol properties.

   A char-table can have a "parent", which is another char-table.  If
it does, then whenever the char-table specifies `nil' for a particular
character C, it inherits the value specified in the parent.  In other
words, `(aref CHAR-TABLE C)' returns the value from the parent of
CHAR-TABLE if CHAR-TABLE itself specifies `nil'.

   A char-table can also have a "default value".  If so, then `(aref
CHAR-TABLE C)' returns the default value whenever the char-table does
not specify any other non-`nil' value.

 -- Function: make-char-table subtype &optional init
     Return a newly-created char-table, with subtype SUBTYPE (a
     symbol).  Each element is initialized to INIT, which defaults to
     `nil'.  You cannot alter the subtype of a char-table after the
     char-table is created.

     There is no argument to specify the length of the char-table,
     because all char-tables have room for any valid character code as
     an index.

     If SUBTYPE has the `char-table-extra-slots' symbol property, that
     specifies the number of extra slots in the char-table.  This
     should be an integer between 0 and 10; otherwise,
     `make-char-table' raises an error.  If SUBTYPE has no
     `char-table-extra-slots' symbol property (*note Property Lists::),
     the char-table has no extra slots.

 -- Function: char-table-p object
     This function returns `t' if OBJECT is a char-table, and `nil'
     otherwise.

 -- Function: char-table-subtype char-table
     This function returns the subtype symbol of CHAR-TABLE.

   There is no special function to access default values in a
char-table.  To do that, use `char-table-range' (see below).

 -- Function: char-table-parent char-table
     This function returns the parent of CHAR-TABLE.  The parent is
     always either `nil' or another char-table.

 -- Function: set-char-table-parent char-table new-parent
     This function sets the parent of CHAR-TABLE to NEW-PARENT.

 -- Function: char-table-extra-slot char-table n
     This function returns the contents of extra slot N of CHAR-TABLE.
     The number of extra slots in a char-table is determined by its
     subtype.

 -- Function: set-char-table-extra-slot char-table n value
     This function stores VALUE in extra slot N of CHAR-TABLE.

   A char-table can specify an element value for a single character
code; it can also specify a value for an entire character set.

 -- Function: char-table-range char-table range
     This returns the value specified in CHAR-TABLE for a range of
     characters RANGE.  Here are the possibilities for RANGE:

    `nil'
          Refers to the default value.

    CHAR
          Refers to the element for character CHAR (supposing CHAR is a
          valid character code).

    `(FROM . TO)'
          A cons cell refers to all the characters in the inclusive
          range `[FROM..TO]'.

 -- Function: set-char-table-range char-table range value
     This function sets the value in CHAR-TABLE for a range of
     characters RANGE.  Here are the possibilities for RANGE:

    `nil'
          Refers to the default value.

    `t'
          Refers to the whole range of character codes.

    CHAR
          Refers to the element for character CHAR (supposing CHAR is a
          valid character code).

    `(FROM . TO)'
          A cons cell refers to all the characters in the inclusive
          range `[FROM..TO]'.

 -- Function: map-char-table function char-table
     This function calls its argument FUNCTION for each element of
     CHAR-TABLE that has a non-`nil' value.  The call to FUNCTION is
     with two arguments, a key and a value.  The key is a possible
     RANGE argument for `char-table-range'--either a valid character or
     a cons cell `(FROM . TO)', specifying a range of characters that
     share the same value.  The value is what `(char-table-range
     CHAR-TABLE KEY)' returns.

     Overall, the key-value pairs passed to FUNCTION describe all the
     values stored in CHAR-TABLE.

     The return value is always `nil'; to make calls to
     `map-char-table' useful, FUNCTION should have side effects.  For
     example, here is how to examine the elements of the syntax table:

          (let (accumulator)
             (map-char-table
              #'(lambda (key value)
          	(setq accumulator
          	      (cons (list
          		     (if (consp key)
          			 (list (car key) (cdr key))
          		       key)
          		     value)
          		    accumulator)))
              (syntax-table))
             accumulator)
          =>
          (((2597602 4194303) (2)) ((2597523 2597601) (3))
           ... (65379 (5 . 65378)) (65378 (4 . 65379)) (65377 (1))
           ... (12 (0)) (11 (3)) (10 (12)) (9 (0)) ((0 8) (3)))

File: elisp,  Node: Bool-Vectors,  Prev: Char-Tables,  Up: Sequences Arrays Vectors

6.7 Bool-vectors
================

A bool-vector is much like a vector, except that it stores only the
values `t' and `nil'.  If you try to store any non-`nil' value into an
element of the bool-vector, the effect is to store `t' there.  As with
all arrays, bool-vector indices start from 0, and the length cannot be
changed once the bool-vector is created.  Bool-vectors are constants
when evaluated.

   There are two special functions for working with bool-vectors; aside
from that, you manipulate them with same functions used for other kinds
of arrays.

 -- Function: make-bool-vector length initial
     Return a new bool-vector of LENGTH elements, each one initialized
     to INITIAL.

 -- Function: bool-vector-p object
     This returns `t' if OBJECT is a bool-vector, and `nil' otherwise.

   Here is an example of creating, examining, and updating a
bool-vector.  Note that the printed form represents up to 8 boolean
values as a single character.

     (setq bv (make-bool-vector 5 t))
          => #&5"^_"
     (aref bv 1)
          => t
     (aset bv 3 nil)
          => nil
     bv
          => #&5"^W"

These results make sense because the binary codes for control-_ and
control-W are 11111 and 10111, respectively.

File: elisp,  Node: Hash Tables,  Next: Symbols,  Prev: Sequences Arrays Vectors,  Up: Top

7 Hash Tables
*************

A hash table is a very fast kind of lookup table, somewhat like an
alist (*note Association Lists::) in that it maps keys to corresponding
values.  It differs from an alist in these ways:

   * Lookup in a hash table is extremely fast for large tables--in
     fact, the time required is essentially _independent_ of how many
     elements are stored in the table.  For smaller tables (a few tens
     of elements) alists may still be faster because hash tables have a
     more-or-less constant overhead.

   * The correspondences in a hash table are in no particular order.

   * There is no way to share structure between two hash tables, the
     way two alists can share a common tail.

   Emacs Lisp provides a general-purpose hash table data type, along
with a series of functions for operating on them.  Hash tables have no
read syntax, and print in hash notation, like this:

     (make-hash-table)
          => #<hash-table 'eql nil 0/65 0x83af980>

(The term "hash notation" refers to the initial `#' character--*note
Printed Representation::--and has nothing to do with the term "hash
table.")

   Obarrays are also a kind of hash table, but they are a different type
of object and are used only for recording interned symbols (*note
Creating Symbols::).

* Menu:

* Creating Hash::       Functions to create hash tables.
* Hash Access::         Reading and writing the hash table contents.
* Defining Hash::       Defining new comparison methods.
* Other Hash::          Miscellaneous.

File: elisp,  Node: Creating Hash,  Next: Hash Access,  Up: Hash Tables

7.1 Creating Hash Tables
========================

The principal function for creating a hash table is `make-hash-table'.

 -- Function: make-hash-table &rest keyword-args
     This function creates a new hash table according to the specified
     arguments.  The arguments should consist of alternating keywords
     (particular symbols recognized specially) and values corresponding
     to them.

     Several keywords make sense in `make-hash-table', but the only two
     that you really need to know about are `:test' and `:weakness'.

    `:test TEST'
          This specifies the method of key lookup for this hash table.
          The default is `eql'; `eq' and `equal' are other alternatives:

         `eql'
               Keys which are numbers are "the same" if they are
               `equal', that is, if they are equal in value and either
               both are integers or both are floating point numbers;
               otherwise, two distinct objects are never "the same."

         `eq'
               Any two distinct Lisp objects are "different" as keys.

         `equal'
               Two Lisp objects are "the same," as keys, if they are
               equal according to `equal'.

          You can use `define-hash-table-test' (*note Defining Hash::)
          to define additional possibilities for TEST.

    `:weakness WEAK'
          The weakness of a hash table specifies whether the presence
          of a key or value in the hash table preserves it from garbage
          collection.

          The value, WEAK, must be one of `nil', `key', `value',
          `key-or-value', `key-and-value', or `t' which is an alias for
          `key-and-value'.  If WEAK is `key' then the hash table does
          not prevent its keys from being collected as garbage (if they
          are not referenced anywhere else); if a particular key does
          get collected, the corresponding association is removed from
          the hash table.

          If WEAK is `value', then the hash table does not prevent
          values from being collected as garbage (if they are not
          referenced anywhere else); if a particular value does get
          collected, the corresponding association is removed from the
          hash table.

          If WEAK is `key-and-value' or `t', both the key and the value
          must be live in order to preserve the association.  Thus, the
          hash table does not protect either keys or values from garbage
          collection; if either one is collected as garbage, that
          removes the association.

          If WEAK is `key-or-value', either the key or the value can
          preserve the association.  Thus, associations are removed
          from the hash table when both their key and value would be
          collected as garbage (if not for references from weak hash
          tables).

          The default for WEAK is `nil', so that all keys and values
          referenced in the hash table are preserved from garbage
          collection.

    `:size SIZE'
          This specifies a hint for how many associations you plan to
          store in the hash table.  If you know the approximate number,
          you can make things a little more efficient by specifying it
          this way.  If you specify too small a size, the hash table
          will grow automatically when necessary, but doing that takes
          some extra time.

          The default size is 65.

    `:rehash-size REHASH-SIZE'
          When you add an association to a hash table and the table is
          "full," it grows automatically.  This value specifies how to
          make the hash table larger, at that time.

          If REHASH-SIZE is an integer, it should be positive, and the
          hash table grows by adding that much to the nominal size.  If
          REHASH-SIZE is a floating point number, it had better be
          greater than 1, and the hash table grows by multiplying the
          old size by that number.

          The default value is 1.5.

    `:rehash-threshold THRESHOLD'
          This specifies the criterion for when the hash table is
          "full" (so it should be made larger).  The value, THRESHOLD,
          should be a positive floating point number, no greater than
          1.  The hash table is "full" whenever the actual number of
          entries exceeds this fraction of the nominal size.  The
          default for THRESHOLD is 0.8.

 -- Function: makehash &optional test
     This is equivalent to `make-hash-table', but with a different style
     argument list.  The argument TEST specifies the method of key
     lookup.

     This function is obsolete. Use `make-hash-table' instead.

File: elisp,  Node: Hash Access,  Next: Defining Hash,  Prev: Creating Hash,  Up: Hash Tables

7.2 Hash Table Access
=====================

This section describes the functions for accessing and storing
associations in a hash table.  In general, any Lisp object can be used
as a hash key, unless the comparison method imposes limits.  Any Lisp
object can also be used as the value.

 -- Function: gethash key table &optional default
     This function looks up KEY in TABLE, and returns its associated
     VALUE--or DEFAULT, if KEY has no association in TABLE.

 -- Function: puthash key value table
     This function enters an association for KEY in TABLE, with value
     VALUE.  If KEY already has an association in TABLE, VALUE replaces
     the old associated value.

 -- Function: remhash key table
     This function removes the association for KEY from TABLE, if there
     is one.  If KEY has no association, `remhash' does nothing.

     Common Lisp note: In Common Lisp, `remhash' returns non-`nil' if
     it actually removed an association and `nil' otherwise.  In Emacs
     Lisp, `remhash' always returns `nil'.

 -- Function: clrhash table
     This function removes all the associations from hash table TABLE,
     so that it becomes empty.  This is also called "clearing" the hash
     table.

     Common Lisp note: In Common Lisp, `clrhash' returns the empty
     TABLE.  In Emacs Lisp, it returns `nil'.

 -- Function: maphash function table
     This function calls FUNCTION once for each of the associations in
     TABLE.  The function FUNCTION should accept two arguments--a KEY
     listed in TABLE, and its associated VALUE.  `maphash' returns
     `nil'.

File: elisp,  Node: Defining Hash,  Next: Other Hash,  Prev: Hash Access,  Up: Hash Tables

7.3 Defining Hash Comparisons
=============================

You can define new methods of key lookup by means of
`define-hash-table-test'.  In order to use this feature, you need to
understand how hash tables work, and what a "hash code" means.

   You can think of a hash table conceptually as a large array of many
slots, each capable of holding one association.  To look up a key,
`gethash' first computes an integer, the hash code, from the key.  It
reduces this integer modulo the length of the array, to produce an
index in the array.  Then it looks in that slot, and if necessary in
other nearby slots, to see if it has found the key being sought.

   Thus, to define a new method of key lookup, you need to specify both
a function to compute the hash code from a key, and a function to
compare two keys directly.

 -- Function: define-hash-table-test name test-fn hash-fn
     This function defines a new hash table test, named NAME.

     After defining NAME in this way, you can use it as the TEST
     argument in `make-hash-table'.  When you do that, the hash table
     will use TEST-FN to compare key values, and HASH-FN to compute a
     "hash code" from a key value.

     The function TEST-FN should accept two arguments, two keys, and
     return non-`nil' if they are considered "the same."

     The function HASH-FN should accept one argument, a key, and return
     an integer that is the "hash code" of that key.  For good results,
     the function should use the whole range of integer values for hash
     codes, including negative integers.

     The specified functions are stored in the property list of NAME
     under the property `hash-table-test'; the property value's form is
     `(TEST-FN HASH-FN)'.

 -- Function: sxhash obj
     This function returns a hash code for Lisp object OBJ.  This is an
     integer which reflects the contents of OBJ and the other Lisp
     objects it points to.

     If two objects OBJ1 and OBJ2 are equal, then `(sxhash OBJ1)' and
     `(sxhash OBJ2)' are the same integer.

     If the two objects are not equal, the values returned by `sxhash'
     are usually different, but not always; once in a rare while, by
     luck, you will encounter two distinct-looking objects that give
     the same result from `sxhash'.

   This example creates a hash table whose keys are strings that are
compared case-insensitively.

     (defun case-fold-string= (a b)
       (compare-strings a nil nil b nil nil t))
     (defun case-fold-string-hash (a)
       (sxhash (upcase a)))

     (define-hash-table-test 'case-fold
       'case-fold-string= 'case-fold-string-hash)

     (make-hash-table :test 'case-fold)

   Here is how you could define a hash table test equivalent to the
predefined test value `equal'.  The keys can be any Lisp object, and
equal-looking objects are considered the same key.

     (define-hash-table-test 'contents-hash 'equal 'sxhash)

     (make-hash-table :test 'contents-hash)

File: elisp,  Node: Other Hash,  Prev: Defining Hash,  Up: Hash Tables

7.4 Other Hash Table Functions
==============================

Here are some other functions for working with hash tables.

 -- Function: hash-table-p table
     This returns non-`nil' if TABLE is a hash table object.

 -- Function: copy-hash-table table
     This function creates and returns a copy of TABLE.  Only the table
     itself is copied--the keys and values are shared.

 -- Function: hash-table-count table
     This function returns the actual number of entries in TABLE.

 -- Function: hash-table-test table
     This returns the TEST value that was given when TABLE was created,
     to specify how to hash and compare keys.  See `make-hash-table'
     (*note Creating Hash::).

 -- Function: hash-table-weakness table
     This function returns the WEAK value that was specified for hash
     table TABLE.

 -- Function: hash-table-rehash-size table
     This returns the rehash size of TABLE.

 -- Function: hash-table-rehash-threshold table
     This returns the rehash threshold of TABLE.

 -- Function: hash-table-size table
     This returns the current nominal size of TABLE.

File: elisp,  Node: Symbols,  Next: Evaluation,  Prev: Hash Tables,  Up: Top

8 Symbols
*********

A "symbol" is an object with a unique name.  This chapter describes
symbols, their components, their property lists, and how they are
created and interned.  Separate chapters describe the use of symbols as
variables and as function names; see *note Variables::, and *note
Functions::.  For the precise read syntax for symbols, see *note Symbol
Type::.

   You can test whether an arbitrary Lisp object is a symbol with
`symbolp':

 -- Function: symbolp object
     This function returns `t' if OBJECT is a symbol, `nil' otherwise.

* Menu:

* 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.
* Property Lists::           Each symbol has a property list
                               for recording miscellaneous information.

File: elisp,  Node: Symbol Components,  Next: Definitions,  Prev: Symbols,  Up: Symbols

8.1 Symbol Components
=====================

Each symbol has four components (or "cells"), each of which references
another object:

Print name
     The "print name cell" holds a string that names the symbol for
     reading and printing.  See `symbol-name' in *note Creating
     Symbols::.

Value
     The "value cell" holds the current value of the symbol as a
     variable.  When a symbol is used as a form, the value of the form
     is the contents of the symbol's value cell.  See `symbol-value' in
     *note Accessing Variables::.

Function
     The "function cell" holds the function definition of the symbol.
     When a symbol is used as a function, its function definition is
     used in its place.  This cell is also used to make a symbol stand
     for a keymap or a keyboard macro, for editor command execution.
     Because each symbol has separate value and function cells,
     variables names and function names do not conflict.  See
     `symbol-function' in *note Function Cells::.

Property list
     The "property list cell" holds the property list of the symbol.
     See `symbol-plist' in *note Property Lists::.

   The print name cell always holds a string, and cannot be changed.
The other three cells can be set individually to any specified Lisp
object.

   The print name cell holds the string that is the name of the symbol.
Since symbols are represented textually by their names, it is important
not to have two symbols with the same name.  The Lisp reader ensures
this: every time it reads a symbol, it looks for an existing symbol with
the specified name before it creates a new one.  (In GNU Emacs Lisp,
this lookup uses a hashing algorithm and an obarray; see *note Creating
Symbols::.)

   The value cell holds the symbol's value as a variable (*note
Variables::).  That is what you get if you evaluate the symbol as a
Lisp expression (*note Evaluation::).  Any Lisp object is a legitimate
value.  Certain symbols have values that cannot be changed; these
include `nil' and `t', and any symbol whose name starts with `:' (those
are called "keywords").  *Note Constant Variables::.

   We often refer to "the function `foo'" when we really mean the
function stored in the function cell of the symbol `foo'.  We make the
distinction explicit only when necessary.  In normal usage, the
function cell usually contains a function (*note Functions::) or a
macro (*note Macros::), as that is what the Lisp interpreter expects to
see there (*note Evaluation::).  Keyboard macros (*note Keyboard
Macros::), keymaps (*note Keymaps::) and autoload objects (*note
Autoloading::) are also sometimes stored in the function cells of
symbols.

   The property list cell normally should hold a correctly formatted
property list (*note Property Lists::), as a number of functions expect
to see a property list there.

   The function cell or the value cell may be "void", which means that
the cell does not reference any object.  (This is not the same thing as
holding the symbol `void', nor the same as holding the symbol `nil'.)
Examining a function or value cell that is void results in an error,
such as `Symbol's value as variable is void'.

   The four functions `symbol-name', `symbol-value', `symbol-plist',
and `symbol-function' return the contents of the four cells of a
symbol.  Here as an example we show the contents of the four cells of
the symbol `buffer-file-name':

     (symbol-name 'buffer-file-name)
          => "buffer-file-name"
     (symbol-value 'buffer-file-name)
          => "/gnu/elisp/symbols.texi"
     (symbol-function 'buffer-file-name)
          => #<subr buffer-file-name>
     (symbol-plist 'buffer-file-name)
          => (variable-documentation 29529)

Because this symbol is the variable which holds the name of the file
being visited in the current buffer, the value cell contents we see are
the name of the source file of this chapter of the Emacs Lisp Manual.
The property list cell contains the list `(variable-documentation
29529)' which tells the documentation functions where to find the
documentation string for the variable `buffer-file-name' in the
`DOC-VERSION' file.  (29529 is the offset from the beginning of the
`DOC-VERSION' file to where that documentation string begins--see *note
Documentation Basics::.)  The function cell contains the function for
returning the name of the file.  `buffer-file-name' names a primitive
function, which has no read syntax and prints in hash notation (*note
Primitive Function Type::).  A symbol naming a function written in Lisp
would have a lambda expression (or a byte-code object) in this cell.

File: elisp,  Node: Definitions,  Next: Creating Symbols,  Prev: Symbol Components,  Up: Symbols

8.2 Defining Symbols
====================

A "definition" in Lisp is a special form that announces your intention
to use a certain symbol in a particular way.  In Emacs Lisp, you can
define a symbol as a variable, or define it as a function (or macro),
or both independently.

   A definition construct typically specifies a value or meaning for the
symbol for one kind of use, plus documentation for its meaning when used
in this way.  Thus, when you define a symbol as a variable, you can
supply an initial value for the variable, plus documentation for the
variable.

   `defvar' and `defconst' are special forms that define a symbol as a
global variable.  They are documented in detail in *note Defining
Variables::.  For defining user option variables that can be
customized, use `defcustom' (*note Customization::).

   `defun' defines a symbol as a function, creating a lambda expression
and storing it in the function cell of the symbol.  This lambda
expression thus becomes the function definition of the symbol.  (The
term "function definition," meaning the contents of the function cell,
is derived from the idea that `defun' gives the symbol its definition
as a function.)  `defsubst' and `defalias' are two other ways of
defining a function.  *Note Functions::.

   `defmacro' defines a symbol as a macro.  It creates a macro object
and stores it in the function cell of the symbol.  Note that a given
symbol can be a macro or a function, but not both at once, because both
macro and function definitions are kept in the function cell, and that
cell can hold only one Lisp object at any given time.  *Note Macros::.

   In Emacs Lisp, a definition is not required in order to use a symbol
as a variable or function.  Thus, you can make a symbol a global
variable with `setq', whether you define it first or not.  The real
purpose of definitions is to guide programmers and programming tools.
They inform programmers who read the code that certain symbols are
_intended_ to be used as variables, or as functions.  In addition,
utilities such as `etags' and `make-docfile' recognize definitions, and
add appropriate information to tag tables and the `DOC-VERSION' file.
*Note Accessing Documentation::.

File: elisp,  Node: Creating Symbols,  Next: Property Lists,  Prev: Definitions,  Up: Symbols

8.3 Creating and Interning Symbols
==================================

To understand how symbols are created in GNU Emacs Lisp, you must know
how Lisp reads them.  Lisp must ensure that it finds the same symbol
every time it reads the same set of characters.  Failure to do so would
cause complete confusion.

   When the Lisp reader encounters a symbol, it reads all the characters
of the name.  Then it "hashes" those characters to find an index in a
table called an "obarray".  Hashing is an efficient method of looking
something up.  For example, instead of searching a telephone book cover
to cover when looking up Jan Jones, you start with the J's and go from
there.  That is a simple version of hashing.  Each element of the
obarray is a "bucket" which holds all the symbols with a given hash
code; to look for a given name, it is sufficient to look through all
the symbols in the bucket for that name's hash code.  (The same idea is
used for general Emacs hash tables, but they are a different data type;
see *note Hash Tables::.)

   If a symbol with the desired name is found, the reader uses that
symbol.  If the obarray does not contain a symbol with that name, the
reader makes a new symbol and adds it to the obarray.  Finding or adding
a symbol with a certain name is called "interning" it, and the symbol
is then called an "interned symbol".

   Interning ensures that each obarray has just one symbol with any
particular name.  Other like-named symbols may exist, but not in the
same obarray.  Thus, the reader gets the same symbols for the same
names, as long as you keep reading with the same obarray.

   Interning usually happens automatically in the reader, but sometimes
other programs need to do it.  For example, after the `M-x' command
obtains the command name as a string using the minibuffer, it then
interns the string, to get the interned symbol with that name.

   No obarray contains all symbols; in fact, some symbols are not in any
obarray.  They are called "uninterned symbols".  An uninterned symbol
has the same four cells as other symbols; however, the only way to gain
access to it is by finding it in some other object or as the value of a
variable.

   Creating an uninterned symbol is useful in generating Lisp code,
because an uninterned symbol used as a variable in the code you generate
cannot clash with any variables used in other Lisp programs.

   In Emacs Lisp, an obarray is actually a vector.  Each element of the
vector is a bucket; its value is either an interned symbol whose name
hashes to that bucket, or 0 if the bucket is empty.  Each interned
symbol has an internal link (invisible to the user) to the next symbol
in the bucket.  Because these links are invisible, there is no way to
find all the symbols in an obarray except using `mapatoms' (below).
The order of symbols in a bucket is not significant.

   In an empty obarray, every element is 0, so you can create an obarray
with `(make-vector LENGTH 0)'.  *This is the only valid way to create
an obarray.*  Prime numbers as lengths tend to result in good hashing;
lengths one less than a power of two are also good.

   *Do not try to put symbols in an obarray yourself.*  This does not
work--only `intern' can enter a symbol in an obarray properly.

     Common Lisp note: In Common Lisp, a single symbol may be interned
     in several obarrays.

   Most of the functions below take a name and sometimes an obarray as
arguments.  A `wrong-type-argument' error is signaled if the name is
not a string, or if the obarray is not a vector.

 -- Function: symbol-name symbol
     This function returns the string that is SYMBOL's name.  For
     example:

          (symbol-name 'foo)
               => "foo"

     *Warning:* Changing the string by substituting characters does
     change the name of the symbol, but fails to update the obarray, so
     don't do it!

 -- Function: make-symbol name
     This function returns a newly-allocated, uninterned symbol whose
     name is NAME (which must be a string).  Its value and function
     definition are void, and its property list is `nil'.  In the
     example below, the value of `sym' is not `eq' to `foo' because it
     is a distinct uninterned symbol whose name is also `foo'.

          (setq sym (make-symbol "foo"))
               => foo
          (eq sym 'foo)
               => nil

 -- Function: intern name &optional obarray
     This function returns the interned symbol whose name is NAME.  If
     there is no such symbol in the obarray OBARRAY, `intern' creates a
     new one, adds it to the obarray, and returns it.  If OBARRAY is
     omitted, the value of the global variable `obarray' is used.

          (setq sym (intern "foo"))
               => foo
          (eq sym 'foo)
               => t

          (setq sym1 (intern "foo" other-obarray))
               => foo
          (eq sym1 'foo)
               => nil

     Common Lisp note: In Common Lisp, you can intern an existing symbol
     in an obarray.  In Emacs Lisp, you cannot do this, because the
     argument to `intern' must be a string, not a symbol.

 -- Function: intern-soft name &optional obarray
     This function returns the symbol in OBARRAY whose name is NAME, or
     `nil' if OBARRAY has no symbol with that name.  Therefore, you can
     use `intern-soft' to test whether a symbol with a given name is
     already interned.  If OBARRAY is omitted, the value of the global
     variable `obarray' is used.

     The argument NAME may also be a symbol; in that case, the function
     returns NAME if NAME is interned in the specified obarray, and
     otherwise `nil'.

          (intern-soft "frazzle")        ; No such symbol exists.
               => nil
          (make-symbol "frazzle")        ; Create an uninterned one.
               => frazzle
          (intern-soft "frazzle")        ; That one cannot be found.
               => nil
          (setq sym (intern "frazzle"))  ; Create an interned one.
               => frazzle
          (intern-soft "frazzle")        ; That one can be found!
               => frazzle
          (eq sym 'frazzle)              ; And it is the same one.
               => t

 -- Variable: obarray
     This variable is the standard obarray for use by `intern' and
     `read'.

 -- Function: mapatoms function &optional obarray
     This function calls FUNCTION once with each symbol in the obarray
     OBARRAY.  Then it returns `nil'.  If OBARRAY is omitted, it
     defaults to the value of `obarray', the standard obarray for
     ordinary symbols.

          (setq count 0)
               => 0
          (defun count-syms (s)
            (setq count (1+ count)))
               => count-syms
          (mapatoms 'count-syms)
               => nil
          count
               => 1871

     See `documentation' in *note Accessing Documentation::, for another
     example using `mapatoms'.

 -- Function: unintern symbol &optional obarray
     This function deletes SYMBOL from the obarray OBARRAY.  If
     `symbol' is not actually in the obarray, `unintern' does nothing.
     If OBARRAY is `nil', the current obarray is used.

     If you provide a string instead of a symbol as SYMBOL, it stands
     for a symbol name.  Then `unintern' deletes the symbol (if any) in
     the obarray which has that name.  If there is no such symbol,
     `unintern' does nothing.

     If `unintern' does delete a symbol, it returns `t'.  Otherwise it
     returns `nil'.

File: elisp,  Node: Property Lists,  Prev: Creating Symbols,  Up: Symbols

8.4 Property Lists
==================

A "property list" ("plist" for short) is a list of paired elements.
Each of the pairs associates a property name (usually a symbol) with a
property or value.

   Every symbol has a cell that stores a property list (*note Symbol
Components::).  This property list is used to record information about
the symbol, such as its variable documentation and the name of the file
where it was defined.

   Property lists can also be used in other contexts.  For instance,
you can assign property lists to character positions in a string or
buffer.  *Note Text Properties::.

   The property names and values in a property list can be any Lisp
objects, but the names are usually symbols.  Property list functions
compare the property names using `eq'.  Here is an example of a
property list, found on the symbol `progn' when the compiler is loaded:

     (lisp-indent-function 0 byte-compile byte-compile-progn)

Here `lisp-indent-function' and `byte-compile' are property names, and
the other two elements are the corresponding values.

* Menu:

* Plists and Alists::           Comparison of the advantages of property
                                  lists and association lists.
* Symbol Plists::               Functions to access symbols' property lists.
* Other Plists::                Accessing property lists stored elsewhere.

File: elisp,  Node: Plists and Alists,  Next: Symbol Plists,  Up: Property Lists

8.4.1 Property Lists and Association Lists
------------------------------------------

Association lists (*note Association Lists::) are very similar to
property lists.  In contrast to association lists, the order of the
pairs in the property list is not significant since the property names
must be distinct.

   Property lists are better than association lists for attaching
information to various Lisp function names or variables.  If your
program keeps all of its associations in one association list, it will
typically need to search that entire list each time it checks for an
association.  This could be slow.  By contrast, if you keep the same
information in the property lists of the function names or variables
themselves, each search will scan only the length of one property list,
which is usually short.  This is why the documentation for a variable is
recorded in a property named `variable-documentation'.  The byte
compiler likewise uses properties to record those functions needing
special treatment.

   However, association lists have their own advantages.  Depending on
your application, it may be faster to add an association to the front of
an association list than to update a property.  All properties for a
symbol are stored in the same property list, so there is a possibility
of a conflict between different uses of a property name.  (For this
reason, it is a good idea to choose property names that are probably
unique, such as by beginning the property name with the program's usual
name-prefix for variables and functions.)  An association list may be
used like a stack where associations are pushed on the front of the list
and later discarded; this is not possible with a property list.

File: elisp,  Node: Symbol Plists,  Next: Other Plists,  Prev: Plists and Alists,  Up: Property Lists

8.4.2 Property List Functions for Symbols
-----------------------------------------

 -- Function: symbol-plist symbol
     This function returns the property list of SYMBOL.

 -- Function: setplist symbol plist
     This function sets SYMBOL's property list to PLIST.  Normally,
     PLIST should be a well-formed property list, but this is not
     enforced.  The return value is PLIST.

          (setplist 'foo '(a 1 b (2 3) c nil))
               => (a 1 b (2 3) c nil)
          (symbol-plist 'foo)
               => (a 1 b (2 3) c nil)

     For symbols in special obarrays, which are not used for ordinary
     purposes, it may make sense to use the property list cell in a
     nonstandard fashion; in fact, the abbrev mechanism does so (*note
     Abbrevs::).

 -- Function: get symbol property
     This function finds the value of the property named PROPERTY in
     SYMBOL's property list.  If there is no such property, `nil' is
     returned.  Thus, there is no distinction between a value of `nil'
     and the absence of the property.

     The name PROPERTY is compared with the existing property names
     using `eq', so any object is a legitimate property.

     See `put' for an example.

 -- Function: put symbol property value
     This function puts VALUE onto SYMBOL's property list under the
     property name PROPERTY, replacing any previous property value.
     The `put' function returns VALUE.

          (put 'fly 'verb 'transitive)
               =>'transitive
          (put 'fly 'noun '(a buzzing little bug))
               => (a buzzing little bug)
          (get 'fly 'verb)
               => transitive
          (symbol-plist 'fly)
               => (verb transitive noun (a buzzing little bug))

File: elisp,  Node: Other Plists,  Prev: Symbol Plists,  Up: Property Lists

8.4.3 Property Lists Outside Symbols
------------------------------------

These functions are useful for manipulating property lists that are
stored in places other than symbols:

 -- Function: plist-get plist property
     This returns the value of the PROPERTY property stored in the
     property list PLIST.  It accepts a malformed PLIST argument.  If
     PROPERTY is not found in the PLIST, it returns `nil'.  For example,

          (plist-get '(foo 4) 'foo)
               => 4
          (plist-get '(foo 4 bad) 'foo)
               => 4
          (plist-get '(foo 4 bad) 'bad)
               => `nil'
          (plist-get '(foo 4 bad) 'bar)
               => nil

 -- Function: plist-put plist property value
     This stores VALUE as the value of the PROPERTY property in the
     property list PLIST.  It may modify PLIST destructively, or it may
     construct a new list structure without altering the old.  The
     function returns the modified property list, so you can store that
     back in the place where you got PLIST.  For example,

          (setq my-plist '(bar t foo 4))
               => (bar t foo 4)
          (setq my-plist (plist-put my-plist 'foo 69))
               => (bar t foo 69)
          (setq my-plist (plist-put my-plist 'quux '(a)))
               => (bar t foo 69 quux (a))

   You could define `put' in terms of `plist-put' as follows:

     (defun put (symbol prop value)
       (setplist symbol
                 (plist-put (symbol-plist symbol) prop value)))

 -- Function: lax-plist-get plist property
     Like `plist-get' except that it compares properties using `equal'
     instead of `eq'.

 -- Function: lax-plist-put plist property value
     Like `plist-put' except that it compares properties using `equal'
     instead of `eq'.

 -- Function: plist-member plist property
     This returns non-`nil' if PLIST contains the given PROPERTY.
     Unlike `plist-get', this allows you to distinguish between a
     missing property and a property with the value `nil'.  The value
     is actually the tail of PLIST whose `car' is PROPERTY.

File: elisp,  Node: Evaluation,  Next: Control Structures,  Prev: Symbols,  Up: Top

9 Evaluation
************

The "evaluation" of expressions in Emacs Lisp is performed by the "Lisp
interpreter"--a program that receives a Lisp object as input and
computes its "value as an expression".  How it does this depends on the
data type of the object, according to rules described in this chapter.
The interpreter runs automatically to evaluate portions of your
program, but can also be called explicitly via the Lisp primitive
function `eval'.

* Menu:

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

File: elisp,  Node: Intro Eval,  Next: Forms,  Up: Evaluation

9.1 Introduction to Evaluation
==============================

The Lisp interpreter, or evaluator, is the part of Emacs that computes
the value of an expression that is given to it.  When a function
written in Lisp is called, the evaluator computes the value of the
function by evaluating the expressions in the function body.  Thus,
running any Lisp program really means running the Lisp interpreter.

   A Lisp object that is intended for evaluation is called an
"expression" or a "form".  The fact that forms are data objects and not
merely text is one of the fundamental differences between Lisp-like
languages and typical programming languages.  Any object can be
evaluated, but in practice only numbers, symbols, lists and strings are
evaluated very often.

   In subsequent sections, we will describe the details of what
evaluation means for each kind of form.

   It is very common to read a Lisp form and then evaluate the form,
but reading and evaluation are separate activities, and either can be
performed alone.  Reading per se does not evaluate anything; it
converts the printed representation of a Lisp object to the object
itself.  It is up to the caller of `read' to specify whether this
object is a form to be evaluated, or serves some entirely different
purpose.  *Note Input Functions::.

   Evaluation is a recursive process, and evaluating a form often
involves evaluating parts within that form.  For instance, when you
evaluate a "function call" form such as `(car x)', Emacs first
evaluates the argument (the subform `x').  After evaluating the
argument, Emacs "executes" the function (`car'), and if the function is
written in Lisp, execution works by evaluating the "body" of the
function.  (In this example, however, `car' is not a Lisp function; it
is a primitive function implemented in C.)  *Note Functions::, for more
information about functions and function calls.

   Evaluation takes place in a context called the "environment", which
consists of the current values and bindings of all Lisp variables
(*note Variables::).(1)  Whenever a form refers to a variable without
creating a new binding for it, the variable evaluates to the value
given by the current environment.  Evaluating a form may create a new
environment for recursive evaluation, by binding variables (*note Local
Variables::).  Such environments are temporary, and vanish when the
evaluation of the form is complete.

   Evaluating a form may also make changes that persist; these changes
are called "side effects".  An example of a form that produces a side
effect is `(setq foo 1)'.

   Do not confuse evaluation with command key interpretation.  The
editor command loop translates keyboard input into a command (an
interactively callable function) using the active keymaps, and then
uses `call-interactively' to execute that command.  Executing the
command usually involves evaluation, if the command is written in Lisp;
however, this step is not considered a part of command key
interpretation.  *Note Command Loop::.

   ---------- Footnotes ----------

   (1) This definition of "environment" is specifically not intended to
include all the data that can affect the result of a program.

File: elisp,  Node: Forms,  Next: Quoting,  Prev: Intro Eval,  Up: Evaluation

9.2 Kinds of Forms
==================

A Lisp object that is intended to be evaluated is called a "form".  How
Emacs evaluates a form depends on its data type.  Emacs has three
different kinds of form that are evaluated differently: symbols, lists,
and "all other types."  This section describes all three kinds, one by
one, starting with the "all other types" which are self-evaluating
forms.

* Menu:

* 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 Indirection::    When a symbol appears as the car of a list,
			      we find the real function via the symbol.
* 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.

File: elisp,  Node: Self-Evaluating Forms,  Next: Symbol Forms,  Up: Forms

9.2.1 Self-Evaluating Forms
---------------------------

A "self-evaluating form" is any form that is not a list or symbol.
Self-evaluating forms evaluate to themselves: the result of evaluation
is the same object that was evaluated.  Thus, the number 25 evaluates
to 25, and the string `"foo"' evaluates to the string `"foo"'.
Likewise, evaluating a vector does not cause evaluation of the elements
of the vector--it returns the same vector with its contents unchanged.

     '123               ; A number, shown without evaluation.
          => 123
     123                ; Evaluated as usual--result is the same.
          => 123
     (eval '123)        ; Evaluated "by hand"--result is the same.
          => 123
     (eval (eval '123)) ; Evaluating twice changes nothing.
          => 123

   It is common to write numbers, characters, strings, and even vectors
in Lisp code, taking advantage of the fact that they self-evaluate.
However, it is quite unusual to do this for types that lack a read
syntax, because there's no way to write them textually.  It is possible
to construct Lisp expressions containing these types by means of a Lisp
program.  Here is an example:

     ;; Build an expression containing a buffer object.
     (setq print-exp (list 'print (current-buffer)))
          => (print #<buffer eval.texi>)
     ;; Evaluate it.
     (eval print-exp)
          -| #<buffer eval.texi>
          => #<buffer eval.texi>

File: elisp,  Node: Symbol Forms,  Next: Classifying Lists,  Prev: Self-Evaluating Forms,  Up: Forms

9.2.2 Symbol Forms
------------------

When a symbol is evaluated, it is treated as a variable.  The result is
the variable's value, if it has one.  If it has none (if its value cell
is void), an error is signaled.  For more information on the use of
variables, see *note Variables::.

   In the following example, we set the value of a symbol with `setq'.
Then we evaluate the symbol, and get back the value that `setq' stored.

     (setq a 123)
          => 123
     (eval 'a)
          => 123
     a
          => 123

   The symbols `nil' and `t' are treated specially, so that the value
of `nil' is always `nil', and the value of `t' is always `t'; you
cannot set or bind them to any other values.  Thus, these two symbols
act like self-evaluating forms, even though `eval' treats them like any
other symbol.  A symbol whose name starts with `:' also self-evaluates
in the same way; likewise, its value ordinarily cannot be changed.
*Note Constant Variables::.

File: elisp,  Node: Classifying Lists,  Next: Function Indirection,  Prev: Symbol Forms,  Up: Forms

9.2.3 Classification of List Forms
----------------------------------

A form that is a nonempty list is either a function call, a macro call,
or a special form, according to its first element.  These three kinds
of forms are evaluated in different ways, described below.  The
remaining list elements constitute the "arguments" for the function,
macro, or special form.

   The first step in evaluating a nonempty list is to examine its first
element.  This element alone determines what kind of form the list is
and how the rest of the list is to be processed.  The first element is
_not_ evaluated, as it would be in some Lisp dialects such as Scheme.

File: elisp,  Node: Function Indirection,  Next: Function Forms,  Prev: Classifying Lists,  Up: Forms

9.2.4 Symbol Function Indirection
---------------------------------

If the first element of the list is a symbol then evaluation examines
the symbol's function cell, and uses its contents instead of the
original symbol.  If the contents are another symbol, this process,
called "symbol function indirection", is repeated until it obtains a
non-symbol.  *Note Function Names::, for more information about symbol
function indirection.

   One possible consequence of this process is an infinite loop, in the
event that a symbol's function cell refers to the same symbol.  Or a
symbol may have a void function cell, in which case the subroutine
`symbol-function' signals a `void-function' error.  But if neither of
these things happens, we eventually obtain a non-symbol, which ought to
be a function or other suitable object.

   More precisely, we should now have a Lisp function (a lambda
expression), a byte-code function, a primitive function, a Lisp macro,
a special form, or an autoload object.  Each of these types is a case
described in one of the following sections.  If the object is not one
of these types, Emacs signals an `invalid-function' error.

   The following example illustrates the symbol indirection process.  We
use `fset' to set the function cell of a symbol and `symbol-function'
to get the function cell contents (*note Function Cells::).
Specifically, we store the symbol `car' into the function cell of
`first', and the symbol `first' into the function cell of `erste'.

     ;; Build this function cell linkage:
     ;;   -------------       -----        -------        -------
     ;;  | #<subr car> | <-- | car |  <-- | first |  <-- | erste |
     ;;   -------------       -----        -------        -------

     (symbol-function 'car)
          => #<subr car>
     (fset 'first 'car)
          => car
     (fset 'erste 'first)
          => first
     (erste '(1 2 3))   ; Call the function referenced by `erste'.
          => 1

   By contrast, the following example calls a function without any
symbol function indirection, because the first element is an anonymous
Lisp function, not a symbol.

     ((lambda (arg) (erste arg))
      '(1 2 3))
          => 1

Executing the function itself evaluates its body; this does involve
symbol function indirection when calling `erste'.

   The built-in function `indirect-function' provides an easy way to
perform symbol function indirection explicitly.

 -- Function: indirect-function function &optional noerror
     This function returns the meaning of FUNCTION as a function.  If
     FUNCTION is a symbol, then it finds FUNCTION's function definition
     and starts over with that value.  If FUNCTION is not a symbol,
     then it returns FUNCTION itself.

     This function signals a `void-function' error if the final symbol
     is unbound and optional argument NOERROR is `nil' or omitted.
     Otherwise, if NOERROR is non-`nil', it returns `nil' if the final
     symbol is unbound.

     It signals a `cyclic-function-indirection' error if there is a
     loop in the chain of symbols.

     Here is how you could define `indirect-function' in Lisp:

          (defun indirect-function (function)
            (if (symbolp function)
                (indirect-function (symbol-function function))
              function))

File: elisp,  Node: Function Forms,  Next: Macro Forms,  Prev: Function Indirection,  Up: Forms

9.2.5 Evaluation of Function Forms
----------------------------------

If the first element of a list being evaluated is a Lisp function
object, byte-code object or primitive function object, then that list is
a "function call".  For example, here is a call to the function `+':

     (+ 1 x)

   The first step in evaluating a function call is to evaluate the
remaining elements of the list from left to right.  The results are the
actual argument values, one value for each list element.  The next step
is to call the function with this list of arguments, effectively using
the function `apply' (*note Calling Functions::).  If the function is
written in Lisp, the arguments are used to bind the argument variables
of the function (*note Lambda Expressions::); then the forms in the
function body are evaluated in order, and the value of the last body
form becomes the value of the function call.

File: elisp,  Node: Macro Forms,  Next: Special Forms,  Prev: Function Forms,  Up: Forms

9.2.6 Lisp Macro Evaluation
---------------------------

If the first element of a list being evaluated is a macro object, then
the list is a "macro call".  When a macro call is evaluated, the
elements of the rest of the list are _not_ initially evaluated.
Instead, these elements themselves are used as the arguments of the
macro.  The macro definition computes a replacement form, called the
"expansion" of the macro, to be evaluated in place of the original
form.  The expansion may be any sort of form: a self-evaluating
constant, a symbol, or a list.  If the expansion is itself a macro call,
this process of expansion repeats until some other sort of form results.

   Ordinary evaluation of a macro call finishes by evaluating the
expansion.  However, the macro expansion is not necessarily evaluated
right away, or at all, because other programs also expand macro calls,
and they may or may not evaluate the expansions.

   Normally, the argument expressions are not evaluated as part of
computing the macro expansion, but instead appear as part of the
expansion, so they are computed when the expansion is evaluated.

   For example, given a macro defined as follows:

     (defmacro cadr (x)
       (list 'car (list 'cdr x)))

an expression such as `(cadr (assq 'handler list))' is a macro call,
and its expansion is:

     (car (cdr (assq 'handler list)))

Note that the argument `(assq 'handler list)' appears in the expansion.

   *Note Macros::, for a complete description of Emacs Lisp macros.

File: elisp,  Node: Special Forms,  Next: Autoloading,  Prev: Macro Forms,  Up: Forms

9.2.7 Special Forms
-------------------

A "special form" is a primitive function specially marked so that its
arguments are not all evaluated.  Most special forms define control
structures or perform variable bindings--things which functions cannot
do.

   Each special form has its own rules for which arguments are evaluated
and which are used without evaluation.  Whether a particular argument is
evaluated may depend on the results of evaluating other arguments.

   Here is a list, in alphabetical order, of all of the special forms in
Emacs Lisp with a reference to where each is described.

`and'
     *note Combining Conditions::

`catch'
     *note Catch and Throw::

`cond'
     *note Conditionals::

`condition-case'
     *note Handling Errors::

`defconst'
     *note Defining Variables::

`defmacro'
     *note Defining Macros::

`defun'
     *note Defining Functions::

`defvar'
     *note Defining Variables::

`function'
     *note Anonymous Functions::

`if'
     *note Conditionals::

`interactive'
     *note Interactive Call::

`let'
`let*'
     *note Local Variables::

`or'
     *note Combining Conditions::

`prog1'
`prog2'
`progn'
     *note Sequencing::

`quote'
     *note Quoting::

`save-current-buffer'
     *note Current Buffer::

`save-excursion'
     *note Excursions::

`save-restriction'
     *note Narrowing::

`save-window-excursion'
     *note Window Configurations::

`setq'
     *note Setting Variables::

`setq-default'
     *note Creating Buffer-Local::

`track-mouse'
     *note Mouse Tracking::

`unwind-protect'
     *note Nonlocal Exits::

`while'
     *note Iteration::

`with-output-to-temp-buffer'
     *note Temporary Displays::

     Common Lisp note: Here are some comparisons of special forms in
     GNU Emacs Lisp and Common Lisp.  `setq', `if', and `catch' are
     special forms in both Emacs Lisp and Common Lisp.  `defun' is a
     special form in Emacs Lisp, but a macro in Common Lisp.
     `save-excursion' is a special form in Emacs Lisp, but doesn't
     exist in Common Lisp.  `throw' is a special form in Common Lisp
     (because it must be able to throw multiple values), but it is a
     function in Emacs Lisp (which doesn't have multiple values).

File: elisp,  Node: Autoloading,  Prev: Special Forms,  Up: Forms

9.2.8 Autoloading
-----------------

The "autoload" feature allows you to call a function or macro whose
function definition has not yet been loaded into Emacs.  It specifies
which file contains the definition.  When an autoload object appears as
a symbol's function definition, calling that symbol as a function
automatically loads the specified file; then it calls the real
definition loaded from that file.  *Note Autoload::.

File: elisp,  Node: Quoting,  Next: Eval,  Prev: Forms,  Up: Evaluation

9.3 Quoting
===========

The special form `quote' returns its single argument, as written,
without evaluating it.  This provides a way to include constant symbols
and lists, which are not self-evaluating objects, in a program.  (It is
not necessary to quote self-evaluating objects such as numbers, strings,
and vectors.)

 -- Special Form: quote object
     This special form returns OBJECT, without evaluating it.

   Because `quote' is used so often in programs, Lisp provides a
convenient read syntax for it.  An apostrophe character (`'') followed
by a Lisp object (in read syntax) expands to a list whose first element
is `quote', and whose second element is the object.  Thus, the read
syntax `'x' is an abbreviation for `(quote x)'.

   Here are some examples of expressions that use `quote':

     (quote (+ 1 2))
          => (+ 1 2)
     (quote foo)
          => foo
     'foo
          => foo
     ''foo
          => (quote foo)
     '(quote foo)
          => (quote foo)
     ['foo]
          => [(quote foo)]

   Other quoting constructs include `function' (*note Anonymous
Functions::), which causes an anonymous lambda expression written in
Lisp to be compiled, and ``' (*note Backquote::), which is used to quote
only part of a list, while computing and substituting other parts.

File: elisp,  Node: Eval,  Prev: Quoting,  Up: Evaluation

9.4 Eval
========

Most often, forms are evaluated automatically, by virtue of their
occurrence in a program being run.  On rare occasions, you may need to
write code that evaluates a form that is computed at run time, such as
after reading a form from text being edited or getting one from a
property list.  On these occasions, use the `eval' function.

   The functions and variables described in this section evaluate forms,
specify limits to the evaluation process, or record recently returned
values.  Loading a file also does evaluation (*note Loading::).

   It is generally cleaner and more flexible to store a function in a
data structure, and call it with `funcall' or `apply', than to store an
expression in the data structure and evaluate it.  Using functions
provides the ability to pass information to them as arguments.

 -- Function: eval form
     This is the basic function evaluating an expression.  It evaluates
     FORM in the current environment and returns the result.  How the
     evaluation proceeds depends on the type of the object (*note
     Forms::).

     Since `eval' is a function, the argument expression that appears
     in a call to `eval' is evaluated twice: once as preparation before
     `eval' is called, and again by the `eval' function itself.  Here
     is an example:

          (setq foo 'bar)
               => bar
          (setq bar 'baz)
               => baz
          ;; Here `eval' receives argument `foo'
          (eval 'foo)
               => bar
          ;; Here `eval' receives argument `bar', which is the value of `foo'
          (eval foo)
               => baz

     The number of currently active calls to `eval' is limited to
     `max-lisp-eval-depth' (see below).

 -- Command: eval-region start end &optional stream read-function
     This function evaluates the forms in the current buffer in the
     region defined by the positions START and END.  It reads forms from
     the region and calls `eval' on them until the end of the region is
     reached, or until an error is signaled and not handled.

     By default, `eval-region' does not produce any output.  However,
     if STREAM is non-`nil', any output produced by output functions
     (*note Output Functions::), as well as the values that result from
     evaluating the expressions in the region are printed using STREAM.
     *Note Output Streams::.

     If READ-FUNCTION is non-`nil', it should be a function, which is
     used instead of `read' to read expressions one by one.  This
     function is called with one argument, the stream for reading
     input.  You can also use the variable `load-read-function' (*note
     How Programs Do Loading: Definition of load-read-function.)  to
     specify this function, but it is more robust to use the
     READ-FUNCTION argument.

     `eval-region' does not move point.  It always returns `nil'.

 -- Command: eval-buffer &optional buffer-or-name stream filename
          unibyte print
     This is similar to `eval-region', but the arguments provide
     different optional features.  `eval-buffer' operates on the entire
     accessible portion of buffer BUFFER-OR-NAME.  BUFFER-OR-NAME can
     be a buffer, a buffer name (a string), or `nil' (or omitted),
     which means to use the current buffer.  STREAM is used as in
     `eval-region', unless STREAM is `nil' and PRINT non-`nil'.  In
     that case, values that result from evaluating the expressions are
     still discarded, but the output of the output functions is printed
     in the echo area.  FILENAME is the file name to use for
     `load-history' (*note Unloading::), and defaults to
     `buffer-file-name' (*note Buffer File Name::).  If UNIBYTE is
     non-`nil', `read' converts strings to unibyte whenever possible.

     `eval-current-buffer' is an alias for this command.

 -- User Option: max-lisp-eval-depth
     This variable defines the maximum depth allowed in calls to `eval',
     `apply', and `funcall' before an error is signaled (with error
     message `"Lisp nesting exceeds max-lisp-eval-depth"').

     This limit, with the associated error when it is exceeded, is one
     way Emacs Lisp avoids infinite recursion on an ill-defined
     function.  If you increase the value of `max-lisp-eval-depth' too
     much, such code can cause stack overflow instead.

     The depth limit counts internal uses of `eval', `apply', and
     `funcall', such as for calling the functions mentioned in Lisp
     expressions, and recursive evaluation of function call arguments
     and function body forms, as well as explicit calls in Lisp code.

     The default value of this variable is 400.  If you set it to a
     value less than 100, Lisp will reset it to 100 if the given value
     is reached.  Entry to the Lisp debugger increases the value, if
     there is little room left, to make sure the debugger itself has
     room to execute.

     `max-specpdl-size' provides another limit on nesting.  *Note Local
     Variables: Definition of max-specpdl-size.

 -- Variable: values
     The value of this variable is a list of the values returned by all
     the expressions that were read, evaluated, and printed from buffers
     (including the minibuffer) by the standard Emacs commands which do
     this.  (Note that this does _not_ include evaluation in `*ielm*'
     buffers, nor evaluation using `C-j' in `lisp-interaction-mode'.)
     The elements are ordered most recent first.

          (setq x 1)
               => 1
          (list 'A (1+ 2) auto-save-default)
               => (A 3 t)
          values
               => ((A 3 t) 1 ...)

     This variable is useful for referring back to values of forms
     recently evaluated.  It is generally a bad idea to print the value
     of `values' itself, since this may be very long.  Instead, examine
     particular elements, like this:

          ;; Refer to the most recent evaluation result.
          (nth 0 values)
               => (A 3 t)
          ;; That put a new element on,
          ;;   so all elements move back one.
          (nth 1 values)
               => (A 3 t)
          ;; This gets the element that was next-to-most-recent
          ;;   before this example.
          (nth 3 values)
               => 1

File: elisp,  Node: Control Structures,  Next: Variables,  Prev: Evaluation,  Up: Top

10 Control Structures
*********************

A Lisp program consists of expressions or "forms" (*note Forms::).  We
control the order of execution of these forms by enclosing them in
"control structures".  Control structures are special forms which
control when, whether, or how many times to execute the forms they
contain.

   The simplest order of execution is sequential execution: first form
A, then form B, and so on.  This is what happens when you write several
forms in succession in the body of a function, or at top level in a
file of Lisp code--the forms are executed in the order written.  We
call this "textual order".  For example, if a function body consists of
two forms A and B, evaluation of the function evaluates first A and
then B.  The result of evaluating B becomes the value of the function.

   Explicit control structures make possible an order of execution other
than sequential.

   Emacs Lisp provides several kinds of control structure, including
other varieties of sequencing, conditionals, iteration, and (controlled)
jumps--all discussed below.  The built-in control structures are
special forms since their subforms are not necessarily evaluated or not
evaluated sequentially.  You can use macros to define your own control
structure constructs (*note Macros::).

* Menu:

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

File: elisp,  Node: Sequencing,  Next: Conditionals,  Up: Control Structures

10.1 Sequencing
===============

Evaluating forms in the order they appear is the most common way
control passes from one form to another.  In some contexts, such as in a
function body, this happens automatically.  Elsewhere you must use a
control structure construct to do this: `progn', the simplest control
construct of Lisp.

   A `progn' special form looks like this:

     (progn A B C ...)

and it says to execute the forms A, B, C, and so on, in that order.
These forms are called the "body" of the `progn' form.  The value of
the last form in the body becomes the value of the entire `progn'.
`(progn)' returns `nil'.

   In the early days of Lisp, `progn' was the only way to execute two
or more forms in succession and use the value of the last of them.  But
programmers found they often needed to use a `progn' in the body of a
function, where (at that time) only one form was allowed.  So the body
of a function was made into an "implicit `progn'": several forms are
allowed just as in the body of an actual `progn'.  Many other control
structures likewise contain an implicit `progn'.  As a result, `progn'
is not used as much as it was many years ago.  It is needed now most
often inside an `unwind-protect', `and', `or', or in the THEN-part of
an `if'.

 -- Special Form: progn forms...
     This special form evaluates all of the FORMS, in textual order,
     returning the result of the final form.

          (progn (print "The first form")
                 (print "The second form")
                 (print "The third form"))
               -| "The first form"
               -| "The second form"
               -| "The third form"
          => "The third form"

   Two other control constructs likewise evaluate a series of forms but
return a different value:

 -- Special Form: prog1 form1 forms...
     This special form evaluates FORM1 and all of the FORMS, in textual
     order, returning the result of FORM1.

          (prog1 (print "The first form")
                 (print "The second form")
                 (print "The third form"))
               -| "The first form"
               -| "The second form"
               -| "The third form"
          => "The first form"

     Here is a way to remove the first element from a list in the
     variable `x', then return the value of that former element:

          (prog1 (car x) (setq x (cdr x)))

 -- Special Form: prog2 form1 form2 forms...
     This special form evaluates FORM1, FORM2, and all of the following
     FORMS, in textual order, returning the result of FORM2.

          (prog2 (print "The first form")
                 (print "The second form")
                 (print "The third form"))
               -| "The first form"
               -| "The second form"
               -| "The third form"
          => "The second form"

File: elisp,  Node: Conditionals,  Next: Combining Conditions,  Prev: Sequencing,  Up: Control Structures

10.2 Conditionals
=================

Conditional control structures choose among alternatives.  Emacs Lisp
has four conditional forms: `if', which is much the same as in other
languages; `when' and `unless', which are variants of `if'; and `cond',
which is a generalized case statement.

 -- Special Form: if condition then-form else-forms...
     `if' chooses between the THEN-FORM and the ELSE-FORMS based on the
     value of CONDITION.  If the evaluated CONDITION is non-`nil',
     THEN-FORM is evaluated and the result returned.  Otherwise, the
     ELSE-FORMS are evaluated in textual order, and the value of the
     last one is returned.  (The ELSE part of `if' is an example of an
     implicit `progn'.  *Note Sequencing::.)

     If CONDITION has the value `nil', and no ELSE-FORMS are given,
     `if' returns `nil'.

     `if' is a special form because the branch that is not selected is
     never evaluated--it is ignored.  Thus, in the example below,
     `true' is not printed because `print' is never called.

          (if nil
              (print 'true)
            'very-false)
          => very-false

 -- Macro: when condition then-forms...
     This is a variant of `if' where there are no ELSE-FORMS, and
     possibly several THEN-FORMS.  In particular,

          (when CONDITION A B C)

     is entirely equivalent to

          (if CONDITION (progn A B C) nil)

 -- Macro: unless condition forms...
     This is a variant of `if' where there is no THEN-FORM:

          (unless CONDITION A B C)

     is entirely equivalent to

          (if CONDITION nil
             A B C)

 -- Special Form: cond clause...
     `cond' chooses among an arbitrary number of alternatives.  Each
     CLAUSE in the `cond' must be a list.  The CAR of this list is the
     CONDITION; the remaining elements, if any, the BODY-FORMS.  Thus,
     a clause looks like this:

          (CONDITION BODY-FORMS...)

     `cond' tries the clauses in textual order, by evaluating the
     CONDITION of each clause.  If the value of CONDITION is non-`nil',
     the clause "succeeds"; then `cond' evaluates its BODY-FORMS, and
     the value of the last of BODY-FORMS becomes the value of the
     `cond'.  The remaining clauses are ignored.

     If the value of CONDITION is `nil', the clause "fails," so the
     `cond' moves on to the following clause, trying its CONDITION.

     If every CONDITION evaluates to `nil', so that every clause fails,
     `cond' returns `nil'.

     A clause may also look like this:

          (CONDITION)

     Then, if CONDITION is non-`nil' when tested, the value of
     CONDITION becomes the value of the `cond' form.

     The following example has four clauses, which test for the cases
     where the value of `x' is a number, string, buffer and symbol,
     respectively:

          (cond ((numberp x) x)
                ((stringp x) x)
                ((bufferp x)
                 (setq temporary-hack x) ; multiple body-forms
                 (buffer-name x))        ; in one clause
                ((symbolp x) (symbol-value x)))

     Often we want to execute the last clause whenever none of the
     previous clauses was successful.  To do this, we use `t' as the
     CONDITION of the last clause, like this: `(t BODY-FORMS)'.  The
     form `t' evaluates to `t', which is never `nil', so this clause
     never fails, provided the `cond' gets to it at all.

     For example,

          (setq a 5)
          (cond ((eq a 'hack) 'foo)
                (t "default"))
          => "default"

     This `cond' expression returns `foo' if the value of `a' is
     `hack', and returns the string `"default"' otherwise.

   Any conditional construct can be expressed with `cond' or with `if'.
Therefore, the choice between them is a matter of style.  For example:

     (if A B C)
     ==
     (cond (A B) (t C))

File: elisp,  Node: Combining Conditions,  Next: Iteration,  Prev: Conditionals,  Up: Control Structures

10.3 Constructs for Combining Conditions
========================================

This section describes three constructs that are often used together
with `if' and `cond' to express complicated conditions.  The constructs
`and' and `or' can also be used individually as kinds of multiple
conditional constructs.

 -- Function: not condition
     This function tests for the falsehood of CONDITION.  It returns
     `t' if CONDITION is `nil', and `nil' otherwise.  The function
     `not' is identical to `null', and we recommend using the name
     `null' if you are testing for an empty list.

 -- Special Form: and conditions...
     The `and' special form tests whether all the CONDITIONS are true.
     It works by evaluating the CONDITIONS one by one in the order
     written.

     If any of the CONDITIONS evaluates to `nil', then the result of
     the `and' must be `nil' regardless of the remaining CONDITIONS; so
     `and' returns `nil' right away, ignoring the remaining CONDITIONS.

     If all the CONDITIONS turn out non-`nil', then the value of the
     last of them becomes the value of the `and' form.  Just `(and)',
     with no CONDITIONS, returns `t', appropriate because all the
     CONDITIONS turned out non-`nil'.  (Think about it; which one did
     not?)

     Here is an example.  The first condition returns the integer 1,
     which is not `nil'.  Similarly, the second condition returns the
     integer 2, which is not `nil'.  The third condition is `nil', so
     the remaining condition is never evaluated.

          (and (print 1) (print 2) nil (print 3))
               -| 1
               -| 2
          => nil

     Here is a more realistic example of using `and':

          (if (and (consp foo) (eq (car foo) 'x))
              (message "foo is a list starting with x"))

     Note that `(car foo)' is not executed if `(consp foo)' returns
     `nil', thus avoiding an error.

     `and' expressions can also be written using either `if' or `cond'.
     Here's how:

          (and ARG1 ARG2 ARG3)
          ==
          (if ARG1 (if ARG2 ARG3))
          ==
          (cond (ARG1 (cond (ARG2 ARG3))))

 -- Special Form: or conditions...
     The `or' special form tests whether at least one of the CONDITIONS
     is true.  It works by evaluating all the CONDITIONS one by one in
     the order written.

     If any of the CONDITIONS evaluates to a non-`nil' value, then the
     result of the `or' must be non-`nil'; so `or' returns right away,
     ignoring the remaining CONDITIONS.  The value it returns is the
     non-`nil' value of the condition just evaluated.

     If all the CONDITIONS turn out `nil', then the `or' expression
     returns `nil'.  Just `(or)', with no CONDITIONS, returns `nil',
     appropriate because all the CONDITIONS turned out `nil'.  (Think
     about it; which one did not?)

     For example, this expression tests whether `x' is either `nil' or
     the integer zero:

          (or (eq x nil) (eq x 0))

     Like the `and' construct, `or' can be written in terms of `cond'.
     For example:

          (or ARG1 ARG2 ARG3)
          ==
          (cond (ARG1)
                (ARG2)
                (ARG3))

     You could almost write `or' in terms of `if', but not quite:

          (if ARG1 ARG1
            (if ARG2 ARG2
              ARG3))

     This is not completely equivalent because it can evaluate ARG1 or
     ARG2 twice.  By contrast, `(or ARG1 ARG2 ARG3)' never evaluates
     any argument more than once.

File: elisp,  Node: Iteration,  Next: Nonlocal Exits,  Prev: Combining Conditions,  Up: Control Structures

10.4 Iteration
==============

Iteration means executing part of a program repetitively.  For example,
you might want to repeat some computation once for each element of a
list, or once for each integer from 0 to N.  You can do this in Emacs
Lisp with the special form `while':

 -- Special Form: while condition forms...
     `while' first evaluates CONDITION.  If the result is non-`nil', it
     evaluates FORMS in textual order.  Then it reevaluates CONDITION,
     and if the result is non-`nil', it evaluates FORMS again.  This
     process repeats until CONDITION evaluates to `nil'.

     There is no limit on the number of iterations that may occur.  The
     loop will continue until either CONDITION evaluates to `nil' or
     until an error or `throw' jumps out of it (*note Nonlocal Exits::).

     The value of a `while' form is always `nil'.

          (setq num 0)
               => 0
          (while (< num 4)
            (princ (format "Iteration %d." num))
            (setq num (1+ num)))
               -| Iteration 0.
               -| Iteration 1.
               -| Iteration 2.
               -| Iteration 3.
               => nil

     To write a "repeat...until" loop, which will execute something on
     each iteration and then do the end-test, put the body followed by
     the end-test in a `progn' as the first argument of `while', as
     shown here:

          (while (progn
                   (forward-line 1)
                   (not (looking-at "^$"))))

     This moves forward one line and continues moving by lines until it
     reaches an empty line.  It is peculiar in that the `while' has no
     body, just the end test (which also does the real work of moving
     point).

   The `dolist' and `dotimes' macros provide convenient ways to write
two common kinds of loops.

 -- Macro: dolist (var list [result]) body...
     This construct executes BODY once for each element of LIST,
     binding the variable VAR locally to hold the current element.
     Then it returns the value of evaluating RESULT, or `nil' if RESULT
     is omitted.  For example, here is how you could use `dolist' to
     define the `reverse' function:

          (defun reverse (list)
            (let (value)
              (dolist (elt list value)
                (setq value (cons elt value)))))

 -- Macro: dotimes (var count [result]) body...
     This construct executes BODY once for each integer from 0
     (inclusive) to COUNT (exclusive), binding the variable VAR to the
     integer for the current iteration.  Then it returns the value of
     evaluating RESULT, or `nil' if RESULT is omitted.  Here is an
     example of using `dotimes' to do something 100 times:

          (dotimes (i 100)
            (insert "I will not obey absurd orders\n"))

File: elisp,  Node: Nonlocal Exits,  Prev: Iteration,  Up: Control Structures

10.5 Nonlocal Exits
===================

A "nonlocal exit" is a transfer of control from one point in a program
to another remote point.  Nonlocal exits can occur in Emacs Lisp as a
result of errors; you can also use them under explicit control.
Nonlocal exits unbind all variable bindings made by the constructs being
exited.

* Menu:

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

File: elisp,  Node: Catch and Throw,  Next: Examples of Catch,  Up: Nonlocal Exits

10.5.1 Explicit Nonlocal Exits: `catch' and `throw'
---------------------------------------------------

Most control constructs affect only the flow of control within the
construct itself.  The function `throw' is the exception to this rule
of normal program execution: it performs a nonlocal exit on request.
(There are other exceptions, but they are for error handling only.)
`throw' is used inside a `catch', and jumps back to that `catch'.  For
example:

     (defun foo-outer ()
       (catch 'foo
         (foo-inner)))

     (defun foo-inner ()
       ...
       (if x
           (throw 'foo t))
       ...)

The `throw' form, if executed, transfers control straight back to the
corresponding `catch', which returns immediately.  The code following
the `throw' is not executed.  The second argument of `throw' is used as
the return value of the `catch'.

   The function `throw' finds the matching `catch' based on the first
argument: it searches for a `catch' whose first argument is `eq' to the
one specified in the `throw'.  If there is more than one applicable
`catch', the innermost one takes precedence.  Thus, in the above
example, the `throw' specifies `foo', and the `catch' in `foo-outer'
specifies the same symbol, so that `catch' is the applicable one
(assuming there is no other matching `catch' in between).

   Executing `throw' exits all Lisp constructs up to the matching
`catch', including function calls.  When binding constructs such as
`let' or function calls are exited in this way, the bindings are
unbound, just as they are when these constructs exit normally (*note
Local Variables::).  Likewise, `throw' restores the buffer and position
saved by `save-excursion' (*note Excursions::), and the narrowing
status saved by `save-restriction' and the window selection saved by
`save-window-excursion' (*note Window Configurations::).  It also runs
any cleanups established with the `unwind-protect' special form when it
exits that form (*note Cleanups::).

   The `throw' need not appear lexically within the `catch' that it
jumps to.  It can equally well be called from another function called
within the `catch'.  As long as the `throw' takes place chronologically
after entry to the `catch', and chronologically before exit from it, it
has access to that `catch'.  This is why `throw' can be used in
commands such as `exit-recursive-edit' that throw back to the editor
command loop (*note Recursive Editing::).

     Common Lisp note: Most other versions of Lisp, including Common
     Lisp, have several ways of transferring control nonsequentially:
     `return', `return-from', and `go', for example.  Emacs Lisp has
     only `throw'.

 -- Special Form: catch tag body...
     `catch' establishes a return point for the `throw' function.  The
     return point is distinguished from other such return points by
     TAG, which may be any Lisp object except `nil'.  The argument TAG
     is evaluated normally before the return point is established.

     With the return point in effect, `catch' evaluates the forms of the
     BODY in textual order.  If the forms execute normally (without
     error or nonlocal exit) the value of the last body form is
     returned from the `catch'.

     If a `throw' is executed during the execution of BODY, specifying
     the same value TAG, the `catch' form exits immediately; the value
     it returns is whatever was specified as the second argument of
     `throw'.

 -- Function: throw tag value
     The purpose of `throw' is to return from a return point previously
     established with `catch'.  The argument TAG is used to choose
     among the various existing return points; it must be `eq' to the
     value specified in the `catch'.  If multiple return points match
     TAG, the innermost one is used.

     The argument VALUE is used as the value to return from that
     `catch'.

     If no return point is in effect with tag TAG, then a `no-catch'
     error is signaled with data `(TAG VALUE)'.

File: elisp,  Node: Examples of Catch,  Next: Errors,  Prev: Catch and Throw,  Up: Nonlocal Exits

10.5.2 Examples of `catch' and `throw'
--------------------------------------

One way to use `catch' and `throw' is to exit from a doubly nested
loop.  (In most languages, this would be done with a "go to.")  Here we
compute `(foo I J)' for I and J varying from 0 to 9:

     (defun search-foo ()
       (catch 'loop
         (let ((i 0))
           (while (< i 10)
             (let ((j 0))
               (while (< j 10)
                 (if (foo i j)
                     (throw 'loop (list i j)))
                 (setq j (1+ j))))
             (setq i (1+ i))))))

If `foo' ever returns non-`nil', we stop immediately and return a list
of I and J.  If `foo' always returns `nil', the `catch' returns
normally, and the value is `nil', since that is the result of the
`while'.

   Here are two tricky examples, slightly different, showing two return
points at once.  First, two return points with the same tag, `hack':

     (defun catch2 (tag)
       (catch tag
         (throw 'hack 'yes)))
     => catch2

     (catch 'hack
       (print (catch2 'hack))
       'no)
     -| yes
     => no

Since both return points have tags that match the `throw', it goes to
the inner one, the one established in `catch2'.  Therefore, `catch2'
returns normally with value `yes', and this value is printed.  Finally
the second body form in the outer `catch', which is `'no', is evaluated
and returned from the outer `catch'.

   Now let's change the argument given to `catch2':

     (catch 'hack
       (print (catch2 'quux))
       'no)
     => yes

We still have two return points, but this time only the outer one has
the tag `hack'; the inner one has the tag `quux' instead.  Therefore,
`throw' makes the outer `catch' return the value `yes'.  The function
`print' is never called, and the body-form `'no' is never evaluated.

File: elisp,  Node: Errors,  Next: Cleanups,  Prev: Examples of Catch,  Up: Nonlocal Exits

10.5.3 Errors
-------------

When Emacs Lisp attempts to evaluate a form that, for some reason,
cannot be evaluated, it "signals" an "error".

   When an error is signaled, Emacs's default reaction is to print an
error message and terminate execution of the current command.  This is
the right thing to do in most cases, such as if you type `C-f' at the
end of the buffer.

   In complicated programs, simple termination may not be what you want.
For example, the program may have made temporary changes in data
structures, or created temporary buffers that should be deleted before
the program is finished.  In such cases, you would use `unwind-protect'
to establish "cleanup expressions" to be evaluated in case of error.
(*Note Cleanups::.)  Occasionally, you may wish the program to continue
execution despite an error in a subroutine.  In these cases, you would
use `condition-case' to establish "error handlers" to recover control
in case of error.

   Resist the temptation to use error handling to transfer control from
one part of the program to another; use `catch' and `throw' instead.
*Note Catch and Throw::.

* Menu:

* Signaling Errors::      How to report an error.
* Processing of Errors::  What Emacs 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.

File: elisp,  Node: Signaling Errors,  Next: Processing of Errors,  Up: Errors

10.5.3.1 How to Signal an Error
...............................

"Signaling" an error means beginning error processing.  Error
processing normally aborts all or part of the running program and
returns to a point that is set up to handle the error (*note Processing
of Errors::).  Here we describe how to signal an error.

   Most errors are signaled "automatically" within Lisp primitives
which you call for other purposes, such as if you try to take the CAR
of an integer or move forward a character at the end of the buffer.
You can also signal errors explicitly with the functions `error' and
`signal'.

   Quitting, which happens when the user types `C-g', is not considered
an error, but it is handled almost like an error.  *Note Quitting::.

   Every error specifies an error message, one way or another.  The
message should state what is wrong ("File does not exist"), not how
things ought to be ("File must exist").  The convention in Emacs Lisp
is that error messages should start with a capital letter, but should
not end with any sort of punctuation.

 -- Function: error format-string &rest args
     This function signals an error with an error message constructed by
     applying `format' (*note Formatting Strings::) to FORMAT-STRING
     and ARGS.

     These examples show typical uses of `error':

          (error "That is an error -- try something else")
               error--> That is an error -- try something else

          (error "You have committed %d errors" 10)
               error--> You have committed 10 errors

     `error' works by calling `signal' with two arguments: the error
     symbol `error', and a list containing the string returned by
     `format'.

     *Warning:* If you want to use your own string as an error message
     verbatim, don't just write `(error STRING)'.  If STRING contains
     `%', it will be interpreted as a format specifier, with
     undesirable results.  Instead, use `(error "%s" STRING)'.

 -- Function: signal error-symbol data
     This function signals an error named by ERROR-SYMBOL.  The
     argument DATA is a list of additional Lisp objects relevant to the
     circumstances of the error.

     The argument ERROR-SYMBOL must be an "error symbol"--a symbol
     bearing a property `error-conditions' whose value is a list of
     condition names.  This is how Emacs Lisp classifies different
     sorts of errors. *Note Error Symbols::, for a description of error
     symbols, error conditions and condition names.

     If the error is not handled, the two arguments are used in printing
     the error message.  Normally, this error message is provided by the
     `error-message' property of ERROR-SYMBOL.  If DATA is non-`nil',
     this is followed by a colon and a comma separated list of the
     unevaluated elements of DATA.  For `error', the error message is
     the CAR of DATA (that must be a string).  Subcategories of
     `file-error' are handled specially.

     The number and significance of the objects in DATA depends on
     ERROR-SYMBOL.  For example, with a `wrong-type-argument' error,
     there should be two objects in the list: a predicate that
     describes the type that was expected, and the object that failed
     to fit that type.

     Both ERROR-SYMBOL and DATA are available to any error handlers
     that handle the error: `condition-case' binds a local variable to
     a list of the form `(ERROR-SYMBOL .  DATA)' (*note Handling
     Errors::).

     The function `signal' never returns (though in older Emacs versions
     it could sometimes return).

          (signal 'wrong-number-of-arguments '(x y))
               error--> Wrong number of arguments: x, y

          (signal 'no-such-error '("My unknown error condition"))
               error--> peculiar error: "My unknown error condition"

     Common Lisp note: Emacs Lisp has nothing like the Common Lisp
     concept of continuable errors.

File: elisp,  Node: Processing of Errors,  Next: Handling Errors,  Prev: Signaling Errors,  Up: Errors

10.5.3.2 How Emacs Processes Errors
...................................

When an error is signaled, `signal' searches for an active "handler"
for the error.  A handler is a sequence of Lisp expressions designated
to be executed if an error happens in part of the Lisp program.  If the
error has an applicable handler, the handler is executed, and control
resumes following the handler.  The handler executes in the environment
of the `condition-case' that established it; all functions called
within that `condition-case' have already been exited, and the handler
cannot return to them.

   If there is no applicable handler for the error, it terminates the
current command and returns control to the editor command loop.  (The
command loop has an implicit handler for all kinds of errors.)  The
command loop's handler uses the error symbol and associated data to
print an error message.  You can use the variable
`command-error-function' to control how this is done:

 -- Variable: command-error-function
     This variable, if non-`nil', specifies a function to use to handle
     errors that return control to the Emacs command loop.  The
     function should take three arguments: DATA, a list of the same
     form that `condition-case' would bind to its variable; CONTEXT, a
     string describing the situation in which the error occurred, or
     (more often) `nil'; and CALLER, the Lisp function which called the
     primitive that signaled the error.

   An error that has no explicit handler may call the Lisp debugger.
The debugger is enabled if the variable `debug-on-error' (*note Error
Debugging::) is non-`nil'.  Unlike error handlers, the debugger runs in
the environment of the error, so that you can examine values of
variables precisely as they were at the time of the error.

File: elisp,  Node: Handling Errors,  Next: Error Symbols,  Prev: Processing of Errors,  Up: Errors

10.5.3.3 Writing Code to Handle Errors
......................................

The usual effect of signaling an error is to terminate the command that
is running and return immediately to the Emacs editor command loop.
You can arrange to trap errors occurring in a part of your program by
establishing an error handler, with the special form `condition-case'.
A simple example looks like this:

     (condition-case nil
         (delete-file filename)
       (error nil))

This deletes the file named FILENAME, catching any error and returning
`nil' if an error occurs(1).

   The `condition-case' construct is often used to trap errors that are
predictable, such as failure to open a file in a call to
`insert-file-contents'.  It is also used to trap errors that are
totally unpredictable, such as when the program evaluates an expression
read from the user.

   The second argument of `condition-case' is called the "protected
form".  (In the example above, the protected form is a call to
`delete-file'.)  The error handlers go into effect when this form
begins execution and are deactivated when this form returns.  They
remain in effect for all the intervening time.  In particular, they are
in effect during the execution of functions called by this form, in
their subroutines, and so on.  This is a good thing, since, strictly
speaking, errors can be signaled only by Lisp primitives (including
`signal' and `error') called by the protected form, not by the
protected form itself.

   The arguments after the protected form are handlers.  Each handler
lists one or more "condition names" (which are symbols) to specify
which errors it will handle.  The error symbol specified when an error
is signaled also defines a list of condition names.  A handler applies
to an error if they have any condition names in common.  In the example
above, there is one handler, and it specifies one condition name,
`error', which covers all errors.

   The search for an applicable handler checks all the established
handlers starting with the most recently established one.  Thus, if two
nested `condition-case' forms offer to handle the same error, the inner
of the two gets to handle it.

   If an error is handled by some `condition-case' form, this
ordinarily prevents the debugger from being run, even if
`debug-on-error' says this error should invoke the debugger.

   If you want to be able to debug errors that are caught by a
`condition-case', set the variable `debug-on-signal' to a non-`nil'
value.  You can also specify that a particular handler should let the
debugger run first, by writing `debug' among the conditions, like this:

     (condition-case nil
         (delete-file filename)
       ((debug error) nil))

The effect of `debug' here is only to prevent `condition-case' from
suppressing the call to the debugger.  Any given error will invoke the
debugger only if `debug-on-error' and the other usual filtering
mechanisms say it should.  *Note Error Debugging::.

   Once Emacs decides that a certain handler handles the error, it
returns control to that handler.  To do so, Emacs unbinds all variable
bindings made by binding constructs that are being exited, and executes
the cleanups of all `unwind-protect' forms that are being exited.  Once
control arrives at the handler, the body of the handler executes
normally.

   After execution of the handler body, execution returns from the
`condition-case' form.  Because the protected form is exited completely
before execution of the handler, the handler cannot resume execution at
the point of the error, nor can it examine variable bindings that were
made within the protected form.  All it can do is clean up and proceed.

   Error signaling and handling have some resemblance to `throw' and
`catch' (*note Catch and Throw::), but they are entirely separate
facilities.  An error cannot be caught by a `catch', and a `throw'
cannot be handled by an error handler (though using `throw' when there
is no suitable `catch' signals an error that can be handled).

 -- Special Form: condition-case var protected-form handlers...
     This special form establishes the error handlers HANDLERS around
     the execution of PROTECTED-FORM.  If PROTECTED-FORM executes
     without error, the value it returns becomes the value of the
     `condition-case' form; in this case, the `condition-case' has no
     effect.  The `condition-case' form makes a difference when an
     error occurs during PROTECTED-FORM.

     Each of the HANDLERS is a list of the form `(CONDITIONS BODY...)'.
     Here CONDITIONS is an error condition name to be handled, or a
     list of condition names (which can include `debug' to allow the
     debugger to run before the handler); BODY is one or more Lisp
     expressions to be executed when this handler handles an error.
     Here are examples of handlers:

          (error nil)

          (arith-error (message "Division by zero"))

          ((arith-error file-error)
           (message
            "Either division by zero or failure to open a file"))

     Each error that occurs has an "error symbol" that describes what
     kind of error it is.  The `error-conditions' property of this
     symbol is a list of condition names (*note Error Symbols::).  Emacs
     searches all the active `condition-case' forms for a handler that
     specifies one or more of these condition names; the innermost
     matching `condition-case' handles the error.  Within this
     `condition-case', the first applicable handler handles the error.

     After executing the body of the handler, the `condition-case'
     returns normally, using the value of the last form in the handler
     body as the overall value.

     The argument VAR is a variable.  `condition-case' does not bind
     this variable when executing the PROTECTED-FORM, only when it
     handles an error.  At that time, it binds VAR locally to an "error
     description", which is a list giving the particulars of the error.
     The error description has the form `(ERROR-SYMBOL . DATA)'.  The
     handler can refer to this list to decide what to do.  For example,
     if the error is for failure opening a file, the file name is the
     second element of DATA--the third element of the error description.

     If VAR is `nil', that means no variable is bound.  Then the error
     symbol and associated data are not available to the handler.

 -- Function: error-message-string error-description
     This function returns the error message string for a given error
     descriptor.  It is useful if you want to handle an error by
     printing the usual error message for that error.  *Note Definition
     of signal::.

   Here is an example of using `condition-case' to handle the error
that results from dividing by zero.  The handler displays the error
message (but without a beep), then returns a very large number.

     (defun safe-divide (dividend divisor)
       (condition-case err
           ;; Protected form.
           (/ dividend divisor)
         ;; The handler.
         (arith-error                        ; Condition.
          ;; Display the usual message for this error.
          (message "%s" (error-message-string err))
          1000000)))
     => safe-divide

     (safe-divide 5 0)
          -| Arithmetic error: (arith-error)
     => 1000000

The handler specifies condition name `arith-error' so that it will
handle only division-by-zero errors.  Other kinds of errors will not be
handled, at least not by this `condition-case'.  Thus,

     (safe-divide nil 3)
          error--> Wrong type argument: number-or-marker-p, nil

   Here is a `condition-case' that catches all kinds of errors,
including those signaled with `error':

     (setq baz 34)
          => 34

     (condition-case err
         (if (eq baz 35)
             t
           ;; This is a call to the function `error'.
           (error "Rats!  The variable %s was %s, not 35" 'baz baz))
       ;; This is the handler; it is not a form.
       (error (princ (format "The error was: %s" err))
              2))
     -| The error was: (error "Rats!  The variable baz was 34, not 35")
     => 2

 -- Macro: ignore-errors body...
     This construct executes BODY, ignoring any errors that occur
     during its execution.  If the execution is without error,
     `ignore-errors' returns the value of the last form in BODY;
     otherwise, it returns `nil'.

     Here's the example at the beginning of this subsection rewritten
     using `ignore-errors':

            (ignore-errors
             (delete-file filename))

   ---------- Footnotes ----------

   (1) Actually, you should use `ignore-errors' in such a simple case;
see below.

File: elisp,  Node: Error Symbols,  Prev: Handling Errors,  Up: Errors

10.5.3.4 Error Symbols and Condition Names
..........................................

When you signal an error, you specify an "error symbol" to specify the
kind of error you have in mind.  Each error has one and only one error
symbol to categorize it.  This is the finest classification of errors
defined by the Emacs Lisp language.

   These narrow classifications are grouped into a hierarchy of wider
classes called "error conditions", identified by "condition names".
The narrowest such classes belong to the error symbols themselves: each
error symbol is also a condition name.  There are also condition names
for more extensive classes, up to the condition name `error' which
takes in all kinds of errors (but not `quit').  Thus, each error has
one or more condition names: `error', the error symbol if that is
distinct from `error', and perhaps some intermediate classifications.

   In order for a symbol to be an error symbol, it must have an
`error-conditions' property which gives a list of condition names.
This list defines the conditions that this kind of error belongs to.
(The error symbol itself, and the symbol `error', should always be
members of this list.)  Thus, the hierarchy of condition names is
defined by the `error-conditions' properties of the error symbols.
Because quitting is not considered an error, the value of the
`error-conditions' property of `quit' is just `(quit)'.

   In addition to the `error-conditions' list, the error symbol should
have an `error-message' property whose value is a string to be printed
when that error is signaled but not handled.  If the error symbol has
no `error-message' property or if the `error-message' property exists,
but is not a string, the error message `peculiar error' is used.  *Note
Definition of signal::.

   Here is how we define a new error symbol, `new-error':

     (put 'new-error
          'error-conditions
          '(error my-own-errors new-error))
     => (error my-own-errors new-error)
     (put 'new-error 'error-message "A new error")
     => "A new error"

This error has three condition names: `new-error', the narrowest
classification; `my-own-errors', which we imagine is a wider
classification; and `error', which is the widest of all.

   The error string should start with a capital letter but it should
not end with a period.  This is for consistency with the rest of Emacs.

   Naturally, Emacs will never signal `new-error' on its own; only an
explicit call to `signal' (*note Definition of signal::) in your code
can do this:

     (signal 'new-error '(x y))
          error--> A new error: x, y

   This error can be handled through any of the three condition names.
This example handles `new-error' and any other errors in the class
`my-own-errors':

     (condition-case foo
         (bar nil t)
       (my-own-errors nil))

   The significant way that errors are classified is by their condition
names--the names used to match errors with handlers.  An error symbol
serves only as a convenient way to specify the intended error message
and list of condition names.  It would be cumbersome to give `signal' a
list of condition names rather than one error symbol.

   By contrast, using only error symbols without condition names would
seriously decrease the power of `condition-case'.  Condition names make
it possible to categorize errors at various levels of generality when
you write an error handler.  Using error symbols alone would eliminate
all but the narrowest level of classification.

   *Note Standard Errors::, for a list of all the standard error symbols
and their conditions.

File: elisp,  Node: Cleanups,  Prev: Errors,  Up: Nonlocal Exits

10.5.4 Cleaning Up from Nonlocal Exits
--------------------------------------

The `unwind-protect' construct is essential whenever you temporarily
put a data structure in an inconsistent state; it permits you to make
the data consistent again in the event of an error or throw.  (Another
more specific cleanup construct that is used only for changes in buffer
contents is the atomic change group; *note Atomic Changes::.)

 -- Special Form: unwind-protect body-form cleanup-forms...
     `unwind-protect' executes BODY-FORM with a guarantee that the
     CLEANUP-FORMS will be evaluated if control leaves BODY-FORM, no
     matter how that happens.  BODY-FORM may complete normally, or
     execute a `throw' out of the `unwind-protect', or cause an error;
     in all cases, the CLEANUP-FORMS will be evaluated.

     If BODY-FORM finishes normally, `unwind-protect' returns the value
     of BODY-FORM, after it evaluates the CLEANUP-FORMS.  If BODY-FORM
     does not finish, `unwind-protect' does not return any value in the
     normal sense.

     Only BODY-FORM is protected by the `unwind-protect'.  If any of
     the CLEANUP-FORMS themselves exits nonlocally (via a `throw' or an
     error), `unwind-protect' is _not_ guaranteed to evaluate the rest
     of them.  If the failure of one of the CLEANUP-FORMS has the
     potential to cause trouble, then protect it with another
     `unwind-protect' around that form.

     The number of currently active `unwind-protect' forms counts,
     together with the number of local variable bindings, against the
     limit `max-specpdl-size' (*note Local Variables: Definition of
     max-specpdl-size.).

   For example, here we make an invisible buffer for temporary use, and
make sure to kill it before finishing:

     (save-excursion
       (let ((buffer (get-buffer-create " *temp*")))
         (set-buffer buffer)
         (unwind-protect
             BODY-FORM
           (kill-buffer buffer))))

You might think that we could just as well write `(kill-buffer
(current-buffer))' and dispense with the variable `buffer'.  However,
the way shown above is safer, if BODY-FORM happens to get an error
after switching to a different buffer!  (Alternatively, you could write
another `save-excursion' around BODY-FORM, to ensure that the temporary
buffer becomes current again in time to kill it.)

   Emacs includes a standard macro called `with-temp-buffer' which
expands into more or less the code shown above (*note Current Buffer:
Definition of with-temp-buffer.).  Several of the macros defined in
this manual use `unwind-protect' in this way.

   Here is an actual example derived from an FTP package.  It creates a
process (*note Processes::) to try to establish a connection to a remote
machine.  As the function `ftp-login' is highly susceptible to numerous
problems that the writer of the function cannot anticipate, it is
protected with a form that guarantees deletion of the process in the
event of failure.  Otherwise, Emacs might fill up with useless
subprocesses.

     (let ((win nil))
       (unwind-protect
           (progn
             (setq process (ftp-setup-buffer host file))
             (if (setq win (ftp-login process host user password))
                 (message "Logged in")
               (error "Ftp login failed")))
         (or win (and process (delete-process process)))))

   This example has a small bug: if the user types `C-g' to quit, and
the quit happens immediately after the function `ftp-setup-buffer'
returns but before the variable `process' is set, the process will not
be killed.  There is no easy way to fix this bug, but at least it is
very unlikely.

File: elisp,  Node: Variables,  Next: Functions,  Prev: Control Structures,  Up: Top

11 Variables
************

A "variable" is a name used in a program to stand for a value.  Nearly
all programming languages have variables of some sort.  In the text of
a Lisp program, variables are written using the syntax for symbols.

   In Lisp, unlike most programming languages, programs are represented
primarily as Lisp objects and only secondarily as text.  The Lisp
objects used for variables are symbols: the symbol name is the variable
name, and the variable's value is stored in the value cell of the
symbol.  The use of a symbol as a variable is independent of its use as
a function name.  *Note Symbol Components::.

   The textual form of a Lisp program is given by the read syntax of
the Lisp objects that constitute the program.  Hence, a variable in a
textual Lisp program is written using the read syntax for the symbol
representing the variable.

* Menu:

* 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.
* Tips for Defining::     Things you should think about when you
                            define 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.
* File Local Variables::  Handling local variable lists in files.
* Directory Local Variables:: Local variables common to all files in a directory.
* Frame-Local Variables:: Frame-local bindings for variables.
* Variable Aliases::      Variables that are aliases for other variables.
* Variables with Restricted Values::  Non-constant variables whose value can
                                        _not_ be an arbitrary Lisp object.

File: elisp,  Node: Global Variables,  Next: Constant Variables,  Up: Variables

11.1 Global Variables
=====================

The simplest way to use a variable is "globally".  This means that the
variable has just one value at a time, and this value is in effect (at
least for the moment) throughout the Lisp system.  The value remains in
effect until you specify a new one.  When a new value replaces the old
one, no trace of the old value remains in the variable.

   You specify a value for a symbol with `setq'.  For example,

     (setq x '(a b))

gives the variable `x' the value `(a b)'.  Note that `setq' is a
special form (*note Special Forms::); it does not evaluate its first
argument, the name of the variable, but it does evaluate the second
argument, the new value.

   Once the variable has a value, you can refer to it by using the
symbol itself as an expression.  Thus,

     x => (a b)

assuming the `setq' form shown above has already been executed.

   If you do set the same variable again, the new value replaces the old
one:

     x
          => (a b)
     (setq x 4)
          => 4
     x
          => 4

File: elisp,  Node: Constant Variables,  Next: Local Variables,  Prev: Global Variables,  Up: Variables

11.2 Variables that Never Change
================================

In Emacs Lisp, certain symbols normally evaluate to themselves.  These
include `nil' and `t', as well as any symbol whose name starts with `:'
(these are called "keywords").  These symbols cannot be rebound, nor
can their values be changed.  Any attempt to set or bind `nil' or `t'
signals a `setting-constant' error.  The same is true for a keyword (a
symbol whose name starts with `:'), if it is interned in the standard
obarray, except that setting such a symbol to itself is not an error.

     nil == 'nil
          => nil
     (setq nil 500)
     error--> Attempt to set constant symbol: nil

 -- Function: keywordp object
     function returns `t' if OBJECT is a symbol whose name starts with
     `:', interned in the standard obarray, and returns `nil' otherwise.

File: elisp,  Node: Local Variables,  Next: Void Variables,  Prev: Constant Variables,  Up: Variables

11.3 Local Variables
====================

Global variables have values that last until explicitly superseded with
new values.  Sometimes it is useful to create variable values that
exist temporarily--only until a certain part of the program finishes.
These values are called "local", and the variables so used are called
"local variables".

   For example, when a function is called, its argument variables
receive new local values that last until the function exits.  The `let'
special form explicitly establishes new local values for specified
variables; these last until exit from the `let' form.

   Establishing a local value saves away the variable's previous value
(or lack of one).  We say that the previous value is "shadowed" and
"not visible".  Both global and local values may be shadowed (*note
Scope::).  After the life span of the local value is over, the previous
value (or lack of one) is restored.

   If you set a variable (such as with `setq') while it is local, this
replaces the local value; it does not alter the global value, or
previous local values, that are shadowed.  To model this behavior, we
speak of a "local binding" of the variable as well as a local value.

   The local binding is a conceptual place that holds a local value.
Entering a function, or a special form such as `let', creates the local
binding; exiting the function or the `let' removes the local binding.
While the local binding lasts, the variable's value is stored within
it.  Using `setq' or `set' while there is a local binding stores a
different value into the local binding; it does not create a new
binding.

   We also speak of the "global binding", which is where (conceptually)
the global value is kept.

   A variable can have more than one local binding at a time (for
example, if there are nested `let' forms that bind it).  In such a
case, the most recently created local binding that still exists is the
"current binding" of the variable.  (This rule is called "dynamic
scoping"; see *note Variable Scoping::.)  If there are no local
bindings, the variable's global binding is its current binding.  We
sometimes call the current binding the "most-local existing binding",
for emphasis.  Ordinary evaluation of a symbol always returns the value
of its current binding.

   The special forms `let' and `let*' exist to create local bindings.

 -- Special Form: let (bindings...) forms...
     This special form binds variables according to BINDINGS and then
     evaluates all of the FORMS in textual order.  The `let'-form
     returns the value of the last form in FORMS.

     Each of the BINDINGS is either (i) a symbol, in which case that
     symbol is bound to `nil'; or (ii) a list of the form `(SYMBOL
     VALUE-FORM)', in which case SYMBOL is bound to the result of
     evaluating VALUE-FORM.  If VALUE-FORM is omitted, `nil' is used.

     All of the VALUE-FORMs in BINDINGS are evaluated in the order they
     appear and _before_ binding any of the symbols to them.  Here is
     an example of this: `z' is bound to the old value of `y', which is
     2, not the new value of `y', which is 1.

          (setq y 2)
               => 2
          (let ((y 1)
                (z y))
            (list y z))
               => (1 2)

 -- Special Form: let* (bindings...) forms...
     This special form is like `let', but it binds each variable right
     after computing its local value, before computing the local value
     for the next variable.  Therefore, an expression in BINDINGS can
     reasonably refer to the preceding symbols bound in this `let*'
     form.  Compare the following example with the example above for
     `let'.

          (setq y 2)
               => 2
          (let* ((y 1)
                 (z y))    ; Use the just-established value of `y'.
            (list y z))
               => (1 1)

   Here is a complete list of the other facilities that create local
bindings:

   * Function calls (*note Functions::).

   * Macro calls (*note Macros::).

   * `condition-case' (*note Errors::).

   Variables can also have buffer-local bindings (*note Buffer-Local
Variables::); a few variables have terminal-local bindings (*note
Multiple Terminals::).  These kinds of bindings work somewhat like
ordinary local bindings, but they are localized depending on "where"
you are in Emacs, rather than localized in time.

 -- User Option: max-specpdl-size
     This variable defines the limit on the total number of local
     variable bindings and `unwind-protect' cleanups (see *note
     Cleaning Up from Nonlocal Exits: Cleanups.) that are allowed
     before Emacs signals an error (with data `"Variable binding depth
     exceeds max-specpdl-size"').

     This limit, with the associated error when it is exceeded, is one
     way that Lisp avoids infinite recursion on an ill-defined function.
     `max-lisp-eval-depth' provides another limit on depth of nesting.
     *Note Eval: Definition of max-lisp-eval-depth.

     The default value is 1000.  Entry to the Lisp debugger increases
     the value, if there is little room left, to make sure the debugger
     itself has room to execute.

File: elisp,  Node: Void Variables,  Next: Defining Variables,  Prev: Local Variables,  Up: Variables

11.4 When a Variable is "Void"
==============================

If you have never given a symbol any value as a global variable, we say
that that symbol's global value is "void".  In other words, the
symbol's value cell does not have any Lisp object in it.  If you try to
evaluate the symbol, you get a `void-variable' error rather than a
value.

   Note that a value of `nil' is not the same as void.  The symbol
`nil' is a Lisp object and can be the value of a variable just as any
other object can be; but it is _a value_.  A void variable does not
have any value.

   After you have given a variable a value, you can make it void once
more using `makunbound'.

 -- Function: makunbound symbol
     This function makes the current variable binding of SYMBOL void.
     Subsequent attempts to use this symbol's value as a variable will
     signal the error `void-variable', unless and until you set it
     again.

     `makunbound' returns SYMBOL.

          (makunbound 'x)      ; Make the global value of `x' void.
               => x
          x
          error--> Symbol's value as variable is void: x

     If SYMBOL is locally bound, `makunbound' affects the most local
     existing binding.  This is the only way a symbol can have a void
     local binding, since all the constructs that create local bindings
     create them with values.  In this case, the voidness lasts at most
     as long as the binding does; when the binding is removed due to
     exit from the construct that made it, the previous local or global
     binding is reexposed as usual, and the variable is no longer void
     unless the newly reexposed binding was void all along.

          (setq x 1)               ; Put a value in the global binding.
               => 1
          (let ((x 2))             ; Locally bind it.
            (makunbound 'x)        ; Void the local binding.
            x)
          error--> Symbol's value as variable is void: x
          x                        ; The global binding is unchanged.
               => 1

          (let ((x 2))             ; Locally bind it.
            (let ((x 3))           ; And again.
              (makunbound 'x)      ; Void the innermost-local binding.
              x))                  ; And refer: it's void.
          error--> Symbol's value as variable is void: x

          (let ((x 2))
            (let ((x 3))
              (makunbound 'x))     ; Void inner binding, then remove it.
            x)                     ; Now outer `let' binding is visible.
               => 2

   A variable that has been made void with `makunbound' is
indistinguishable from one that has never received a value and has
always been void.

   You can use the function `boundp' to test whether a variable is
currently void.

 -- Function: boundp variable
     `boundp' returns `t' if VARIABLE (a symbol) is not void; more
     precisely, if its current binding is not void.  It returns `nil'
     otherwise.

          (boundp 'abracadabra)          ; Starts out void.
               => nil
          (let ((abracadabra 5))         ; Locally bind it.
            (boundp 'abracadabra))
               => t
          (boundp 'abracadabra)          ; Still globally void.
               => nil
          (setq abracadabra 5)           ; Make it globally nonvoid.
               => 5
          (boundp 'abracadabra)
               => t

File: elisp,  Node: Defining Variables,  Next: Tips for Defining,  Prev: Void Variables,  Up: Variables

11.5 Defining Global Variables
==============================

You may announce your intention to use a symbol as a global variable
with a "variable definition": a special form, either `defconst' or
`defvar'.

   In Emacs Lisp, definitions serve three purposes.  First, they inform
people who read the code that certain symbols are _intended_ to be used
a certain way (as variables).  Second, they inform the Lisp system of
these things, supplying a value and documentation.  Third, they provide
information to utilities such as `etags' and `make-docfile', which
create data bases of the functions and variables in a program.

   The difference between `defconst' and `defvar' is primarily a matter
of intent, serving to inform human readers of whether the value should
ever change.  Emacs Lisp does not restrict the ways in which a variable
can be used based on `defconst' or `defvar' declarations.  However, it
does make a difference for initialization: `defconst' unconditionally
initializes the variable, while `defvar' initializes it only if it is
void.

 -- Special Form: defvar symbol [value [doc-string]]
     This special form defines SYMBOL as a variable and can also
     initialize and document it.  The definition informs a person
     reading your code that SYMBOL is used as a variable that might be
     set or changed.  Note that SYMBOL is not evaluated; the symbol to
     be defined must appear explicitly in the `defvar'.

     If SYMBOL is void and VALUE is specified, `defvar' evaluates it
     and sets SYMBOL to the result.  But if SYMBOL already has a value
     (i.e., it is not void), VALUE is not even evaluated, and SYMBOL's
     value remains unchanged.  If VALUE is omitted, the value of SYMBOL
     is not changed in any case.

     If SYMBOL has a buffer-local binding in the current buffer,
     `defvar' operates on the default value, which is
     buffer-independent, not the current (buffer-local) binding.  It
     sets the default value if the default value is void.  *Note
     Buffer-Local Variables::.

     When you evaluate a top-level `defvar' form with `C-M-x' in Emacs
     Lisp mode (`eval-defun'), a special feature of `eval-defun'
     arranges to set the variable unconditionally, without testing
     whether its value is void.

     If the DOC-STRING argument appears, it specifies the documentation
     for the variable.  (This opportunity to specify documentation is
     one of the main benefits of defining the variable.)  The
     documentation is stored in the symbol's `variable-documentation'
     property.  The Emacs help functions (*note Documentation::) look
     for this property.

     If the documentation string begins with the character `*', Emacs
     allows users to set it interactively using the `set-variable'
     command.  However, you should nearly always use `defcustom'
     instead of `defvar' to define such variables, so that users can
     use `M-x customize' and related commands to set them.  In that
     case, it is not necessary to begin the documentation string with
     `*'.  *Note Customization::.

     Here are some examples.  This form defines `foo' but does not
     initialize it:

          (defvar foo)
               => foo

     This example initializes the value of `bar' to `23', and gives it
     a documentation string:

          (defvar bar 23
            "The normal weight of a bar.")
               => bar

     The following form changes the documentation string for `bar',
     making it a user option, but does not change the value, since `bar'
     already has a value.  (The addition `(1+ nil)' would get an error
     if it were evaluated, but since it is not evaluated, there is no
     error.)

          (defvar bar (1+ nil)
            "*The normal weight of a bar.")
               => bar
          bar
               => 23

     Here is an equivalent expression for the `defvar' special form:

          (defvar SYMBOL VALUE DOC-STRING)
          ==
          (progn
            (if (not (boundp 'SYMBOL))
                (setq SYMBOL VALUE))
            (if 'DOC-STRING
              (put 'SYMBOL 'variable-documentation 'DOC-STRING))
            'SYMBOL)

     The `defvar' form returns SYMBOL, but it is normally used at top
     level in a file where its value does not matter.

 -- Special Form: defconst symbol value [doc-string]
     This special form defines SYMBOL as a value and initializes it.
     It informs a person reading your code that SYMBOL has a standard
     global value, established here, that should not be changed by the
     user or by other programs.  Note that SYMBOL is not evaluated; the
     symbol to be defined must appear explicitly in the `defconst'.

     `defconst' always evaluates VALUE, and sets the value of SYMBOL to
     the result.  If SYMBOL does have a buffer-local binding in the
     current buffer, `defconst' sets the default value, not the
     buffer-local value.  (But you should not be making buffer-local
     bindings for a symbol that is defined with `defconst'.)

     Here, `pi' is a constant that presumably ought not to be changed
     by anyone (attempts by the Indiana State Legislature
     notwithstanding).  As the second form illustrates, however, this
     is only advisory.

          (defconst pi 3.1415 "Pi to five places.")
               => pi
          (setq pi 3)
               => pi
          pi
               => 3

 -- Function: user-variable-p variable
     This function returns `t' if VARIABLE is a user option--a variable
     intended to be set by the user for customization--and `nil'
     otherwise.  (Variables other than user options exist for the
     internal purposes of Lisp programs, and users need not know about
     them.)

     User option variables are distinguished from other variables either
     though being declared using `defcustom'(1) or by the first
     character of their `variable-documentation' property.  If the
     property exists and is a string, and its first character is `*',
     then the variable is a user option.  Aliases of user options are
     also user options.

   If a user option variable has a `variable-interactive' property, the
`set-variable' command uses that value to control reading the new value
for the variable.  The property's value is used as if it were specified
in `interactive' (*note Using Interactive::).  However, this feature is
largely obsoleted by `defcustom' (*note Customization::).

   *Warning:* If the `defconst' and `defvar' special forms are used
while the variable has a local binding (made with `let', or a function
argument), they set the local-binding's value; the top-level binding is
not changed.  This is not what you usually want.  To prevent it, use
these special forms at top level in a file, where normally no local
binding is in effect, and make sure to load the file before making a
local binding for the variable.

   ---------- Footnotes ----------

   (1) They may also be declared equivalently in `cus-start.el'.

File: elisp,  Node: Tips for Defining,  Next: Accessing Variables,  Prev: Defining Variables,  Up: Variables

11.6 Tips for Defining Variables Robustly
=========================================

When you define a variable whose value is a function, or a list of
functions, use a name that ends in `-function' or `-functions',
respectively.

   There are several other variable name conventions; here is a
complete list:

`...-hook'
     The variable is a normal hook (*note Hooks::).

`...-function'
     The value is a function.

`...-functions'
     The value is a list of functions.

`...-form'
     The value is a form (an expression).

`...-forms'
     The value is a list of forms (expressions).

`...-predicate'
     The value is a predicate--a function of one argument that returns
     non-`nil' for "good" arguments and `nil' for "bad" arguments.

`...-flag'
     The value is significant only as to whether it is `nil' or not.
     Since such variables often end up acquiring more values over time,
     this convention is not strongly recommended.

`...-program'
     The value is a program name.

`...-command'
     The value is a whole shell command.

`...-switches'
     The value specifies options for a command.

   When you define a variable, always consider whether you should mark
it as "safe" or "risky"; see *note File Local Variables::.

   When defining and initializing a variable that holds a complicated
value (such as a keymap with bindings in it), it's best to put the
entire computation of the value into the `defvar', like this:

     (defvar my-mode-map
       (let ((map (make-sparse-keymap)))
         (define-key map "\C-c\C-a" 'my-command)
         ...
         map)
       DOCSTRING)

This method has several benefits.  First, if the user quits while
loading the file, the variable is either still uninitialized or
initialized properly, never in-between.  If it is still uninitialized,
reloading the file will initialize it properly.  Second, reloading the
file once the variable is initialized will not alter it; that is
important if the user has run hooks to alter part of the contents (such
as, to rebind keys).  Third, evaluating the `defvar' form with `C-M-x'
_will_ reinitialize the map completely.

   Putting so much code in the `defvar' form has one disadvantage: it
puts the documentation string far away from the line which names the
variable.  Here's a safe way to avoid that:

     (defvar my-mode-map nil
       DOCSTRING)
     (unless my-mode-map
       (let ((map (make-sparse-keymap)))
         (define-key map "\C-c\C-a" 'my-command)
         ...
         (setq my-mode-map map)))

This has all the same advantages as putting the initialization inside
the `defvar', except that you must type `C-M-x' twice, once on each
form, if you do want to reinitialize the variable.

   But be careful not to write the code like this:

     (defvar my-mode-map nil
       DOCSTRING)
     (unless my-mode-map
       (setq my-mode-map (make-sparse-keymap))
       (define-key my-mode-map "\C-c\C-a" 'my-command)
       ...)

This code sets the variable, then alters it, but it does so in more than
one step.  If the user quits just after the `setq', that leaves the
variable neither correctly initialized nor void nor `nil'.  Once that
happens, reloading the file will not initialize the variable; it will
remain incomplete.

File: elisp,  Node: Accessing Variables,  Next: Setting Variables,  Prev: Tips for Defining,  Up: Variables

11.7 Accessing Variable Values
==============================

The usual way to reference a variable is to write the symbol which
names it (*note Symbol Forms::).  This requires you to specify the
variable name when you write the program.  Usually that is exactly what
you want to do.  Occasionally you need to choose at run time which
variable to reference; then you can use `symbol-value'.

 -- Function: symbol-value symbol
     This function returns the value of SYMBOL.  This is the value in
     the innermost local binding of the symbol, or its global value if
     it has no local bindings.

          (setq abracadabra 5)
               => 5
          (setq foo 9)
               => 9

          ;; Here the symbol `abracadabra'
          ;;   is the symbol whose value is examined.
          (let ((abracadabra 'foo))
            (symbol-value 'abracadabra))
               => foo

          ;; Here, the value of `abracadabra',
          ;;   which is `foo',
          ;;   is the symbol whose value is examined.
          (let ((abracadabra 'foo))
            (symbol-value abracadabra))
               => 9

          (symbol-value 'abracadabra)
               => 5

     A `void-variable' error is signaled if the current binding of
     SYMBOL is void.

File: elisp,  Node: Setting Variables,  Next: Variable Scoping,  Prev: Accessing Variables,  Up: Variables

11.8 How to Alter a Variable Value
==================================

The usual way to change the value of a variable is with the special
form `setq'.  When you need to compute the choice of variable at run
time, use the function `set'.

 -- Special Form: setq [symbol form]...
     This special form is the most common method of changing a
     variable's value.  Each SYMBOL is given a new value, which is the
     result of evaluating the corresponding FORM.  The most-local
     existing binding of the symbol is changed.

     `setq' does not evaluate SYMBOL; it sets the symbol that you
     write.  We say that this argument is "automatically quoted".  The
     `q' in `setq' stands for "quoted."

     The value of the `setq' form is the value of the last FORM.

          (setq x (1+ 2))
               => 3
          x                   ; `x' now has a global value.
               => 3
          (let ((x 5))
            (setq x 6)        ; The local binding of `x' is set.
            x)
               => 6
          x                   ; The global value is unchanged.
               => 3

     Note that the first FORM is evaluated, then the first SYMBOL is
     set, then the second FORM is evaluated, then the second SYMBOL is
     set, and so on:

          (setq x 10          ; Notice that `x' is set before
                y (1+ x))     ;   the value of `y' is computed.
               => 11

 -- Function: set symbol value
     This function sets SYMBOL's value to VALUE, then returns VALUE.
     Since `set' is a function, the expression written for SYMBOL is
     evaluated to obtain the symbol to set.

     The most-local existing binding of the variable is the binding
     that is set; shadowed bindings are not affected.

          (set one 1)
          error--> Symbol's value as variable is void: one
          (set 'one 1)
               => 1
          (set 'two 'one)
               => one
          (set two 2)         ; `two' evaluates to symbol `one'.
               => 2
          one                 ; So it is `one' that was set.
               => 2
          (let ((one 1))      ; This binding of `one' is set,
            (set 'one 3)      ;   not the global value.
            one)
               => 3
          one
               => 2

     If SYMBOL is not actually a symbol, a `wrong-type-argument' error
     is signaled.

          (set '(x y) 'z)
          error--> Wrong type argument: symbolp, (x y)

     Logically speaking, `set' is a more fundamental primitive than
     `setq'.  Any use of `setq' can be trivially rewritten to use
     `set'; `setq' could even be defined as a macro, given the
     availability of `set'.  However, `set' itself is rarely used;
     beginners hardly need to know about it.  It is useful only for
     choosing at run time which variable to set.  For example, the
     command `set-variable', which reads a variable name from the user
     and then sets the variable, needs to use `set'.

          Common Lisp note: In Common Lisp, `set' always changes the
          symbol's "special" or dynamic value, ignoring any lexical
          bindings.  In Emacs Lisp, all variables and all bindings are
          dynamic, so `set' always affects the most local existing
          binding.

File: elisp,  Node: Variable Scoping,  Next: Buffer-Local Variables,  Prev: Setting Variables,  Up: Variables

11.9 Scoping Rules for Variable Bindings
========================================

A given symbol `foo' can have several local variable bindings,
established at different places in the Lisp program, as well as a global
binding.  The most recently established binding takes precedence over
the others.

   Local bindings in Emacs Lisp have "indefinite scope" and "dynamic
extent".  "Scope" refers to _where_ textually in the source code the
binding can be accessed.  "Indefinite scope" means that any part of the
program can potentially access the variable binding.  "Extent" refers
to _when_, as the program is executing, the binding exists.  "Dynamic
extent" means that the binding lasts as long as the activation of the
construct that established it.

   The combination of dynamic extent and indefinite scope is called
"dynamic scoping".  By contrast, most programming languages use
"lexical scoping", in which references to a local variable must be
located textually within the function or block that binds the variable.

     Common Lisp note: Variables declared "special" in Common Lisp are
     dynamically scoped, like all variables in Emacs Lisp.

* Menu:

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

File: elisp,  Node: Scope,  Next: Extent,  Up: Variable Scoping

11.9.1 Scope
------------

Emacs Lisp uses "indefinite scope" for local variable bindings.  This
means that any function anywhere in the program text might access a
given binding of a variable.  Consider the following function
definitions:

     (defun binder (x)   ; `x' is bound in `binder'.
        (foo 5))         ; `foo' is some other function.

     (defun user ()      ; `x' is used "free" in `user'.
       (list x))

   In a lexically scoped language, the binding of `x' in `binder' would
never be accessible in `user', because `user' is not textually
contained within the function `binder'.  However, in dynamically-scoped
Emacs Lisp, `user' may or may not refer to the binding of `x'
established in `binder', depending on the circumstances:

   * If we call `user' directly without calling `binder' at all, then
     whatever binding of `x' is found, it cannot come from `binder'.

   * If we define `foo' as follows and then call `binder', then the
     binding made in `binder' will be seen in `user':

          (defun foo (lose)
            (user))

   * However, if we define `foo' as follows and then call `binder',
     then the binding made in `binder' _will not_ be seen in `user':

          (defun foo (x)
            (user))

     Here, when `foo' is called by `binder', it binds `x'.  (The
     binding in `foo' is said to "shadow" the one made in `binder'.)
     Therefore, `user' will access the `x' bound by `foo' instead of
     the one bound by `binder'.

   Emacs Lisp uses dynamic scoping because simple implementations of
lexical scoping are slow.  In addition, every Lisp system needs to offer
dynamic scoping at least as an option; if lexical scoping is the norm,
there must be a way to specify dynamic scoping instead for a particular
variable.  It might not be a bad thing for Emacs to offer both, but
implementing it with dynamic scoping only was much easier.

File: elisp,  Node: Extent,  Next: Impl of Scope,  Prev: Scope,  Up: Variable Scoping

11.9.2 Extent
-------------

"Extent" refers to the time during program execution that a variable
name is valid.  In Emacs Lisp, a variable is valid only while the form
that bound it is executing.  This is called "dynamic extent".  "Local"
or "automatic" variables in most languages, including C and Pascal,
have dynamic extent.

   One alternative to dynamic extent is "indefinite extent".  This
means that a variable binding can live on past the exit from the form
that made the binding.  Common Lisp and Scheme, for example, support
this, but Emacs Lisp does not.

   To illustrate this, the function below, `make-add', returns a
function that purports to add N to its own argument M.  This would work
in Common Lisp, but it does not do the job in Emacs Lisp, because after
the call to `make-add' exits, the variable `n' is no longer bound to
the actual argument 2.

     (defun make-add (n)
         (function (lambda (m) (+ n m))))  ; Return a function.
          => make-add
     (fset 'add2 (make-add 2))  ; Define function `add2'
                                ;   with `(make-add 2)'.
          => (lambda (m) (+ n m))
     (add2 4)                   ; Try to add 2 to 4.
     error--> Symbol's value as variable is void: n

   Some Lisp dialects have "closures," objects that are like functions
but record additional variable bindings.  Emacs Lisp does not have
closures.

File: elisp,  Node: Impl of Scope,  Next: Using Scoping,  Prev: Extent,  Up: Variable Scoping

11.9.3 Implementation of Dynamic Scoping
----------------------------------------

A simple sample implementation (which is not how Emacs Lisp actually
works) may help you understand dynamic binding.  This technique is
called "deep binding" and was used in early Lisp systems.

   Suppose there is a stack of bindings, which are variable-value pairs.
At entry to a function or to a `let' form, we can push bindings onto
the stack for the arguments or local variables created there.  We can
pop those bindings from the stack at exit from the binding construct.

   We can find the value of a variable by searching the stack from top
to bottom for a binding for that variable; the value from that binding
is the value of the variable.  To set the variable, we search for the
current binding, then store the new value into that binding.

   As you can see, a function's bindings remain in effect as long as it
continues execution, even during its calls to other functions.  That is
why we say the extent of the binding is dynamic.  And any other function
can refer to the bindings, if it uses the same variables while the
bindings are in effect.  That is why we say the scope is indefinite.

   The actual implementation of variable scoping in GNU Emacs Lisp uses
a technique called "shallow binding".  Each variable has a standard
place in which its current value is always found--the value cell of the
symbol.

   In shallow binding, setting the variable works by storing a value in
the value cell.  Creating a new binding works by pushing the old value
(belonging to a previous binding) onto a stack, and storing the new
local value in the value cell.  Eliminating a binding works by popping
the old value off the stack, into the value cell.

   We use shallow binding because it has the same results as deep
binding, but runs faster, since there is never a need to search for a
binding.

File: elisp,  Node: Using Scoping,  Prev: Impl of Scope,  Up: Variable Scoping

11.9.4 Proper Use of Dynamic Scoping
------------------------------------

Binding a variable in one function and using it in another is a
powerful technique, but if used without restraint, it can make programs
hard to understand.  There are two clean ways to use this technique:

   * Use or bind the variable only in a few related functions, written
     close together in one file.  Such a variable is used for
     communication within one program.

     You should write comments to inform other programmers that they
     can see all uses of the variable before them, and to advise them
     not to add uses elsewhere.

   * Give the variable a well-defined, documented meaning, and make all
     appropriate functions refer to it (but not bind it or set it)
     wherever that meaning is relevant.  For example, the variable
     `case-fold-search' is defined as "non-`nil' means ignore case when
     searching"; various search and replace functions refer to it
     directly or through their subroutines, but do not bind or set it.

     Then you can bind the variable in other programs, knowing reliably
     what the effect will be.

   In either case, you should define the variable with `defvar'.  This
helps other people understand your program by telling them to look for
inter-function usage.  It also avoids a warning from the byte compiler.
Choose the variable's name to avoid name conflicts--don't use short
names like `x'.

File: elisp,  Node: Buffer-Local Variables,  Next: File Local Variables,  Prev: Variable Scoping,  Up: Variables

11.10 Buffer-Local Variables
============================

Global and local variable bindings are found in most programming
languages in one form or another.  Emacs, however, also supports
additional, unusual kinds of variable binding, such as "buffer-local"
bindings, which apply only in one buffer.  Having different values for
a variable in different buffers is an important customization method.
(Variables can also have bindings that are local to each terminal, or
to each frame.  *Note Multiple Terminals::, and *Note Frame-Local
Variables::.)

* Menu:

* 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 buffer-local values.

File: elisp,  Node: Intro to Buffer-Local,  Next: Creating Buffer-Local,  Up: Buffer-Local Variables

11.10.1 Introduction to Buffer-Local Variables
----------------------------------------------

A buffer-local variable has a buffer-local binding associated with a
particular buffer.  The binding is in effect when that buffer is
current; otherwise, it is not in effect.  If you set the variable while
a buffer-local binding is in effect, the new value goes in that binding,
so its other bindings are unchanged.  This means that the change is
visible only in the buffer where you made it.

   The variable's ordinary binding, which is not associated with any
specific buffer, is called the "default binding".  In most cases, this
is the global binding.

   A variable can have buffer-local bindings in some buffers but not in
other buffers.  The default binding is shared by all the buffers that
don't have their own bindings for the variable.  (This includes all
newly-created buffers.)  If you set the variable in a buffer that does
not have a buffer-local binding for it, this sets the default binding,
so the new value is visible in all the buffers that see the default
binding.

   The most common use of buffer-local bindings is for major modes to
change variables that control the behavior of commands.  For example, C
mode and Lisp mode both set the variable `paragraph-start' to specify
that only blank lines separate paragraphs.  They do this by making the
variable buffer-local in the buffer that is being put into C mode or
Lisp mode, and then setting it to the new value for that mode.  *Note
Major Modes::.

   The usual way to make a buffer-local binding is with
`make-local-variable', which is what major mode commands typically use.
This affects just the current buffer; all other buffers (including
those yet to be created) will continue to share the default value unless
they are explicitly given their own buffer-local bindings.

   A more powerful operation is to mark the variable as "automatically
buffer-local" by calling `make-variable-buffer-local'.  You can think
of this as making the variable local in all buffers, even those yet to
be created.  More precisely, the effect is that setting the variable
automatically makes the variable local to the current buffer if it is
not already so.  All buffers start out by sharing the default value of
the variable as usual, but setting the variable creates a buffer-local
binding for the current buffer.  The new value is stored in the
buffer-local binding, leaving the default binding untouched.  This
means that the default value cannot be changed with `setq' in any
buffer; the only way to change it is with `setq-default'.

   *Warning:* When a variable has buffer-local bindings in one or more
buffers, `let' rebinds the binding that's currently in effect.  For
instance, if the current buffer has a buffer-local value, `let'
temporarily rebinds that.  If no buffer-local bindings are in effect,
`let' rebinds the default value.  If inside the `let' you then change
to a different current buffer in which a different binding is in effect,
you won't see the `let' binding any more.  And if you exit the `let'
while still in the other buffer, you won't see the unbinding occur
(though it will occur properly).  Here is an example to illustrate:

     (setq foo 'g)
     (set-buffer "a")
     (make-local-variable 'foo)
     (setq foo 'a)
     (let ((foo 'temp))
       ;; foo => 'temp  ; let binding in buffer `a'
       (set-buffer "b")
       ;; foo => 'g     ; the global value since foo is not local in `b'
       BODY...)
     foo => 'g        ; exiting restored the local value in buffer `a',
                      ; but we don't see that in buffer `b'
     (set-buffer "a") ; verify the local value was restored
     foo => 'a

   Note that references to `foo' in BODY access the buffer-local
binding of buffer `b'.

   When a file specifies local variable values, these become
buffer-local values when you visit the file.  *Note File Variables:
(emacs)File Variables.

   A buffer-local variable cannot be made frame-local (*note
Frame-Local Variables::) or terminal-local (*note Multiple Terminals::).

File: elisp,  Node: Creating Buffer-Local,  Next: Default Value,  Prev: Intro to Buffer-Local,  Up: Buffer-Local Variables

11.10.2 Creating and Deleting Buffer-Local Bindings
---------------------------------------------------

 -- Command: make-local-variable variable
     This function creates a buffer-local binding in the current buffer
     for VARIABLE (a symbol).  Other buffers are not affected.  The
     value returned is VARIABLE.

     The buffer-local value of VARIABLE starts out as the same value
     VARIABLE previously had.  If VARIABLE was void, it remains void.

          ;; In buffer `b1':
          (setq foo 5)                ; Affects all buffers.
               => 5
          (make-local-variable 'foo)  ; Now it is local in `b1'.
               => foo
          foo                         ; That did not change
               => 5                   ;   the value.
          (setq foo 6)                ; Change the value
               => 6                   ;   in `b1'.
          foo
               => 6

          ;; In buffer `b2', the value hasn't changed.
          (save-excursion
            (set-buffer "b2")
            foo)
               => 5

     Making a variable buffer-local within a `let'-binding for that
     variable does not work reliably, unless the buffer in which you do
     this is not current either on entry to or exit from the `let'.
     This is because `let' does not distinguish between different kinds
     of bindings; it knows only which variable the binding was made for.

     If the variable is terminal-local (*note Multiple Terminals::), or
     frame-local (*note Frame-Local Variables::), this function signals
     an error.  Such variables cannot have buffer-local bindings as
     well.

     *Warning:* do not use `make-local-variable' for a hook variable.
     The hook variables are automatically made buffer-local as needed
     if you use the LOCAL argument to `add-hook' or `remove-hook'.

 -- Command: make-variable-buffer-local variable
     This function marks VARIABLE (a symbol) automatically
     buffer-local, so that any subsequent attempt to set it will make it
     local to the current buffer at the time.

     A peculiar wrinkle of this feature is that binding the variable
     (with `let' or other binding constructs) does not create a
     buffer-local binding for it.  Only setting the variable (with
     `set' or `setq'), while the variable does not have a `let'-style
     binding that was made in the current buffer, does so.

     If VARIABLE does not have a default value, then calling this
     command will give it a default value of `nil'.  If VARIABLE
     already has a default value, that value remains unchanged.
     Subsequently calling `makunbound' on VARIABLE will result in a
     void buffer-local value and leave the default value unaffected.

     The value returned is VARIABLE.

     *Warning:* Don't assume that you should use
     `make-variable-buffer-local' for user-option variables, simply
     because users _might_ want to customize them differently in
     different buffers.  Users can make any variable local, when they
     wish to.  It is better to leave the choice to them.

     The time to use `make-variable-buffer-local' is when it is crucial
     that no two buffers ever share the same binding.  For example,
     when a variable is used for internal purposes in a Lisp program
     which depends on having separate values in separate buffers, then
     using `make-variable-buffer-local' can be the best solution.

 -- Function: local-variable-p variable &optional buffer
     This returns `t' if VARIABLE is buffer-local in buffer BUFFER
     (which defaults to the current buffer); otherwise, `nil'.

 -- Function: local-variable-if-set-p variable &optional buffer
     This returns `t' if VARIABLE will become buffer-local in buffer
     BUFFER (which defaults to the current buffer) if it is set there.

 -- Function: buffer-local-value variable buffer
     This function returns the buffer-local binding of VARIABLE (a
     symbol) in buffer BUFFER.  If VARIABLE does not have a
     buffer-local binding in buffer BUFFER, it returns the default
     value (*note Default Value::) of VARIABLE instead.

 -- Function: buffer-local-variables &optional buffer
     This function returns a list describing the buffer-local variables
     in buffer BUFFER.  (If BUFFER is omitted, the current buffer is
     used.)  It returns an association list (*note Association Lists::)
     in which each element contains one buffer-local variable and its
     value.  However, when a variable's buffer-local binding in BUFFER
     is void, then the variable appears directly in the resulting list.

          (make-local-variable 'foobar)
          (makunbound 'foobar)
          (make-local-variable 'bind-me)
          (setq bind-me 69)
          (setq lcl (buffer-local-variables))
              ;; First, built-in variables local in all buffers:
          => ((mark-active . nil)
              (buffer-undo-list . nil)
              (mode-name . "Fundamental")
              ...
              ;; Next, non-built-in buffer-local variables.
              ;; This one is buffer-local and void:
              foobar
              ;; This one is buffer-local and nonvoid:
              (bind-me . 69))

     Note that storing new values into the CDRs of cons cells in this
     list does _not_ change the buffer-local values of the variables.

 -- Command: kill-local-variable variable
     This function deletes the buffer-local binding (if any) for
     VARIABLE (a symbol) in the current buffer.  As a result, the
     default binding of VARIABLE becomes visible in this buffer.  This
     typically results in a change in the value of VARIABLE, since the
     default value is usually different from the buffer-local value just
     eliminated.

     If you kill the buffer-local binding of a variable that
     automatically becomes buffer-local when set, this makes the
     default value visible in the current buffer.  However, if you set
     the variable again, that will once again create a buffer-local
     binding for it.

     `kill-local-variable' returns VARIABLE.

     This function is a command because it is sometimes useful to kill
     one buffer-local variable interactively, just as it is useful to
     create buffer-local variables interactively.

 -- Function: kill-all-local-variables
     This function eliminates all the buffer-local variable bindings of
     the current buffer except for variables marked as "permanent" and
     local hook functions that have a non-`nil' `permanent-local-hook'
     property (*note Setting Hooks::).  As a result, the buffer will see
     the default values of most variables.

     This function also resets certain other information pertaining to
     the buffer: it sets the local keymap to `nil', the syntax table to
     the value of `(standard-syntax-table)', the case table to
     `(standard-case-table)', and the abbrev table to the value of
     `fundamental-mode-abbrev-table'.

     The very first thing this function does is run the normal hook
     `change-major-mode-hook' (see below).

     Every major mode command begins by calling this function, which
     has the effect of switching to Fundamental mode and erasing most
     of the effects of the previous major mode.  To ensure that this
     does its job, the variables that major modes set should not be
     marked permanent.

     `kill-all-local-variables' returns `nil'.

 -- Variable: change-major-mode-hook
     The function `kill-all-local-variables' runs this normal hook
     before it does anything else.  This gives major modes a way to
     arrange for something special to be done if the user switches to a
     different major mode.  It is also useful for buffer-specific minor
     modes that should be forgotten if the user changes the major mode.

     For best results, make this variable buffer-local, so that it will
     disappear after doing its job and will not interfere with the
     subsequent major mode.  *Note Hooks::.

   A buffer-local variable is "permanent" if the variable name (a
symbol) has a `permanent-local' property that is non-`nil'.  Permanent
locals are appropriate for data pertaining to where the file came from
or how to save it, rather than with how to edit the contents.

File: elisp,  Node: Default Value,  Prev: Creating Buffer-Local,  Up: Buffer-Local Variables

11.10.3 The Default Value of a Buffer-Local Variable
----------------------------------------------------

The global value of a variable with buffer-local bindings is also
called the "default" value, because it is the value that is in effect
whenever neither the current buffer nor the selected frame has its own
binding for the variable.

   The functions `default-value' and `setq-default' access and change a
variable's default value regardless of whether the current buffer has a
buffer-local binding.  For example, you could use `setq-default' to
change the default setting of `paragraph-start' for most buffers; and
this would work even when you are in a C or Lisp mode buffer that has a
buffer-local value for this variable.

   The special forms `defvar' and `defconst' also set the default value
(if they set the variable at all), rather than any buffer-local value.

 -- Function: default-value symbol
     This function returns SYMBOL's default value.  This is the value
     that is seen in buffers and frames that do not have their own
     values for this variable.  If SYMBOL is not buffer-local, this is
     equivalent to `symbol-value' (*note Accessing Variables::).

 -- Function: default-boundp symbol
     The function `default-boundp' tells you whether SYMBOL's default
     value is nonvoid.  If `(default-boundp 'foo)' returns `nil', then
     `(default-value 'foo)' would get an error.

     `default-boundp' is to `default-value' as `boundp' is to
     `symbol-value'.

 -- Special Form: setq-default [symbol form]...
     This special form gives each SYMBOL a new default value, which is
     the result of evaluating the corresponding FORM.  It does not
     evaluate SYMBOL, but does evaluate FORM.  The value of the
     `setq-default' form is the value of the last FORM.

     If a SYMBOL is not buffer-local for the current buffer, and is not
     marked automatically buffer-local, `setq-default' has the same
     effect as `setq'.  If SYMBOL is buffer-local for the current
     buffer, then this changes the value that other buffers will see
     (as long as they don't have a buffer-local value), but not the
     value that the current buffer sees.

          ;; In buffer `foo':
          (make-local-variable 'buffer-local)
               => buffer-local
          (setq buffer-local 'value-in-foo)
               => value-in-foo
          (setq-default buffer-local 'new-default)
               => new-default
          buffer-local
               => value-in-foo
          (default-value 'buffer-local)
               => new-default

          ;; In (the new) buffer `bar':
          buffer-local
               => new-default
          (default-value 'buffer-local)
               => new-default
          (setq buffer-local 'another-default)
               => another-default
          (default-value 'buffer-local)
               => another-default

          ;; Back in buffer `foo':
          buffer-local
               => value-in-foo
          (default-value 'buffer-local)
               => another-default

 -- Function: set-default symbol value
     This function is like `setq-default', except that SYMBOL is an
     ordinary evaluated argument.

          (set-default (car '(a b c)) 23)
               => 23
          (default-value 'a)
               => 23

File: elisp,  Node: File Local Variables,  Next: Directory Local Variables,  Prev: Buffer-Local Variables,  Up: Variables

11.11 File Local Variables
==========================

A file can specify local variable values; Emacs uses these to create
buffer-local bindings for those variables in the buffer visiting that
file.  *Note Local Variables in Files: (emacs)File variables, for basic
information about file-local variables.  This section describes the
functions and variables that affect how file-local variables are
processed.

   If a file-local variable could specify an arbitrary function or Lisp
expression that would be called later, visiting a file could take over
your Emacs.  Emacs protects against this by automatically setting only
those file-local variables whose specified values are known to be safe.
Other file-local variables are set only if the user agrees.

   For additional safety, `read-circle' is temporarily bound to `nil'
when Emacs reads file-local variables (*note Input Functions::).  This
prevents the Lisp reader from recognizing circular and shared Lisp
structures (*note Circular Objects::).

 -- User Option: enable-local-variables
     This variable controls whether to process file-local variables.
     The possible values are:

    `t' (the default)
          Set the safe variables, and query (once) about any unsafe
          variables.

    `:safe'
          Set only the safe variables and do not query.

    `:all'
          Set all the variables and do not query.

    `nil'
          Don't set any variables.

    anything else
          Query (once) about all the variables.

 -- Function: hack-local-variables &optional mode-only
     This function parses, and binds or evaluates as appropriate, any
     local variables specified by the contents of the current buffer.
     The variable `enable-local-variables' has its effect here.
     However, this function does not look for the `mode:' local
     variable in the `-*-' line.  `set-auto-mode' does that, also taking
     `enable-local-variables' into account (*note Auto Major Mode::).

     This function works by walking the alist stored in
     `file-local-variables-alist' and applying each local variable in
     turn.  It calls `before-hack-local-variables-hook' and
     `hack-local-variables-hook' before and after applying the
     variables, respectively.

     If the optional argument MODE-ONLY is non-`nil', then all this
     function does is return `t' if the `-*-' line or the local
     variables list specifies a mode and `nil' otherwise.  It does not
     set the mode nor any other file-local variable.

 -- Variable: file-local-variables-alist
     This buffer-local variable holds the alist of file-local variable
     settings.  Each element of the alist is of the form
     `(VAR . VALUE)', where VAR is a symbol of the local variable and
     VALUE is its value.  When Emacs visits a file, it first collects
     all the file-local variables into this alist, and then the
     `hack-local-variables' function applies them one by one.

 -- Variable: before-hack-local-variables-hook
     Emacs calls this hook immediately before applying file-local
     variables stored in `file-local-variables-alist'.

 -- Variable: hack-local-variables-hook
     Emacs calls this hook immediately after it finishes applying
     file-local variables stored in `file-local-variables-alist'.

   You can specify safe values for a variable with a
`safe-local-variable' property.  The property has to be a function of
one argument; any value is safe if the function returns non-`nil' given
that value.  Many commonly-encountered file variables have
`safe-local-variable' properties; these include `fill-column',
`fill-prefix', and `indent-tabs-mode'.  For boolean-valued variables
that are safe, use `booleanp' as the property value.  Lambda
expressions should be quoted so that `describe-variable' can display
the predicate.

 -- User Option: safe-local-variable-values
     This variable provides another way to mark some variable values as
     safe.  It is a list of cons cells `(VAR . VAL)', where VAR is a
     variable name and VAL is a value which is safe for that variable.

     When Emacs asks the user whether or not to obey a set of file-local
     variable specifications, the user can choose to mark them as safe.
     Doing so adds those variable/value pairs to
     `safe-local-variable-values', and saves it to the user's custom
     file.

 -- Function: safe-local-variable-p sym val
     This function returns non-`nil' if it is safe to give SYM the
     value VAL, based on the above criteria.

   Some variables are considered "risky".  A variable whose name ends
in any of `-command', `-frame-alist', `-function', `-functions',
`-hook', `-hooks', `-form', `-forms', `-map', `-map-alist',
`-mode-alist', `-program', or `-predicate' is considered risky.  The
variables `font-lock-keywords', `font-lock-keywords' followed by a
digit, and `font-lock-syntactic-keywords' are also considered risky.
Finally, any variable whose name has a non-`nil' `risky-local-variable'
property is considered risky.

 -- Function: risky-local-variable-p sym
     This function returns non-`nil' if SYM is a risky variable, based
     on the above criteria.

   If a variable is risky, it will not be entered automatically into
`safe-local-variable-values' as described above.  Therefore, Emacs will
always query before setting a risky variable, unless the user
explicitly allows the setting by customizing
`safe-local-variable-values' directly.

 -- Variable: ignored-local-variables
     This variable holds a list of variables that should not be given
     local values by files.  Any value specified for one of these
     variables is completely ignored.

   The `Eval:' "variable" is also a potential loophole, so Emacs
normally asks for confirmation before handling it.

 -- User Option: enable-local-eval
     This variable controls processing of `Eval:' in `-*-' lines or
     local variables lists in files being visited.  A value of `t'
     means process them unconditionally; `nil' means ignore them;
     anything else means ask the user what to do for each file.  The
     default value is `maybe'.

 -- User Option: safe-local-eval-forms
     This variable holds a list of expressions that are safe to
     evaluate when found in the `Eval:' "variable" in a file local
     variables list.

   If the expression is a function call and the function has a
`safe-local-eval-function' property, the property value determines
whether the expression is safe to evaluate.  The property value can be
a predicate to call to test the expression, a list of such predicates
(it's safe if any predicate succeeds), or `t' (always safe provided the
arguments are constant).

   Text properties are also potential loopholes, since their values
could include functions to call.  So Emacs discards all text properties
from string values specified for file-local variables.

File: elisp,  Node: Directory Local Variables,  Next: Frame-Local Variables,  Prev: File Local Variables,  Up: Variables

11.12 Directory Local Variables
===============================

A directory can specify local variable values common to all files in
that directory; Emacs uses these to create buffer-local bindings for
those variables in buffers visiting any file in that directory.  This
is useful when the files in the directory belong to some "project" and
therefore share the same local variables.

   There are two different methods for specifying directory local
variables: by putting them in a special file, or by defining a "project
class" for that directory.

 -- Constant: dir-locals-file
     This constant is the name of the file where Emacs expects to find
     the directory-local variables.  The name of the file is
     `.dir-locals.el'(1).  A file by that name in a directory causes
     Emacs to apply its settings to any file in that directory or any
     of its subdirectories.  If some of the subdirectories have their
     own `.dir-locals.el' files, Emacs uses the settings from the
     deepest file it finds starting from the file's directory and
     moving up the directory tree.  The file specifies local variables
     as a specially formatted list; see *note Per-directory Local
     Variables: (emacs)Directory Variables, for more details.

 -- Function: hack-dir-local-variables
     This function reads the `.dir-locals.el' file and stores the
     directory-local variables in `file-local-variables-alist' that is
     local to the buffer visiting any file in the directory, without
     applying them.  It also stores the directory-local settings in
     `dir-locals-class-alist', where it defines a special class for the
     directory in which `.dir-locals.el' file was found.  This function
     works by calling `dir-locals-set-class-variables' and
     `dir-locals-set-directory-class', described below.

 -- Function: dir-locals-set-class-variables class variables
     This function defines a set of variable settings for the named
     CLASS, which is a symbol.  You can later assign the class to one
     or more directories, and Emacs will apply those variable settings
     to all files in those directories.  The list in VARIABLES can be of
     one of the two forms: `(MAJOR-MODE . ALIST)' or `(DIRECTORY .
     LIST)'.  With the first form, if the file's buffer turns on a mode
     that is derived from MAJOR-MODE, then the all the variables in the
     associated ALIST are applied; ALIST should be of the form `(NAME .
     VALUE)'.  A special value `nil' for MAJOR-MODE means the settings
     are applicable to any mode.

     With the second form of VARIABLES, if DIRECTORY is the initial
     substring of the file's directory, then LIST is applied
     recursively by following the above rules; LIST should be of one of
     the two forms accepted by this function in VARIABLES.

 -- Function: dir-locals-set-directory-class directory class
     This function assigns CLASS to all the files in `directory' and
     its subdirectories.  Thereafter, all the variable settings
     specified for CLASS will be applied to any visited file in
     DIRECTORY and its children.  CLASS must have been already defined
     by `dir-locals-set-class-variables'

 -- Variable: dir-locals-class-alist
     This alist holds the class symbols and the associated variable
     settings.  It is updated by `dir-locals-set-class-variables'.

 -- Variable: dir-locals-directory-cache
     This alist holds directory names, their assigned class names, and
     modification times of the associated directory local variables
     file.  It is updated by `dir-locals-set-directory-class'.

   ---------- Footnotes ----------

   (1) The MS-DOS version of Emacs uses `_dir-locals.el' instead, due to
limitations of the DOS filesystems.

File: elisp,  Node: Frame-Local Variables,  Next: Variable Aliases,  Prev: Directory Local Variables,  Up: Variables

11.13 Frame-Local Values for Variables
======================================

In addition to buffer-local variable bindings (*note Buffer-Local
Variables::), Emacs supports "frame-local" bindings.  A frame-local
binding for a variable is in effect in a frame for which it was defined.

   In practice, frame-local variables have not proven very useful.
Ordinary frame parameters are generally used instead (*note Frame
Parameters::).  The function `make-variable-frame-local', which was
used to define frame-local variables, has been deprecated since Emacs
22.2.  However, you can still define a frame-specific binding for a
variable VAR in frame FRAME, by setting the VAR frame parameter for
that frame:

       (modify-frame-parameters FRAME '((VAR . VALUE)))

This causes the variable VAR to be bound to the specified VALUE in the
named FRAME.  To check the frame-specific values of such variables, use
`frame-parameter'.  *Note Parameter Access::.

   Note that you cannot have a frame-local binding for a variable that
has a buffer-local binding.

File: elisp,  Node: Variable Aliases,  Next: Variables with Restricted Values,  Prev: Frame-Local Variables,  Up: Variables

11.14 Variable Aliases
======================

It is sometimes useful to make two variables synonyms, so that both
variables always have the same value, and changing either one also
changes the other.  Whenever you change the name of a variable--either
because you realize its old name was not well chosen, or because its
meaning has partly changed--it can be useful to keep the old name as an
_alias_ of the new one for compatibility.  You can do this with
`defvaralias'.

 -- Function: defvaralias new-alias base-variable &optional docstring
     This function defines the symbol NEW-ALIAS as a variable alias for
     symbol BASE-VARIABLE. This means that retrieving the value of
     NEW-ALIAS returns the value of BASE-VARIABLE, and changing the
     value of NEW-ALIAS changes the value of BASE-VARIABLE.  The two
     aliased variable names always share the same value and the same
     bindings.

     If the DOCSTRING argument is non-`nil', it specifies the
     documentation for NEW-ALIAS; otherwise, the alias gets the same
     documentation as BASE-VARIABLE has, if any, unless BASE-VARIABLE
     is itself an alias, in which case NEW-ALIAS gets the documentation
     of the variable at the end of the chain of aliases.

     This function returns BASE-VARIABLE.

   Variable aliases are convenient for replacing an old name for a
variable with a new name.  `make-obsolete-variable' declares that the
old name is obsolete and therefore that it may be removed at some stage
in the future.

 -- Function: make-obsolete-variable obsolete-name current-name
          &optional when
     This function makes the byte compiler warn that the variable
     OBSOLETE-NAME is obsolete.  If CURRENT-NAME is a symbol, it is the
     variable's new name; then the warning message says to use
     CURRENT-NAME instead of OBSOLETE-NAME.  If CURRENT-NAME is a
     string, this is the message and there is no replacement variable.

     If provided, WHEN should be a string indicating when the variable
     was first made obsolete--for example, a date or a release number.

   You can make two variables synonyms and declare one obsolete at the
same time using the macro `define-obsolete-variable-alias'.

 -- Macro: define-obsolete-variable-alias obsolete-name current-name
          &optional when docstring
     This macro marks the variable OBSOLETE-NAME as obsolete and also
     makes it an alias for the variable CURRENT-NAME.  It is equivalent
     to the following:

          (defvaralias OBSOLETE-NAME CURRENT-NAME DOCSTRING)
          (make-obsolete-variable OBSOLETE-NAME CURRENT-NAME WHEN)

 -- Function: indirect-variable variable
     This function returns the variable at the end of the chain of
     aliases of VARIABLE.  If VARIABLE is not a symbol, or if VARIABLE
     is not defined as an alias, the function returns VARIABLE.

     This function signals a `cyclic-variable-indirection' error if
     there is a loop in the chain of symbols.

     (defvaralias 'foo 'bar)
     (indirect-variable 'foo)
          => bar
     (indirect-variable 'bar)
          => bar
     (setq bar 2)
     bar
          => 2
     foo
          => 2
     (setq foo 0)
     bar
          => 0
     foo
          => 0

File: elisp,  Node: Variables with Restricted Values,  Prev: Variable Aliases,  Up: Variables

11.15 Variables with Restricted Values
======================================

Ordinary Lisp variables can be assigned any value that is a valid Lisp
object.  However, certain Lisp variables are not defined in Lisp, but
in C.  Most of these variables are defined in the C code using
`DEFVAR_LISP'.  Like variables defined in Lisp, these can take on any
value.  However, some variables are defined using `DEFVAR_INT' or
`DEFVAR_BOOL'.  *Note Writing Emacs Primitives: Defining Lisp variables
in C, in particular the description of functions of the type
`syms_of_FILENAME', for a brief discussion of the C implementation.

   Variables of type `DEFVAR_BOOL' can only take on the values `nil' or
`t'.  Attempting to assign them any other value will set them to `t':

     (let ((display-hourglass 5))
       display-hourglass)
          => t

 -- Variable: byte-boolean-vars
     This variable holds a list of all variables of type `DEFVAR_BOOL'.

   Variables of type `DEFVAR_INT' can only take on integer values.
Attempting to assign them any other value will result in an error:

     (setq window-min-height 5.0)
     error--> Wrong type argument: integerp, 5.0

File: elisp,  Node: Functions,  Next: Macros,  Prev: Variables,  Up: Top

12 Functions
************

A Lisp program is composed mainly of Lisp functions.  This chapter
explains what functions are, how they accept arguments, and how to
define them.

* Menu:

* 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.
* Obsolete Functions::    Declaring functions obsolete.
* Inline Functions::	  Defining functions that the compiler will open code.
* Declaring Functions::   Telling the compiler that a function is defined.
* Function Safety::       Determining whether a function is safe to call.
* Related Topics::        Cross-references to specific Lisp primitives
                            that have a special bearing on how functions work.

File: elisp,  Node: What Is a Function,  Next: Lambda Expressions,  Up: Functions

12.1 What Is a Function?
========================

In a general sense, a function is a rule for carrying on a computation
given several values called "arguments".  The result of the computation
is called the value of the function.  The computation can also have
side effects: lasting changes in the values of variables or the
contents of data structures.

   Here are important terms for functions in Emacs Lisp and for other
function-like objects.

"function"
     In Emacs Lisp, a "function" is anything that can be applied to
     arguments in a Lisp program.  In some cases, we use it more
     specifically to mean a function written in Lisp.  Special forms and
     macros are not functions.

"primitive"
     A "primitive" is a function callable from Lisp that is written in
     C, such as `car' or `append'.  These functions are also called
     "built-in functions", or "subrs".  (Special forms are also
     considered primitives.)

     Usually the reason we implement a function as a primitive is either
     because it is fundamental, because it provides a low-level
     interface to operating system services, or because it needs to run
     fast.  Primitives can be modified or added only by changing the C
     sources and recompiling the editor.  See *note Writing Emacs
     Primitives::.

"lambda expression"
     A "lambda expression" is a function written in Lisp.  These are
     described in the following section.  *Note Lambda Expressions::.

"special form"
     A "special form" is a primitive that is like a function but does
     not evaluate all of its arguments in the usual way.  It may
     evaluate only some of the arguments, or may evaluate them in an
     unusual order, or several times.  Many special forms are described
     in *note Control Structures::.

"macro"
     A "macro" is a construct defined in Lisp by the programmer.  It
     differs from a function in that it translates a Lisp expression
     that you write into an equivalent expression to be evaluated
     instead of the original expression.  Macros enable Lisp
     programmers to do the sorts of things that special forms can do.
     *Note Macros::, for how to define and use macros.

"command"
     A "command" is an object that `command-execute' can invoke; it is
     a possible definition for a key sequence.  Some functions are
     commands; a function written in Lisp is a command if it contains an
     interactive declaration (*note Defining Commands::).  Such a
     function can be called from Lisp expressions like other functions;
     in this case, the fact that the function is a command makes no
     difference.

     Keyboard macros (strings and vectors) are commands also, even
     though they are not functions.  A symbol is a command if its
     function definition is a command; such symbols can be invoked with
     `M-x'.  The symbol is a function as well if the definition is a
     function.  *Note Interactive Call::.

"keystroke command"
     A "keystroke command" is a command that is bound to a key sequence
     (typically one to three keystrokes).  The distinction is made here
     merely to avoid confusion with the meaning of "command" in
     non-Emacs editors; for Lisp programs, the distinction is normally
     unimportant.

"byte-code function"
     A "byte-code function" is a function that has been compiled by the
     byte compiler.  *Note Byte-Code Type::.

 -- Function: functionp object
     This function returns `t' if OBJECT is any kind of function, i.e.
     can be passed to `funcall'.  Note that `functionp' returns `nil'
     for special forms (*note Special Forms::).

   Unlike `functionp', the next three functions do _not_ treat a symbol
as its function definition.

 -- Function: subrp object
     This function returns `t' if OBJECT is a built-in function (i.e.,
     a Lisp primitive).

          (subrp 'message)            ; `message' is a symbol,
               => nil                 ;   not a subr object.
          (subrp (symbol-function 'message))
               => t

 -- Function: byte-code-function-p object
     This function returns `t' if OBJECT is a byte-code function.  For
     example:

          (byte-code-function-p (symbol-function 'next-line))
               => t

 -- Function: subr-arity subr
     This function provides information about the argument list of a
     primitive, SUBR.  The returned value is a pair `(MIN . MAX)'.  MIN
     is the minimum number of args.  MAX is the maximum number or the
     symbol `many', for a function with `&rest' arguments, or the
     symbol `unevalled' if SUBR is a special form.

File: elisp,  Node: Lambda Expressions,  Next: Function Names,  Prev: What Is a Function,  Up: Functions

12.2 Lambda Expressions
=======================

A function written in Lisp is a list that looks like this:

     (lambda (ARG-VARIABLES...)
       [DOCUMENTATION-STRING]
       [INTERACTIVE-DECLARATION]
       BODY-FORMS...)

Such a list is called a "lambda expression".  In Emacs Lisp, it
actually is valid as an expression--it evaluates to itself.  In some
other Lisp dialects, a lambda expression is not a valid expression at
all.  In either case, its main use is not to be evaluated as an
expression, but to be called as a function.

* Menu:

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

File: elisp,  Node: Lambda Components,  Next: Simple Lambda,  Up: Lambda Expressions

12.2.1 Components of a Lambda Expression
----------------------------------------

A function written in Lisp (a "lambda expression") is a list that looks
like this:

     (lambda (ARG-VARIABLES...)
       [DOCUMENTATION-STRING]
       [INTERACTIVE-DECLARATION]
       BODY-FORMS...)

The first element of a lambda expression is always the symbol `lambda'.
This indicates that the list represents a function.  The reason
functions are defined to start with `lambda' is so that other lists,
intended for other uses, will not accidentally be valid as functions.

   The second element is a list of symbols--the argument variable names.
This is called the "lambda list".  When a Lisp function is called, the
argument values are matched up against the variables in the lambda
list, which are given local bindings with the values provided.  *Note
Local Variables::.

   The documentation string is a Lisp string object placed within the
function definition to describe the function for the Emacs help
facilities.  *Note Function Documentation::.

   The interactive declaration is a list of the form `(interactive
CODE-STRING)'.  This declares how to provide arguments if the function
is used interactively.  Functions with this declaration are called
"commands"; they can be called using `M-x' or bound to a key.
Functions not intended to be called in this way should not have
interactive declarations.  *Note Defining Commands::, for how to write
an interactive declaration.

   The rest of the elements are the "body" of the function: the Lisp
code to do the work of the function (or, as a Lisp programmer would say,
"a list of Lisp forms to evaluate").  The value returned by the
function is the value returned by the last element of the body.

File: elisp,  Node: Simple Lambda,  Next: Argument List,  Prev: Lambda Components,  Up: Lambda Expressions

12.2.2 A Simple Lambda-Expression Example
-----------------------------------------

Consider for example the following function:

     (lambda (a b c) (+ a b c))

We can call this function by writing it as the CAR of an expression,
like this:

     ((lambda (a b c) (+ a b c))
      1 2 3)

This call evaluates the body of the lambda expression  with the variable
`a' bound to 1, `b' bound to 2, and `c' bound to 3.  Evaluation of the
body adds these three numbers, producing the result 6; therefore, this
call to the function returns the value 6.

   Note that the arguments can be the results of other function calls,
as in this example:

     ((lambda (a b c) (+ a b c))
      1 (* 2 3) (- 5 4))

This evaluates the arguments `1', `(* 2 3)', and `(- 5 4)' from left to
right.  Then it applies the lambda expression to the argument values 1,
6 and 1 to produce the value 8.

   It is not often useful to write a lambda expression as the CAR of a
form in this way.  You can get the same result, of making local
variables and giving them values, using the special form `let' (*note
Local Variables::).  And `let' is clearer and easier to use.  In
practice, lambda expressions are either stored as the function
definitions of symbols, to produce named functions, or passed as
arguments to other functions (*note Anonymous Functions::).

   However, calls to explicit lambda expressions were very useful in the
old days of Lisp, before the special form `let' was invented.  At that
time, they were the only way to bind and initialize local variables.

File: elisp,  Node: Argument List,  Next: Function Documentation,  Prev: Simple Lambda,  Up: Lambda Expressions

12.2.3 Other Features of Argument Lists
---------------------------------------

Our simple sample function, `(lambda (a b c) (+ a b c))', specifies
three argument variables, so it must be called with three arguments: if
you try to call it with only two arguments or four arguments, you get a
`wrong-number-of-arguments' error.

   It is often convenient to write a function that allows certain
arguments to be omitted.  For example, the function `substring' accepts
three arguments--a string, the start index and the end index--but the
third argument defaults to the LENGTH of the string if you omit it.  It
is also convenient for certain functions to accept an indefinite number
of arguments, as the functions `list' and `+' do.

   To specify optional arguments that may be omitted when a function is
called, simply include the keyword `&optional' before the optional
arguments.  To specify a list of zero or more extra arguments, include
the keyword `&rest' before one final argument.

   Thus, the complete syntax for an argument list is as follows:

     (REQUIRED-VARS...
      [&optional OPTIONAL-VARS...]
      [&rest REST-VAR])

The square brackets indicate that the `&optional' and `&rest' clauses,
and the variables that follow them, are optional.

   A call to the function requires one actual argument for each of the
REQUIRED-VARS.  There may be actual arguments for zero or more of the
OPTIONAL-VARS, and there cannot be any actual arguments beyond that
unless the lambda list uses `&rest'.  In that case, there may be any
number of extra actual arguments.

   If actual arguments for the optional and rest variables are omitted,
then they always default to `nil'.  There is no way for the function to
distinguish between an explicit argument of `nil' and an omitted
argument.  However, the body of the function is free to consider `nil'
an abbreviation for some other meaningful value.  This is what
`substring' does; `nil' as the third argument to `substring' means to
use the length of the string supplied.

     Common Lisp note: Common Lisp allows the function to specify what
     default value to use when an optional argument is omitted; Emacs
     Lisp always uses `nil'.  Emacs Lisp does not support "supplied-p"
     variables that tell you whether an argument was explicitly passed.

   For example, an argument list that looks like this:

     (a b &optional c d &rest e)

binds `a' and `b' to the first two actual arguments, which are
required.  If one or two more arguments are provided, `c' and `d' are
bound to them respectively; any arguments after the first four are
collected into a list and `e' is bound to that list.  If there are only
two arguments, `c' is `nil'; if two or three arguments, `d' is `nil';
if four arguments or fewer, `e' is `nil'.

   There is no way to have required arguments following optional
ones--it would not make sense.  To see why this must be so, suppose
that `c' in the example were optional and `d' were required.  Suppose
three actual arguments are given; which variable would the third
argument be for?  Would it be used for the C, or for D?  One can argue
for both possibilities.  Similarly, it makes no sense to have any more
arguments (either required or optional) after a `&rest' argument.

   Here are some examples of argument lists and proper calls:

     ((lambda (n) (1+ n))                ; One required:
      1)                                 ; requires exactly one argument.
          => 2
     ((lambda (n &optional n1)           ; One required and one optional:
              (if n1 (+ n n1) (1+ n)))   ; 1 or 2 arguments.
      1 2)
          => 3
     ((lambda (n &rest ns)               ; One required and one rest:
              (+ n (apply '+ ns)))       ; 1 or more arguments.
      1 2 3 4 5)
          => 15

File: elisp,  Node: Function Documentation,  Prev: Argument List,  Up: Lambda Expressions

12.2.4 Documentation Strings of Functions
-----------------------------------------

A lambda expression may optionally have a "documentation string" just
after the lambda list.  This string does not affect execution of the
function; it is a kind of comment, but a systematized comment which
actually appears inside the Lisp world and can be used by the Emacs help
facilities.  *Note Documentation::, for how the DOCUMENTATION-STRING is
accessed.

   It is a good idea to provide documentation strings for all the
functions in your program, even those that are called only from within
your program.  Documentation strings are like comments, except that they
are easier to access.

   The first line of the documentation string should stand on its own,
because `apropos' displays just this first line.  It should consist of
one or two complete sentences that summarize the function's purpose.

   The start of the documentation string is usually indented in the
source file, but since these spaces come before the starting
double-quote, they are not part of the string.  Some people make a
practice of indenting any additional lines of the string so that the
text lines up in the program source.  _That is a mistake._  The
indentation of the following lines is inside the string; what looks
nice in the source code will look ugly when displayed by the help
commands.

   You may wonder how the documentation string could be optional, since
there are required components of the function that follow it (the body).
Since evaluation of a string returns that string, without any side
effects, it has no effect if it is not the last form in the body.
Thus, in practice, there is no confusion between the first form of the
body and the documentation string; if the only body form is a string
then it serves both as the return value and as the documentation.

   The last line of the documentation string can specify calling
conventions different from the actual function arguments.  Write text
like this:

     \(fn ARGLIST)

following a blank line, at the beginning of the line, with no newline
following it inside the documentation string.  (The `\' is used to
avoid confusing the Emacs motion commands.)  The calling convention
specified in this way appears in help messages in place of the one
derived from the actual arguments of the function.

   This feature is particularly useful for macro definitions, since the
arguments written in a macro definition often do not correspond to the
way users think of the parts of the macro call.

File: elisp,  Node: Function Names,  Next: Defining Functions,  Prev: Lambda Expressions,  Up: Functions

12.3 Naming a Function
======================

In most computer languages, every function has a name; the idea of a
function without a name is nonsensical.  In Lisp, a function in the
strictest sense has no name.  It is simply a list whose first element is
`lambda', a byte-code function object, or a primitive subr-object.

   However, a symbol can serve as the name of a function.  This happens
when you put the function in the symbol's "function cell" (*note Symbol
Components::).  Then the symbol itself becomes a valid, callable
function, equivalent to the list or subr-object that its function cell
refers to.  The contents of the function cell are also called the
symbol's "function definition".  The procedure of using a symbol's
function definition in place of the symbol is called "symbol function
indirection"; see *note Function Indirection::.

   In practice, nearly all functions are given names in this way and
referred to through their names.  For example, the symbol `car' works
as a function and does what it does because the primitive subr-object
`#<subr car>' is stored in its function cell.

   We give functions names because it is convenient to refer to them by
their names in Lisp expressions.  For primitive subr-objects such as
`#<subr car>', names are the only way you can refer to them: there is
no read syntax for such objects.  For functions written in Lisp, the
name is more convenient to use in a call than an explicit lambda
expression.  Also, a function with a name can refer to itself--it can
be recursive.  Writing the function's name in its own definition is much
more convenient than making the function definition point to itself
(something that is not impossible but that has various disadvantages in
practice).

   We often identify functions with the symbols used to name them.  For
example, we often speak of "the function `car'," not distinguishing
between the symbol `car' and the primitive subr-object that is its
function definition.  For most purposes, the distinction is not
important.

   Even so, keep in mind that a function need not have a unique name.
While a given function object _usually_ appears in the function cell of
only one symbol, this is just a matter of convenience.  It is easy to
store it in several symbols using `fset'; then each of the symbols is
equally well a name for the same function.

   A symbol used as a function name may also be used as a variable;
these two uses of a symbol are independent and do not conflict.  (Some
Lisp dialects, such as Scheme, do not distinguish between a symbol's
value and its function definition; a symbol's value as a variable is
also its function definition.)  If you have not given a symbol a
function definition, you cannot use it as a function; whether the
symbol has a value as a variable makes no difference to this.

File: elisp,  Node: Defining Functions,  Next: Calling Functions,  Prev: Function Names,  Up: Functions

12.4 Defining Functions
=======================

We usually give a name to a function when it is first created.  This is
called "defining a function", and it is done with the `defun' special
form.

 -- Special Form: defun name argument-list body-forms
     `defun' is the usual way to define new Lisp functions.  It defines
     the symbol NAME as a function that looks like this:

          (lambda ARGUMENT-LIST . BODY-FORMS)

     `defun' stores this lambda expression in the function cell of
     NAME.  It returns the value NAME, but usually we ignore this value.

     As described previously, ARGUMENT-LIST is a list of argument names
     and may include the keywords `&optional' and `&rest' (*note Lambda
     Expressions::).  Also, the first two of the BODY-FORMS may be a
     documentation string and an interactive declaration.

     There is no conflict if the same symbol NAME is also used as a
     variable, since the symbol's value cell is independent of the
     function cell.  *Note Symbol Components::.

     Here are some examples:

          (defun foo () 5)
               => foo
          (foo)
               => 5

          (defun bar (a &optional b &rest c)
              (list a b c))
               => bar
          (bar 1 2 3 4 5)
               => (1 2 (3 4 5))
          (bar 1)
               => (1 nil nil)
          (bar)
          error--> Wrong number of arguments.

          (defun capitalize-backwards ()
            "Upcase the last letter of a word."
            (interactive)
            (backward-word 1)
            (forward-word 1)
            (backward-char 1)
            (capitalize-word 1))
               => capitalize-backwards

     Be careful not to redefine existing functions unintentionally.
     `defun' redefines even primitive functions such as `car' without
     any hesitation or notification.  Redefining a function already
     defined is often done deliberately, and there is no way to
     distinguish deliberate redefinition from unintentional
     redefinition.

 -- Function: defalias name definition &optional docstring
     This special form defines the symbol NAME as a function, with
     definition DEFINITION (which can be any valid Lisp function).  It
     returns DEFINITION.

     If DOCSTRING is non-`nil', it becomes the function documentation
     of NAME.  Otherwise, any documentation provided by DEFINITION is
     used.

     The proper place to use `defalias' is where a specific function
     name is being defined--especially where that name appears
     explicitly in the source file being loaded.  This is because
     `defalias' records which file defined the function, just like
     `defun' (*note Unloading::).

     By contrast, in programs that manipulate function definitions for
     other purposes, it is better to use `fset', which does not keep
     such records.  *Note Function Cells::.

   You cannot create a new primitive function with `defun' or
`defalias', but you can use them to change the function definition of
any symbol, even one such as `car' or `x-popup-menu' whose normal
definition is a primitive.  However, this is risky: for instance, it is
next to impossible to redefine `car' without breaking Lisp completely.
Redefining an obscure function such as `x-popup-menu' is less
dangerous, but it still may not work as you expect.  If there are calls
to the primitive from C code, they call the primitive's C definition
directly, so changing the symbol's definition will have no effect on
them.

   See also `defsubst', which defines a function like `defun' and tells
the Lisp compiler to open-code it.  *Note Inline Functions::.

File: elisp,  Node: Calling Functions,  Next: Mapping Functions,  Prev: Defining Functions,  Up: Functions

12.5 Calling Functions
======================

Defining functions is only half the battle.  Functions don't do
anything until you "call" them, i.e., tell them to run.  Calling a
function is also known as "invocation".

   The most common way of invoking a function is by evaluating a list.
For example, evaluating the list `(concat "a" "b")' calls the function
`concat' with arguments `"a"' and `"b"'.  *Note Evaluation::, for a
description of evaluation.

   When you write a list as an expression in your program, you specify
which function to call, and how many arguments to give it, in the text
of the program.  Usually that's just what you want.  Occasionally you
need to compute at run time which function to call.  To do that, use
the function `funcall'.  When you also need to determine at run time
how many arguments to pass, use `apply'.

 -- Function: funcall function &rest arguments
     `funcall' calls FUNCTION with ARGUMENTS, and returns whatever
     FUNCTION returns.

     Since `funcall' is a function, all of its arguments, including
     FUNCTION, are evaluated before `funcall' is called.  This means
     that you can use any expression to obtain the function to be
     called.  It also means that `funcall' does not see the expressions
     you write for the ARGUMENTS, only their values.  These values are
     _not_ evaluated a second time in the act of calling FUNCTION; the
     operation of `funcall' is like the normal procedure for calling a
     function, once its arguments have already been evaluated.

     The argument FUNCTION must be either a Lisp function or a
     primitive function.  Special forms and macros are not allowed,
     because they make sense only when given the "unevaluated" argument
     expressions.  `funcall' cannot provide these because, as we saw
     above, it never knows them in the first place.

          (setq f 'list)
               => list
          (funcall f 'x 'y 'z)
               => (x y z)
          (funcall f 'x 'y '(z))
               => (x y (z))
          (funcall 'and t nil)
          error--> Invalid function: #<subr and>

     Compare these examples with the examples of `apply'.

 -- Function: apply function &rest arguments
     `apply' calls FUNCTION with ARGUMENTS, just like `funcall' but
     with one difference: the last of ARGUMENTS is a list of objects,
     which are passed to FUNCTION as separate arguments, rather than a
     single list.  We say that `apply' "spreads" this list so that each
     individual element becomes an argument.

     `apply' returns the result of calling FUNCTION.  As with
     `funcall', FUNCTION must either be a Lisp function or a primitive
     function; special forms and macros do not make sense in `apply'.

          (setq f 'list)
               => list
          (apply f 'x 'y 'z)
          error--> Wrong type argument: listp, z
          (apply '+ 1 2 '(3 4))
               => 10
          (apply '+ '(1 2 3 4))
               => 10

          (apply 'append '((a b c) nil (x y z) nil))
               => (a b c x y z)

     For an interesting example of using `apply', see *note Definition
     of mapcar::.

   Sometimes it is useful to fix some of the function's arguments at
certain values, and leave the rest of arguments for when the function
is actually called.  The act of fixing some of the function's arguments
is called "partial application" of the function(1).  The result is a
new function that accepts the rest of arguments and calls the original
function with all the arguments combined.

   Here's how to do partial application in Emacs Lisp:

 -- Function: apply-partially func &rest args
     This function returns a new function which, when called, will call
     FUNC with the list of arguments composed from ARGS and additional
     arguments specified at the time of the call.  If FUNC accepts N
     arguments, then a call to `apply-partially' with `M < N' arguments
     will produce a new function of `N - M' arguments.

     Here's how we could define the built-in function `1+', if it
     didn't exist, using `apply-partially' and `+', another built-in
     function:

          (defalias '1+ (apply-partially '+ 1)
            "Increment argument by one.")
          (1+ 10)
               => 11

   It is common for Lisp functions to accept functions as arguments or
find them in data structures (especially in hook variables and property
lists) and call them using `funcall' or `apply'.  Functions that accept
function arguments are often called "functionals".

   Sometimes, when you call a functional, it is useful to supply a no-op
function as the argument.  Here are two different kinds of no-op
function:

 -- Function: identity arg
     This function returns ARG and has no side effects.

 -- Function: ignore &rest args
     This function ignores any arguments and returns `nil'.

   ---------- Footnotes ----------

   (1) This is related to, but different from "currying", which
transforms a function that takes multiple arguments in such a way that
it can be called as a chain of functions, each one with a single
argument.

File: elisp,  Node: Mapping Functions,  Next: Anonymous Functions,  Prev: Calling Functions,  Up: Functions

12.6 Mapping Functions
======================

A "mapping function" applies a given function (_not_ a special form or
macro) to each element of a list or other collection.  Emacs Lisp has
several such functions; `mapcar' and `mapconcat', which scan a list,
are described here.  *Note Definition of mapatoms::, for the function
`mapatoms' which maps over the symbols in an obarray.  *Note Definition
of maphash::, for the function `maphash' which maps over key/value
associations in a hash table.

   These mapping functions do not allow char-tables because a char-table
is a sparse array whose nominal range of indices is very large.  To map
over a char-table in a way that deals properly with its sparse nature,
use the function `map-char-table' (*note Char-Tables::).

 -- Function: mapcar function sequence
     `mapcar' applies FUNCTION to each element of SEQUENCE in turn, and
     returns a list of the results.

     The argument SEQUENCE can be any kind of sequence except a
     char-table; that is, a list, a vector, a bool-vector, or a string.
     The result is always a list.  The length of the result is the same
     as the length of SEQUENCE.  For example:

          (mapcar 'car '((a b) (c d) (e f)))
               => (a c e)
          (mapcar '1+ [1 2 3])
               => (2 3 4)
          (mapcar 'char-to-string "abc")
               => ("a" "b" "c")

          ;; Call each function in `my-hooks'.
          (mapcar 'funcall my-hooks)

          (defun mapcar* (function &rest args)
            "Apply FUNCTION to successive cars of all ARGS.
          Return the list of results."
            ;; If no list is exhausted,
            (if (not (memq nil args))
                ;; apply function to CARs.
                (cons (apply function (mapcar 'car args))
                      (apply 'mapcar* function
                             ;; Recurse for rest of elements.
                             (mapcar 'cdr args)))))

          (mapcar* 'cons '(a b c) '(1 2 3 4))
               => ((a . 1) (b . 2) (c . 3))

 -- Function: mapc function sequence
     `mapc' is like `mapcar' except that FUNCTION is used for
     side-effects only--the values it returns are ignored, not collected
     into a list.  `mapc' always returns SEQUENCE.

 -- Function: mapconcat function sequence separator
     `mapconcat' applies FUNCTION to each element of SEQUENCE: the
     results, which must be strings, are concatenated.  Between each
     pair of result strings, `mapconcat' inserts the string SEPARATOR.
     Usually SEPARATOR contains a space or comma or other suitable
     punctuation.

     The argument FUNCTION must be a function that can take one
     argument and return a string.  The argument SEQUENCE can be any
     kind of sequence except a char-table; that is, a list, a vector, a
     bool-vector, or a string.

          (mapconcat 'symbol-name
                     '(The cat in the hat)
                     " ")
               => "The cat in the hat"

          (mapconcat (function (lambda (x) (format "%c" (1+ x))))
                     "HAL-8000"
                     "")
               => "IBM.9111"

File: elisp,  Node: Anonymous Functions,  Next: Function Cells,  Prev: Mapping Functions,  Up: Functions

12.7 Anonymous Functions
========================

In Lisp, a function is a list that starts with `lambda', a byte-code
function compiled from such a list, or alternatively a primitive
subr-object; names are "extra."  Although usually functions are defined
with `defun' and given names at the same time, it is occasionally more
concise to use an explicit lambda expression--an anonymous function.
Such a list is valid wherever a function name is.

   Any method of creating such a list makes a valid function.  Even
this:

     (setq silly (append '(lambda (x)) (list (list '+ (* 3 4) 'x))))
     => (lambda (x) (+ 12 x))

This computes a list that looks like `(lambda (x) (+ 12 x))' and makes
it the value (_not_ the function definition!) of `silly'.

   Here is how we might call this function:

     (funcall silly 1)
     => 13

(It does _not_ work to write `(silly 1)', because this function is not
the _function definition_ of `silly'.  We have not given `silly' any
function definition, just a value as a variable.)

   Most of the time, anonymous functions are constants that appear in
your program.  For example, you might want to pass one as an argument to
the function `mapcar', which applies any given function to each element
of a list.

   Here we define a function `change-property' which uses a function as
its third argument:

     (defun change-property (symbol prop function)
       (let ((value (get symbol prop)))
         (put symbol prop (funcall function value))))

Here we define a function that uses `change-property', passing it a
function to double a number:

     (defun double-property (symbol prop)
       (change-property symbol prop '(lambda (x) (* 2 x))))

In such cases, we usually use the special form `function' instead of
simple quotation to quote the anonymous function, like this:

     (defun double-property (symbol prop)
       (change-property symbol prop
                        (function (lambda (x) (* 2 x)))))

   Using `function' instead of `quote' makes a difference if you
compile the function `double-property'.  For example, if you compile
the second definition of `double-property', the anonymous function is
compiled as well.  By contrast, if you compile the first definition
which uses ordinary `quote', the argument passed to `change-property'
is the precise list shown:

     (lambda (x) (* x 2))

The Lisp compiler cannot assume this list is a function, even though it
looks like one, since it does not know what `change-property' will do
with the list.  Perhaps it will check whether the CAR of the third
element is the symbol `*'!  Using `function' tells the compiler it is
safe to go ahead and compile the constant function.

   Nowadays it is possible to omit `function' entirely, like this:

     (defun double-property (symbol prop)
       (change-property symbol prop (lambda (x) (* 2 x))))

This is because `lambda' itself implies `function'.

   We sometimes write `function' instead of `quote' when quoting the
name of a function, but this usage is just a sort of comment:

     (function SYMBOL) == (quote SYMBOL) == 'SYMBOL

   The read syntax `#'' is a short-hand for using `function'.  For
example,

     #'(lambda (x) (* x x))

is equivalent to

     (function (lambda (x) (* x x)))

 -- Special Form: function function-object
     This special form returns FUNCTION-OBJECT without evaluating it.
     In this, it is equivalent to `quote'.  However, it serves as a
     note to the Emacs Lisp compiler that FUNCTION-OBJECT is intended
     to be used only as a function, and therefore can safely be
     compiled.  Contrast this with `quote', in *note Quoting::.

   *Note describe-symbols example::, for a realistic example using
`function' and an anonymous function.

File: elisp,  Node: Function Cells,  Next: Obsolete Functions,  Prev: Anonymous Functions,  Up: Functions

12.8 Accessing Function Cell Contents
=====================================

The "function definition" of a symbol is the object stored in the
function cell of the symbol.  The functions described here access, test,
and set the function cell of symbols.

   See also the function `indirect-function'.  *Note Definition of
indirect-function::.

 -- Function: symbol-function symbol
     This returns the object in the function cell of SYMBOL.  If the
     symbol's function cell is void, a `void-function' error is
     signaled.

     This function does not check that the returned object is a
     legitimate function.

          (defun bar (n) (+ n 2))
               => bar
          (symbol-function 'bar)
               => (lambda (n) (+ n 2))
          (fset 'baz 'bar)
               => bar
          (symbol-function 'baz)
               => bar

   If you have never given a symbol any function definition, we say that
that symbol's function cell is "void".  In other words, the function
cell does not have any Lisp object in it.  If you try to call such a
symbol as a function, it signals a `void-function' error.

   Note that void is not the same as `nil' or the symbol `void'.  The
symbols `nil' and `void' are Lisp objects, and can be stored into a
function cell just as any other object can be (and they can be valid
functions if you define them in turn with `defun').  A void function
cell contains no object whatsoever.

   You can test the voidness of a symbol's function definition with
`fboundp'.  After you have given a symbol a function definition, you
can make it void once more using `fmakunbound'.

 -- Function: fboundp symbol
     This function returns `t' if the symbol has an object in its
     function cell, `nil' otherwise.  It does not check that the object
     is a legitimate function.

 -- Function: fmakunbound symbol
     This function makes SYMBOL's function cell void, so that a
     subsequent attempt to access this cell will cause a
     `void-function' error.  It returns SYMBOL.  (See also
     `makunbound', in *note Void Variables::.)

          (defun foo (x) x)
               => foo
          (foo 1)
               =>1
          (fmakunbound 'foo)
               => foo
          (foo 1)
          error--> Symbol's function definition is void: foo

 -- Function: fset symbol definition
     This function stores DEFINITION in the function cell of SYMBOL.
     The result is DEFINITION.  Normally DEFINITION should be a
     function or the name of a function, but this is not checked.  The
     argument SYMBOL is an ordinary evaluated argument.

     There are three normal uses of this function:

        * Copying one symbol's function definition to another--in other
          words, making an alternate name for a function.  (If you
          think of this as the definition of the new name, you should
          use `defalias' instead of `fset'; see *note Definition of
          defalias::.)

        * Giving a symbol a function definition that is not a list and
          therefore cannot be made with `defun'.  For example, you can
          use `fset' to give a symbol `s1' a function definition which
          is another symbol `s2'; then `s1' serves as an alias for
          whatever definition `s2' presently has.  (Once again use
          `defalias' instead of `fset' if you think of this as the
          definition of `s1'.)

        * In constructs for defining or altering functions.  If `defun'
          were not a primitive, it could be written in Lisp (as a
          macro) using `fset'.

     Here are examples of these uses:

          ;; Save `foo''s definition in `old-foo'.
          (fset 'old-foo (symbol-function 'foo))

          ;; Make the symbol `car' the function definition of `xfirst'.
          ;; (Most likely, `defalias' would be better than `fset' here.)
          (fset 'xfirst 'car)
               => car
          (xfirst '(1 2 3))
               => 1
          (symbol-function 'xfirst)
               => car
          (symbol-function (symbol-function 'xfirst))
               => #<subr car>

          ;; Define a named keyboard macro.
          (fset 'kill-two-lines "\^u2\^k")
               => "\^u2\^k"

          ;; Here is a function that alters other functions.
          (defun copy-function-definition (new old)
            "Define NEW with the same function definition as OLD."
            (fset new (symbol-function old)))

   `fset' is sometimes used to save the old definition of a function
before redefining it.  That permits the new definition to invoke the
old definition.  But it is unmodular and unclean for a Lisp file to
redefine a function defined elsewhere.  If you want to modify a
function defined by another package, it is cleaner to use `defadvice'
(*note Advising Functions::).

File: elisp,  Node: Obsolete Functions,  Next: Inline Functions,  Prev: Function Cells,  Up: Functions

12.9 Declaring Functions Obsolete
=================================

You can use `make-obsolete' to declare a function obsolete.  This
indicates that the function may be removed at some stage in the future.

 -- Function: make-obsolete obsolete-name current-name &optional when
     This function makes the byte compiler warn that the function
     OBSOLETE-NAME is obsolete.  If CURRENT-NAME is a symbol, the
     warning message says to use CURRENT-NAME instead of OBSOLETE-NAME.
     CURRENT-NAME does not need to be an alias for OBSOLETE-NAME; it
     can be a different function with similar functionality.  If
     CURRENT-NAME is a string, it is the warning message.

     If provided, WHEN should be a string indicating when the function
     was first made obsolete--for example, a date or a release number.

   You can define a function as an alias and declare it obsolete at the
same time using the macro `define-obsolete-function-alias'.

 -- Macro: define-obsolete-function-alias obsolete-name current-name
          &optional when docstring
     This macro marks the function OBSOLETE-NAME obsolete and also
     defines it as an alias for the function CURRENT-NAME.  It is
     equivalent to the following:

          (defalias OBSOLETE-NAME CURRENT-NAME DOCSTRING)
          (make-obsolete OBSOLETE-NAME CURRENT-NAME WHEN)

File: elisp,  Node: Inline Functions,  Next: Declaring Functions,  Prev: Obsolete Functions,  Up: Functions

12.10 Inline Functions
======================

You can define an "inline function" by using `defsubst' instead of
`defun'.  An inline function works just like an ordinary function
except for one thing: when you compile a call to the function, the
function's definition is open-coded into the caller.

   Making a function inline makes explicit calls run faster.  But it
also has disadvantages.  For one thing, it reduces flexibility; if you
change the definition of the function, calls already inlined still use
the old definition until you recompile them.

   Another disadvantage is that making a large function inline can
increase the size of compiled code both in files and in memory.  Since
the speed advantage of inline functions is greatest for small
functions, you generally should not make large functions inline.

   Also, inline functions do not behave well with respect to debugging,
tracing, and advising (*note Advising Functions::).  Since ease of
debugging and the flexibility of redefining functions are important
features of Emacs, you should not make a function inline, even if it's
small, unless its speed is really crucial, and you've timed the code to
verify that using `defun' actually has performance problems.

   It's possible to define a macro to expand into the same code that an
inline function would execute.  (*Note Macros::.)  But the macro would
be limited to direct use in expressions--a macro cannot be called with
`apply', `mapcar' and so on.  Also, it takes some work to convert an
ordinary function into a macro.  To convert it into an inline function
is very easy; simply replace `defun' with `defsubst'.  Since each
argument of an inline function is evaluated exactly once, you needn't
worry about how many times the body uses the arguments, as you do for
macros.  (*Note Argument Evaluation::.)

   Inline functions can be used and open-coded later on in the same
file, following the definition, just like macros.

File: elisp,  Node: Declaring Functions,  Next: Function Safety,  Prev: Inline Functions,  Up: Functions

12.11 Telling the Compiler that a Function is Defined
=====================================================

Byte-compiling a file often produces warnings about functions that the
compiler doesn't know about (*note Compiler Errors::).  Sometimes this
indicates a real problem, but usually the functions in question are
defined in other files which would be loaded if that code is run.  For
example, byte-compiling `fortran.el' used to warn:

     In end of data:
     fortran.el:2152:1:Warning: the function `gud-find-c-expr' is not known
         to be defined.

   In fact, `gud-find-c-expr' is only used in the function that Fortran
mode uses for the local value of `gud-find-expr-function', which is a
callback from GUD; if it is called, the GUD functions will be loaded.
When you know that such a warning does not indicate a real problem, it
is good to suppress the warning.  That makes new warnings which might
mean real problems more visible.  You do that with `declare-function'.

   All you need to do is add a `declare-function' statement before the
first use of the function in question:

     (declare-function gud-find-c-expr "gud.el" nil)

   This says that `gud-find-c-expr' is defined in `gud.el' (the `.el'
can be omitted).  The compiler takes for granted that that file really
defines the function, and does not check.

   The optional third argument specifies the argument list of
`gud-find-c-expr'.  In this case, it takes no arguments (`nil' is
different from not specifying a value).  In other cases, this might be
something like `(file &optional overwrite)'.  You don't have to specify
the argument list, but if you do the byte compiler can check that the
calls match the declaration.

 -- Macro: declare-function function file &optional arglist fileonly
     Tell the byte compiler to assume that FUNCTION is defined, with
     arguments ARGLIST, and that the definition should come from the
     file FILE.  FILEONLY non-`nil' means only check that FILE exists,
     not that it actually defines FUNCTION.

   To verify that these functions really are declared where
`declare-function' says they are, use `check-declare-file' to check all
`declare-function' calls in one source file, or use
`check-declare-directory' check all the files in and under a certain
directory.

   These commands find the file that ought to contain a function's
definition using `locate-library'; if that finds no file, they expand
the definition file name relative to the directory of the file that
contains the `declare-function' call.

   You can also say that a function is defined by C code by specifying
a file name ending in `.c'.  `check-declare-file' looks for these files
in the C source code directory.  This is useful only when you call a
function that is defined only on certain systems.  Most of the
primitive functions of Emacs are always defined so they will never give
you a warning.

   Sometimes a file will optionally use functions from an external
package.  If you prefix the filename in the `declare-function'
statement with `ext:', then it will be checked if it is found,
otherwise skipped without error.

   There are some function definitions that `check-declare' does not
understand (e.g. `defstruct' and some other macros).  In such cases,
you can pass a non-`nil' FILEONLY argument to `declare-function',
meaning to only check that the file exists, not that it actually
defines the function.  Note that to do this without having to specify
an argument list, you should set the ARGLIST argument to `t' (because
`nil' means an empty argument list, as opposed to an unspecified one).

File: elisp,  Node: Function Safety,  Next: Related Topics,  Prev: Declaring Functions,  Up: Functions

12.12 Determining whether a Function is Safe to Call
====================================================

Some major modes such as SES call functions that are stored in user
files.  (*note (ses)Top::, for more information on SES.)  User files
sometimes have poor pedigrees--you can get a spreadsheet from someone
you've just met, or you can get one through email from someone you've
never met.  So it is risky to call a function whose source code is
stored in a user file until you have determined that it is safe.

 -- Function: unsafep form &optional unsafep-vars
     Returns `nil' if FORM is a "safe" Lisp expression, or returns a
     list that describes why it might be unsafe.  The argument
     UNSAFEP-VARS is a list of symbols known to have temporary bindings
     at this point; it is mainly used for internal recursive calls.
     The current buffer is an implicit argument, which provides a list
     of buffer-local bindings.

   Being quick and simple, `unsafep' does a very light analysis and
rejects many Lisp expressions that are actually safe.  There are no
known cases where `unsafep' returns `nil' for an unsafe expression.
However, a "safe" Lisp expression can return a string with a `display'
property, containing an associated Lisp expression to be executed after
the string is inserted into a buffer.  This associated expression can
be a virus.  In order to be safe, you must delete properties from all
strings calculated by user code before inserting them into buffers.

File: elisp,  Node: Related Topics,  Prev: Function Safety,  Up: Functions

12.13 Other Topics Related to Functions
=======================================

Here is a table of several functions that do things related to function
calling and function definitions.  They are documented elsewhere, but
we provide cross references here.

`apply'
     See *note Calling Functions::.

`autoload'
     See *note Autoload::.

`call-interactively'
     See *note Interactive Call::.

`called-interactively-p'
     See *note Distinguish Interactive::.

`commandp'
     See *note Interactive Call::.

`documentation'
     See *note Accessing Documentation::.

`eval'
     See *note Eval::.

`funcall'
     See *note Calling Functions::.

`function'
     See *note Anonymous Functions::.

`ignore'
     See *note Calling Functions::.

`indirect-function'
     See *note Function Indirection::.

`interactive'
     See *note Using Interactive::.

`interactive-p'
     See *note Distinguish Interactive::.

`mapatoms'
     See *note Creating Symbols::.

`mapcar'
     See *note Mapping Functions::.

`map-char-table'
     See *note Char-Tables::.

`mapconcat'
     See *note Mapping Functions::.

`undefined'
     See *note Functions for Key Lookup::.

File: elisp,  Node: Macros,  Next: Customization,  Prev: Functions,  Up: Top

13 Macros
*********

"Macros" enable you to define new control constructs and other language
features.  A macro is defined much like a function, but instead of
telling how to compute a value, it tells how to compute another Lisp
expression which will in turn compute the value.  We call this
expression the "expansion" of the macro.

   Macros can do this because they operate on the unevaluated
expressions for the arguments, not on the argument values as functions
do.  They can therefore construct an expansion containing these
argument expressions or parts of them.

   If you are using a macro to do something an ordinary function could
do, just for the sake of speed, consider using an inline function
instead.  *Note Inline Functions::.

* Menu:

* 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.
* Indenting Macros::        Specifying how to indent macro calls.

File: elisp,  Node: Simple Macro,  Next: Expansion,  Up: Macros

13.1 A Simple Example of a Macro
================================

Suppose we would like to define a Lisp construct to increment a
variable value, much like the `++' operator in C.  We would like to
write `(inc x)' and have the effect of `(setq x (1+ x))'.  Here's a
macro definition that does the job:

     (defmacro inc (var)
        (list 'setq var (list '1+ var)))

   When this is called with `(inc x)', the argument VAR is the symbol
`x'--_not_ the _value_ of `x', as it would be in a function.  The body
of the macro uses this to construct the expansion, which is `(setq x
(1+ x))'.  Once the macro definition returns this expansion, Lisp
proceeds to evaluate it, thus incrementing `x'.

File: elisp,  Node: Expansion,  Next: Compiling Macros,  Prev: Simple Macro,  Up: Macros

13.2 Expansion of a Macro Call
==============================

A macro call looks just like a function call in that it is a list which
starts with the name of the macro.  The rest of the elements of the list
are the arguments of the macro.

   Evaluation of the macro call begins like evaluation of a function
call except for one crucial difference: the macro arguments are the
actual expressions appearing in the macro call.  They are not evaluated
before they are given to the macro definition.  By contrast, the
arguments of a function are results of evaluating the elements of the
function call list.

   Having obtained the arguments, Lisp invokes the macro definition just
as a function is invoked.  The argument variables of the macro are bound
to the argument values from the macro call, or to a list of them in the
case of a `&rest' argument.  And the macro body executes and returns
its value just as a function body does.

   The second crucial difference between macros and functions is that
the value returned by the macro body is not the value of the macro call.
Instead, it is an alternate expression for computing that value, also
known as the "expansion" of the macro.  The Lisp interpreter proceeds
to evaluate the expansion as soon as it comes back from the macro.

   Since the expansion is evaluated in the normal manner, it may contain
calls to other macros.  It may even be a call to the same macro, though
this is unusual.

   You can see the expansion of a given macro call by calling
`macroexpand'.

 -- Function: macroexpand form &optional environment
     This function expands FORM, if it is a macro call.  If the result
     is another macro call, it is expanded in turn, until something
     which is not a macro call results.  That is the value returned by
     `macroexpand'.  If FORM is not a macro call to begin with, it is
     returned as given.

     Note that `macroexpand' does not look at the subexpressions of
     FORM (although some macro definitions may do so).  Even if they
     are macro calls themselves, `macroexpand' does not expand them.

     The function `macroexpand' does not expand calls to inline
     functions.  Normally there is no need for that, since a call to an
     inline function is no harder to understand than a call to an
     ordinary function.

     If ENVIRONMENT is provided, it specifies an alist of macro
     definitions that shadow the currently defined macros.  Byte
     compilation uses this feature.

          (defmacro inc (var)
              (list 'setq var (list '1+ var)))
               => inc

          (macroexpand '(inc r))
               => (setq r (1+ r))

          (defmacro inc2 (var1 var2)
              (list 'progn (list 'inc var1) (list 'inc var2)))
               => inc2

          (macroexpand '(inc2 r s))
               => (progn (inc r) (inc s))  ; `inc' not expanded here.

 -- Function: macroexpand-all form &optional environment
     `macroexpand-all' expands macros like `macroexpand', but will look
     for and expand all macros in FORM, not just at the top-level.  If
     no macros are expanded, the return value is `eq' to FORM.

     Repeating the example used for `macroexpand' above with
     `macroexpand-all', we see that `macroexpand-all' _does_ expand the
     embedded calls to `inc':

          (macroexpand-all '(inc2 r s))
               => (progn (setq r (1+ r)) (setq s (1+ s)))


File: elisp,  Node: Compiling Macros,  Next: Defining Macros,  Prev: Expansion,  Up: Macros

13.3 Macros and Byte Compilation
================================

You might ask why we take the trouble to compute an expansion for a
macro and then evaluate the expansion.  Why not have the macro body
produce the desired results directly?  The reason has to do with
compilation.

   When a macro call appears in a Lisp program being compiled, the Lisp
compiler calls the macro definition just as the interpreter would, and
receives an expansion.  But instead of evaluating this expansion, it
compiles the expansion as if it had appeared directly in the program.
As a result, the compiled code produces the value and side effects
intended for the macro, but executes at full compiled speed.  This would
not work if the macro body computed the value and side effects
itself--they would be computed at compile time, which is not useful.

   In order for compilation of macro calls to work, the macros must
already be defined in Lisp when the calls to them are compiled.  The
compiler has a special feature to help you do this: if a file being
compiled contains a `defmacro' form, the macro is defined temporarily
for the rest of the compilation of that file.

   Byte-compiling a file also executes any `require' calls at top-level
in the file, so you can ensure that necessary macro definitions are
available during compilation by requiring the files that define them
(*note Named Features::).  To avoid loading the macro definition files
when someone _runs_ the compiled program, write `eval-when-compile'
around the `require' calls (*note Eval During Compile::).

File: elisp,  Node: Defining Macros,  Next: Backquote,  Prev: Compiling Macros,  Up: Macros

13.4 Defining Macros
====================

A Lisp macro is a list whose CAR is `macro'.  Its CDR should be a
function; expansion of the macro works by applying the function (with
`apply') to the list of unevaluated argument-expressions from the macro
call.

   It is possible to use an anonymous Lisp macro just like an anonymous
function, but this is never done, because it does not make sense to pass
an anonymous macro to functionals such as `mapcar'.  In practice, all
Lisp macros have names, and they are usually defined with the special
form `defmacro'.

 -- Special Form: defmacro name argument-list body-forms...
     `defmacro' defines the symbol NAME as a macro that looks like this:

          (macro lambda ARGUMENT-LIST . BODY-FORMS)

     (Note that the CDR of this list is a function--a lambda
     expression.)  This macro object is stored in the function cell of
     NAME.  The value returned by evaluating the `defmacro' form is
     NAME, but usually we ignore this value.

     The shape and meaning of ARGUMENT-LIST is the same as in a
     function, and the keywords `&rest' and `&optional' may be used
     (*note Argument List::).  Macros may have a documentation string,
     but any `interactive' declaration is ignored since macros cannot be
     called interactively.

   The body of the macro definition can include a `declare' form, which
can specify how <TAB> should indent macro calls, and how to step
through them for Edebug.

 -- Macro: declare SPECS...
     A `declare' form is used in a macro definition to specify various
     additional information about it.  Two kinds of specification are
     currently supported:

    `(debug EDEBUG-FORM-SPEC)'
          Specify how to step through macro calls for Edebug.  *Note
          Instrumenting Macro Calls::.

    `(indent INDENT-SPEC)'
          Specify how to indent calls to this macro.  *Note Indenting
          Macros::, for more details.

     A `declare' form only has its special effect in the body of a
     `defmacro' form if it immediately follows the documentation
     string, if present, or the argument list otherwise.  (Strictly
     speaking, _several_ `declare' forms can follow the documentation
     string or argument list, but since a `declare' form can have
     several SPECS, they can always be combined into a single form.)
     When used at other places in a `defmacro' form, or outside a
     `defmacro' form, `declare' just returns `nil' without evaluating
     any SPECS.

   No macro absolutely needs a `declare' form, because that form has no
effect on how the macro expands, on what the macro means in the
program.  It only affects secondary features: indentation and Edebug.

File: elisp,  Node: Backquote,  Next: Problems with Macros,  Prev: Defining Macros,  Up: Macros

13.5 Backquote
==============

Macros often need to construct large list structures from a mixture of
constants and nonconstant parts.  To make this easier, use the ``'
syntax (usually called "backquote").

   Backquote allows you to quote a list, but selectively evaluate
elements of that list.  In the simplest case, it is identical to the
special form `quote' (*note Quoting::).  For example, these two forms
yield identical results:

     `(a list of (+ 2 3) elements)
          => (a list of (+ 2 3) elements)
     '(a list of (+ 2 3) elements)
          => (a list of (+ 2 3) elements)

   The special marker `,' inside of the argument to backquote indicates
a value that isn't constant.  Backquote evaluates the argument of `,'
and puts the value in the list structure:

     (list 'a 'list 'of (+ 2 3) 'elements)
          => (a list of 5 elements)
     `(a list of ,(+ 2 3) elements)
          => (a list of 5 elements)

   Substitution with `,' is allowed at deeper levels of the list
structure also.  For example:

     (defmacro t-becomes-nil (variable)
       `(if (eq ,variable t)
            (setq ,variable nil)))

     (t-becomes-nil foo)
          == (if (eq foo t) (setq foo nil))

   You can also "splice" an evaluated value into the resulting list,
using the special marker `,@'.  The elements of the spliced list become
elements at the same level as the other elements of the resulting list.
The equivalent code without using ``' is often unreadable.  Here are
some examples:

     (setq some-list '(2 3))
          => (2 3)
     (cons 1 (append some-list '(4) some-list))
          => (1 2 3 4 2 3)
     `(1 ,@some-list 4 ,@some-list)
          => (1 2 3 4 2 3)

     (setq list '(hack foo bar))
          => (hack foo bar)
     (cons 'use
       (cons 'the
         (cons 'words (append (cdr list) '(as elements)))))
          => (use the words foo bar as elements)
     `(use the words ,@(cdr list) as elements)
          => (use the words foo bar as elements)

File: elisp,  Node: Problems with Macros,  Next: Indenting Macros,  Prev: Backquote,  Up: Macros

13.6 Common Problems Using Macros
=================================

The basic facts of macro expansion have counterintuitive consequences.
This section describes some important consequences that can lead to
trouble, and rules to follow to avoid trouble.

* Menu:

* Wrong Time::             Do the work in the expansion, not in the macro.
* Argument Evaluation::    The expansion should evaluate each macro arg once.
* Surprising Local Vars::  Local variable bindings in the expansion
                              require special care.
* Eval During Expansion::  Don't evaluate them; put them in the expansion.
* Repeated Expansion::     Avoid depending on how many times expansion is done.

File: elisp,  Node: Wrong Time,  Next: Argument Evaluation,  Up: Problems with Macros

13.6.1 Wrong Time
-----------------

The most common problem in writing macros is doing some of the real
work prematurely--while expanding the macro, rather than in the
expansion itself.  For instance, one real package had this macro
definition:

     (defmacro my-set-buffer-multibyte (arg)
       (if (fboundp 'set-buffer-multibyte)
           (set-buffer-multibyte arg)))

   With this erroneous macro definition, the program worked fine when
interpreted but failed when compiled.  This macro definition called
`set-buffer-multibyte' during compilation, which was wrong, and then
did nothing when the compiled package was run.  The definition that the
programmer really wanted was this:

     (defmacro my-set-buffer-multibyte (arg)
       (if (fboundp 'set-buffer-multibyte)
           `(set-buffer-multibyte ,arg)))

This macro expands, if appropriate, into a call to
`set-buffer-multibyte' that will be executed when the compiled program
is actually run.

File: elisp,  Node: Argument Evaluation,  Next: Surprising Local Vars,  Prev: Wrong Time,  Up: Problems with Macros

13.6.2 Evaluating Macro Arguments Repeatedly
--------------------------------------------

When defining a macro you must pay attention to the number of times the
arguments will be evaluated when the expansion is executed.  The
following macro (used to facilitate iteration) illustrates the problem.
This macro allows us to write a simple "for" loop such as one might
find in Pascal.

     (defmacro for (var from init to final do &rest body)
       "Execute a simple \"for\" loop.
     For example, (for i from 1 to 10 do (print i))."
       (list 'let (list (list var init))
             (cons 'while (cons (list '<= var final)
                                (append body (list (list 'inc var)))))))
     => for

     (for i from 1 to 3 do
        (setq square (* i i))
        (princ (format "\n%d %d" i square)))
     ==>
     (let ((i 1))
       (while (<= i 3)
         (setq square (* i i))
         (princ (format "\n%d %d" i square))
         (inc i)))

          -|1       1
          -|2       4
          -|3       9
     => nil

The arguments `from', `to', and `do' in this macro are "syntactic
sugar"; they are entirely ignored.  The idea is that you will write
noise words (such as `from', `to', and `do') in those positions in the
macro call.

   Here's an equivalent definition simplified through use of backquote:

     (defmacro for (var from init to final do &rest body)
       "Execute a simple \"for\" loop.
     For example, (for i from 1 to 10 do (print i))."
       `(let ((,var ,init))
          (while (<= ,var ,final)
            ,@body
            (inc ,var))))

   Both forms of this definition (with backquote and without) suffer
from the defect that FINAL is evaluated on every iteration.  If FINAL
is a constant, this is not a problem.  If it is a more complex form,
say `(long-complex-calculation x)', this can slow down the execution
significantly.  If FINAL has side effects, executing it more than once
is probably incorrect.

   A well-designed macro definition takes steps to avoid this problem by
producing an expansion that evaluates the argument expressions exactly
once unless repeated evaluation is part of the intended purpose of the
macro.  Here is a correct expansion for the `for' macro:

     (let ((i 1)
           (max 3))
       (while (<= i max)
         (setq square (* i i))
         (princ (format "%d      %d" i square))
         (inc i)))

   Here is a macro definition that creates this expansion:

     (defmacro for (var from init to final do &rest body)
       "Execute a simple for loop: (for i from 1 to 10 do (print i))."
       `(let ((,var ,init)
              (max ,final))
          (while (<= ,var max)
            ,@body
            (inc ,var))))

   Unfortunately, this fix introduces another problem, described in the
following section.

File: elisp,  Node: Surprising Local Vars,  Next: Eval During Expansion,  Prev: Argument Evaluation,  Up: Problems with Macros

13.6.3 Local Variables in Macro Expansions
------------------------------------------

In the previous section, the definition of `for' was fixed as follows
to make the expansion evaluate the macro arguments the proper number of
times:

     (defmacro for (var from init to final do &rest body)
       "Execute a simple for loop: (for i from 1 to 10 do (print i))."
       `(let ((,var ,init)
              (max ,final))
          (while (<= ,var max)
            ,@body
            (inc ,var))))

The new definition of `for' has a new problem: it introduces a local
variable named `max' which the user does not expect.  This causes
trouble in examples such as the following:

     (let ((max 0))
       (for x from 0 to 10 do
         (let ((this (frob x)))
           (if (< max this)
               (setq max this)))))

The references to `max' inside the body of the `for', which are
supposed to refer to the user's binding of `max', really access the
binding made by `for'.

   The way to correct this is to use an uninterned symbol instead of
`max' (*note Creating Symbols::).  The uninterned symbol can be bound
and referred to just like any other symbol, but since it is created by
`for', we know that it cannot already appear in the user's program.
Since it is not interned, there is no way the user can put it into the
program later.  It will never appear anywhere except where put by
`for'.  Here is a definition of `for' that works this way:

     (defmacro for (var from init to final do &rest body)
       "Execute a simple for loop: (for i from 1 to 10 do (print i))."
       (let ((tempvar (make-symbol "max")))
         `(let ((,var ,init)
                (,tempvar ,final))
            (while (<= ,var ,tempvar)
              ,@body
              (inc ,var)))))

This creates an uninterned symbol named `max' and puts it in the
expansion instead of the usual interned symbol `max' that appears in
expressions ordinarily.

File: elisp,  Node: Eval During Expansion,  Next: Repeated Expansion,  Prev: Surprising Local Vars,  Up: Problems with Macros

13.6.4 Evaluating Macro Arguments in Expansion
----------------------------------------------

Another problem can happen if the macro definition itself evaluates any
of the macro argument expressions, such as by calling `eval' (*note
Eval::).  If the argument is supposed to refer to the user's variables,
you may have trouble if the user happens to use a variable with the
same name as one of the macro arguments.  Inside the macro body, the
macro argument binding is the most local binding of this variable, so
any references inside the form being evaluated do refer to it.  Here is
an example:

     (defmacro foo (a)
       (list 'setq (eval a) t))
          => foo
     (setq x 'b)
     (foo x) ==> (setq b t)
          => t                  ; and `b' has been set.
     ;; but
     (setq a 'c)
     (foo a) ==> (setq a t)
          => t                  ; but this set `a', not `c'.

   It makes a difference whether the user's variable is named `a' or
`x', because `a' conflicts with the macro argument variable `a'.

   Another problem with calling `eval' in a macro definition is that it
probably won't do what you intend in a compiled program.  The byte
compiler runs macro definitions while compiling the program, when the
program's own computations (which you might have wished to access with
`eval') don't occur and its local variable bindings don't exist.

   To avoid these problems, *don't evaluate an argument expression
while computing the macro expansion*.  Instead, substitute the
expression into the macro expansion, so that its value will be computed
as part of executing the expansion.  This is how the other examples in
this chapter work.

File: elisp,  Node: Repeated Expansion,  Prev: Eval During Expansion,  Up: Problems with Macros

13.6.5 How Many Times is the Macro Expanded?
--------------------------------------------

Occasionally problems result from the fact that a macro call is
expanded each time it is evaluated in an interpreted function, but is
expanded only once (during compilation) for a compiled function.  If the
macro definition has side effects, they will work differently depending
on how many times the macro is expanded.

   Therefore, you should avoid side effects in computation of the macro
expansion, unless you really know what you are doing.

   One special kind of side effect can't be avoided: constructing Lisp
objects.  Almost all macro expansions include constructed lists; that is
the whole point of most macros.  This is usually safe; there is just one
case where you must be careful: when the object you construct is part
of a quoted constant in the macro expansion.

   If the macro is expanded just once, in compilation, then the object
is constructed just once, during compilation.  But in interpreted
execution, the macro is expanded each time the macro call runs, and this
means a new object is constructed each time.

   In most clean Lisp code, this difference won't matter.  It can matter
only if you perform side-effects on the objects constructed by the macro
definition.  Thus, to avoid trouble, *avoid side effects on objects
constructed by macro definitions*.  Here is an example of how such side
effects can get you into trouble:

     (defmacro empty-object ()
       (list 'quote (cons nil nil)))

     (defun initialize (condition)
       (let ((object (empty-object)))
         (if condition
             (setcar object condition))
         object))

If `initialize' is interpreted, a new list `(nil)' is constructed each
time `initialize' is called.  Thus, no side effect survives between
calls.  If `initialize' is compiled, then the macro `empty-object' is
expanded during compilation, producing a single "constant" `(nil)' that
is reused and altered each time `initialize' is called.

   One way to avoid pathological cases like this is to think of
`empty-object' as a funny kind of constant, not as a memory allocation
construct.  You wouldn't use `setcar' on a constant such as `'(nil)',
so naturally you won't use it on `(empty-object)' either.

File: elisp,  Node: Indenting Macros,  Prev: Problems with Macros,  Up: Macros

13.7 Indenting Macros
=====================

You can use the `declare' form in the macro definition to specify how
to <TAB> should indent indent calls to the macro.  You write it like
this:

     (declare (indent INDENT-SPEC))

Here are the possibilities for INDENT-SPEC:

`nil'
     This is the same as no property--use the standard indentation
     pattern.

`defun'
     Handle this function like a `def' construct: treat the second line
     as the start of a "body".

an integer, NUMBER
     The first NUMBER arguments of the function are "distinguished"
     arguments; the rest are considered the body of the expression.  A
     line in the expression is indented according to whether the first
     argument on it is distinguished or not.  If the argument is part
     of the body, the line is indented `lisp-body-indent' more columns
     than the open-parenthesis starting the containing expression.  If
     the argument is distinguished and is either the first or second
     argument, it is indented _twice_ that many extra columns.  If the
     argument is distinguished and not the first or second argument,
     the line uses the standard pattern.

a symbol, SYMBOL
     SYMBOL should be a function name; that function is called to
     calculate the indentation of a line within this expression.  The
     function receives two arguments:
    STATE
          The value returned by `parse-partial-sexp' (a Lisp primitive
          for indentation and nesting computation) when it parses up to
          the beginning of this line.

    POS
          The position at which the line being indented begins.
     It should return either a number, which is the number of columns of
     indentation for that line, or a list whose car is such a number.
     The difference between returning a number and returning a list is
     that a number says that all following lines at the same nesting
     level should be indented just like this one; a list says that
     following lines might call for different indentations.  This makes
     a difference when the indentation is being computed by `C-M-q'; if
     the value is a number, `C-M-q' need not recalculate indentation
     for the following lines until the end of the list.

File: elisp,  Node: Customization,  Next: Loading,  Prev: Macros,  Up: Top

14 Writing Customization Definitions
************************************

This chapter describes how to declare user options for customization,
and also customization groups for classifying them.  We use the term
"customization item" to include both kinds of customization
definitions--as well as face definitions (*note Defining Faces::).

* Menu:

* Common Keywords::      Common keyword arguments for all kinds of
                           customization declarations.
* Group Definitions::    Writing customization group definitions.
* Variable Definitions:: Declaring user options.
* Customization Types::  Specifying the type of a user option.

File: elisp,  Node: Common Keywords,  Next: Group Definitions,  Up: Customization

14.1 Common Item Keywords
=========================

All kinds of customization declarations (for variables and groups, and
for faces) accept keyword arguments for specifying various information.
This section describes some keywords that apply to all kinds.

   All of these keywords, except `:tag', can be used more than once in
a given item.  Each use of the keyword has an independent effect.  The
keyword `:tag' is an exception because any given item can only display
one name.

`:tag LABEL'
     Use LABEL, a string, instead of the item's name, to label the item
     in customization menus and buffers.  *Don't use a tag which is
     substantially different from the item's real name; that would
     cause confusion.*

`:group GROUP'
     Put this customization item in group GROUP.  When you use `:group'
     in a `defgroup', it makes the new group a subgroup of GROUP.

     If you use this keyword more than once, you can put a single item
     into more than one group.  Displaying any of those groups will
     show this item.  Please don't overdo this, since the result would
     be annoying.

`:link LINK-DATA'
     Include an external link after the documentation string for this
     item.  This is a sentence containing an active field which
     references some other documentation.

     There are several alternatives you can use for LINK-DATA:

    `(custom-manual INFO-NODE)'
          Link to an Info node; INFO-NODE is a string which specifies
          the node name, as in `"(emacs)Top"'.  The link appears as
          `[Manual]' in the customization buffer and enters the built-in
          Info reader on INFO-NODE.

    `(info-link INFO-NODE)'
          Like `custom-manual' except that the link appears in the
          customization buffer with the Info node name.

    `(url-link URL)'
          Link to a web page; URL is a string which specifies the URL.
          The link appears in the customization buffer as URL and
          invokes the WWW browser specified by
          `browse-url-browser-function'.

    `(emacs-commentary-link LIBRARY)'
          Link to the commentary section of a library; LIBRARY is a
          string which specifies the library name.

    `(emacs-library-link LIBRARY)'
          Link to an Emacs Lisp library file; LIBRARY is a string which
          specifies the library name.

    `(file-link FILE)'
          Link to a file; FILE is a string which specifies the name of
          the file to visit with `find-file' when the user invokes this
          link.

    `(function-link FUNCTION)'
          Link to the documentation of a function; FUNCTION is a string
          which specifies the name of the function to describe with
          `describe-function' when the user invokes this link.

    `(variable-link VARIABLE)'
          Link to the documentation of a variable; VARIABLE is a string
          which specifies the name of the variable to describe with
          `describe-variable' when the user invokes this link.

    `(custom-group-link GROUP)'
          Link to another customization group.  Invoking it creates a
          new customization buffer for GROUP.

     You can specify the text to use in the customization buffer by
     adding `:tag NAME' after the first element of the LINK-DATA; for
     example, `(info-link :tag "foo" "(emacs)Top")' makes a link to the
     Emacs manual which appears in the buffer as `foo'.

     An item can have more than one external link; however, most items
     have none at all.

`:load FILE'
     Load file FILE (a string) before displaying this customization
     item.  Loading is done with `load-library', and only if the file is
     not already loaded.

`:require FEATURE'
     Execute `(require 'FEATURE)' when your saved customizations set
     the value of this item.  FEATURE should be a symbol.

     The most common reason to use `:require' is when a variable enables
     a feature such as a minor mode, and just setting the variable
     won't have any effect unless the code which implements the mode is
     loaded.

`:version VERSION'
     This keyword specifies that the item was first introduced in Emacs
     version VERSION, or that its default value was changed in that
     version.  The value VERSION must be a string.

`:package-version '(PACKAGE . VERSION)'
     This keyword specifies that the item was first introduced in
     PACKAGE version VERSION, or that its meaning or default value was
     changed in that version.  The value of PACKAGE is a symbol and
     VERSION is a string.

     This keyword takes priority over `:version'.

     PACKAGE should be the official name of the package, such as MH-E
     or Gnus.  If the package PACKAGE is released as part of Emacs,
     PACKAGE and VERSION should appear in the value of
     `customize-package-emacs-version-alist'.

   Packages distributed as part of Emacs that use the
`:package-version' keyword must also update the
`customize-package-emacs-version-alist' variable.

 -- Variable: customize-package-emacs-version-alist
     This alist provides a mapping for the versions of Emacs that are
     associated with versions of a package listed in the
     `:package-version' keyword.  Its elements look like this:

          (PACKAGE (PVERSION . EVERSION)...)

     For each PACKAGE, which is a symbol, there are one or more
     elements that contain a package version PVERSION with an
     associated Emacs version EVERSION.  These versions are strings.
     For example, the MH-E package updates this alist with the
     following:

          (add-to-list 'customize-package-emacs-version-alist
                       '(MH-E ("6.0" . "22.1") ("6.1" . "22.1") ("7.0" . "22.1")
                              ("7.1" . "22.1") ("7.2" . "22.1") ("7.3" . "22.1")
                              ("7.4" . "22.1") ("8.0" . "22.1")))

     The value of PACKAGE needs to be unique and it needs to match the
     PACKAGE value appearing in the `:package-version' keyword.  Since
     the user might see the value in a error message, a good choice is
     the official name of the package, such as MH-E or Gnus.

File: elisp,  Node: Group Definitions,  Next: Variable Definitions,  Prev: Common Keywords,  Up: Customization

14.2 Defining Customization Groups
==================================

Each Emacs Lisp package should have one main customization group which
contains all the options, faces and other groups in the package.  If the
package has a small number of options and faces, use just one group and
put everything in it.  When there are more than twelve or so options and
faces, then you should structure them into subgroups, and put the
subgroups under the package's main customization group.  It is OK to
put some of the options and faces in the package's main group alongside
the subgroups.

   The package's main or only group should be a member of one or more of
the standard customization groups.  (To display the full list of them,
use `M-x customize'.)  Choose one or more of them (but not too many),
and add your group to each of them using the `:group' keyword.

   The way to declare new customization groups is with `defgroup'.

 -- Macro: defgroup group members doc [keyword value]...
     Declare GROUP as a customization group containing MEMBERS.  Do not
     quote the symbol GROUP.  The argument DOC specifies the
     documentation string for the group.

     The argument MEMBERS is a list specifying an initial set of
     customization items to be members of the group.  However, most
     often MEMBERS is `nil', and you specify the group's members by
     using the `:group' keyword when defining those members.

     If you want to specify group members through MEMBERS, each element
     should have the form `(NAME WIDGET)'.  Here NAME is a symbol, and
     WIDGET is a widget type for editing that symbol.  Useful widgets
     are `custom-variable' for a variable, `custom-face' for a face,
     and `custom-group' for a group.

     When you introduce a new group into Emacs, use the `:version'
     keyword in the `defgroup'; then you need not use it for the
     individual members of the group.

     In addition to the common keywords (*note Common Keywords::), you
     can also use this keyword in `defgroup':

    `:prefix PREFIX'
          If the name of an item in the group starts with PREFIX, then
          the tag for that item is constructed (by default) by omitting
          PREFIX.

          One group can have any number of prefixes.

   The prefix-discarding feature is currently turned off, which means
that `:prefix' currently has no effect.  We did this because we found
that discarding the specified prefixes often led to confusing names for
options.  This happened because the people who wrote the `defgroup'
definitions for various groups added `:prefix' keywords whenever they
make logical sense--that is, whenever the variables in the library have
a common prefix.

   In order to obtain good results with `:prefix', it would be
necessary to check the specific effects of discarding a particular
prefix, given the specific items in a group and their names and
documentation.  If the resulting text is not clear, then `:prefix'
should not be used in that case.

   It should be possible to recheck all the customization groups, delete
the `:prefix' specifications which give unclear results, and then turn
this feature back on, if someone would like to do the work.

File: elisp,  Node: Variable Definitions,  Next: Customization Types,  Prev: Group Definitions,  Up: Customization

14.3 Defining Customization Variables
=====================================

Use `defcustom' to declare user-customizable variables.

 -- Macro: defcustom option standard doc [keyword value]...
     This macro declares OPTION as a customizable "user option".  You
     should not quote OPTION.

     This causes the function `user-variable-p' to return `t' when
     given OPTION as an argument.  *Note Defining Variables::.  The
     argument DOC specifies the documentation string for the variable.
     (Note that there is no need to start DOC with a `*'.)

     The argument STANDARD is an expression that specifies the standard
     value for OPTION.  Evaluating the `defcustom' form evaluates
     STANDARD, but does not necessarily install the standard value.  If
     OPTION already has a default value, `defcustom' does not change
     it.  If the user has saved a customization for OPTION, `defcustom'
     installs the user's customized value as OPTION's default value.
     If neither of those cases applies, `defcustom' installs the result
     of evaluating STANDARD as the default value.

     The expression STANDARD can be evaluated at various other times,
     too--whenever the customization facility needs to know OPTION's
     standard value.  So be sure to use an expression which is harmless
     to evaluate at any time.  We recommend avoiding backquotes in
     STANDARD, because they are not expanded when editing the value, so
     list values will appear to have the wrong structure.

     Every `defcustom' should specify `:group' at least once.

     If you specify the `:set' keyword, to make the variable take other
     special actions when set through the customization buffer, the
     variable's documentation string should tell the user specifically
     how to do the same job in hand-written Lisp code.

     When you evaluate a `defcustom' form with `C-M-x' in Emacs Lisp
     mode (`eval-defun'), a special feature of `eval-defun' arranges to
     set the variable unconditionally, without testing whether its
     value is void.  (The same feature applies to `defvar'.)  *Note
     Defining Variables::.

     If you put a `defcustom' in a file that is preloaded at dump time
     (*note Building Emacs::), and the standard value installed for the
     variable at that time might not be correct, use
     `custom-reevaluate-setting', described below, to re-evaluate the
     standard value during or after Emacs startup.

   `defcustom' accepts the following additional keywords:

`:type TYPE'
     Use TYPE as the data type for this option.  It specifies which
     values are legitimate, and how to display the value.  *Note
     Customization Types::, for more information.

`:options VALUE-LIST'
     Specify the list of reasonable values for use in this option.  The
     user is not restricted to using only these values, but they are
     offered as convenient alternatives.

     This is meaningful only for certain types, currently including
     `hook', `plist' and `alist'.  See the definition of the individual
     types for a description of how to use `:options'.

`:set SETFUNCTION'
     Specify SETFUNCTION as the way to change the value of this option.
     The function SETFUNCTION should take two arguments, a symbol (the
     option name) and the new value, and should do whatever is
     necessary to update the value properly for this option (which may
     not mean simply setting the option as a Lisp variable).  The
     default for SETFUNCTION is `set-default'.

`:get GETFUNCTION'
     Specify GETFUNCTION as the way to extract the value of this
     option.  The function GETFUNCTION should take one argument, a
     symbol, and should return whatever customize should use as the
     "current value" for that symbol (which need not be the symbol's
     Lisp value).  The default is `default-value'.

     You have to really understand the workings of Custom to use `:get'
     correctly.  It is meant for values that are treated in Custom as
     variables but are not actually stored in Lisp variables.  It is
     almost surely a mistake to specify `getfunction' for a value that
     really is stored in a Lisp variable.

`:initialize FUNCTION'
     FUNCTION should be a function used to initialize the variable when
     the `defcustom' is evaluated.  It should take two arguments, the
     option name (a symbol) and the value.  Here are some predefined
     functions meant for use in this way:

    `custom-initialize-set'
          Use the variable's `:set' function to initialize the
          variable, but do not reinitialize it if it is already
          non-void.

    `custom-initialize-default'
          Like `custom-initialize-set', but use the function
          `set-default' to set the variable, instead of the variable's
          `:set' function.  This is the usual choice for a variable
          whose `:set' function enables or disables a minor mode; with
          this choice, defining the variable will not call the minor
          mode function, but customizing the variable will do so.

    `custom-initialize-reset'
          Always use the `:set' function to initialize the variable.  If
          the variable is already non-void, reset it by calling the
          `:set' function using the current value (returned by the
          `:get' method).  This is the default `:initialize' function.

    `custom-initialize-changed'
          Use the `:set' function to initialize the variable, if it is
          already set or has been customized; otherwise, just use
          `set-default'.

    `custom-initialize-safe-set'
    `custom-initialize-safe-default'
          These functions behave like `custom-initialize-set'
          (`custom-initialize-default', respectively), but catch errors.
          If an error occurs during initialization, they set the
          variable to `nil' using `set-default', and throw no error.

          These two functions are only meant for options defined in
          pre-loaded files, where some variables or functions used to
          compute the option's value may not yet be defined.  The
          option normally gets updated in `startup.el', ignoring the
          previously computed value.  Because of this typical usage,
          the value which these two functions compute normally only
          matters when, after startup, one unsets the option's value
          and then reevaluates the defcustom.  By that time, the
          necessary variables and functions will be defined, so there
          will not be an error.

`:risky VALUE'
     Set the variable's `risky-local-variable' property to VALUE (*note
     File Local Variables::).

`:safe FUNCTION'
     Set the variable's `safe-local-variable' property to FUNCTION
     (*note File Local Variables::).

`:set-after VARIABLES'
     When setting variables according to saved customizations, make
     sure to set the variables VARIABLES before this one; in other
     words, delay setting this variable until after those others have
     been handled.  Use `:set-after' if setting this variable won't
     work properly unless those other variables already have their
     intended values.

   It is useful to specify the `:require' keyword for an option that
"turns on" a certain feature.  This causes Emacs to load the feature,
if it is not already loaded, whenever the option is set.  *Note Common
Keywords::.  Here is an example, from the library `saveplace.el':

     (defcustom save-place nil
       "Non-nil means automatically save place in each file..."
       :type 'boolean
       :require 'saveplace
       :group 'save-place)

   If a customization item has a type such as `hook' or `alist', which
supports `:options', you can add additional values to the list from
outside the `defcustom' declaration by calling
`custom-add-frequent-value'.  For example, if you define a function
`my-lisp-mode-initialization' intended to be called from
`emacs-lisp-mode-hook', you might want to add that to the list of
reasonable values for `emacs-lisp-mode-hook', but not by editing its
definition.  You can do it thus:

     (custom-add-frequent-value 'emacs-lisp-mode-hook
        'my-lisp-mode-initialization)

 -- Function: custom-add-frequent-value symbol value
     For the customization option SYMBOL, add VALUE to the list of
     reasonable values.

     The precise effect of adding a value depends on the customization
     type of SYMBOL.

   Internally, `defcustom' uses the symbol property `standard-value' to
record the expression for the standard value, `saved-value' to record
the value saved by the user with the customization buffer, and
`customized-value' to record the value set by the user with the
customization buffer, but not saved.  *Note Property Lists::.  These
properties are lists, the car of which is an expression that evaluates
to the value.

 -- Function: custom-reevaluate-setting symbol
     This function re-evaluates the standard value of SYMBOL, which
     should be a user option declared via `defcustom'.  (If the
     variable was customized, this function re-evaluates the saved value
     instead.)  This is useful for customizable options that are defined
     before their value could be computed correctly, such as variables
     defined in packages that are loaded at dump time, but depend on the
     run-time information.  For example, the value could be a file whose
     precise name depends on the hierarchy of files when Emacs runs, or
     a name of a program that needs to be searched at run time.

     A good place to put calls to this function is in the function
     `command-line' that is run during startup (*note Startup Summary::)
     or in the various hooks it calls.

File: elisp,  Node: Customization Types,  Prev: Variable Definitions,  Up: Customization

14.4 Customization Types
========================

When you define a user option with `defcustom', you must specify its
"customization type".  That is a Lisp object which describes (1) which
values are legitimate and (2) how to display the value in the
customization buffer for editing.

   You specify the customization type in `defcustom' with the `:type'
keyword.  The argument of `:type' is evaluated, but only once when the
`defcustom' is executed, so it isn't useful for the value to vary.
Normally we use a quoted constant.  For example:

     (defcustom diff-command "diff"
       "The command to use to run diff."
       :type '(string)
       :group 'diff)

   In general, a customization type is a list whose first element is a
symbol, one of the customization type names defined in the following
sections.  After this symbol come a number of arguments, depending on
the symbol.  Between the type symbol and its arguments, you can
optionally write keyword-value pairs (*note Type Keywords::).

   Some type symbols do not use any arguments; those are called "simple
types".  For a simple type, if you do not use any keyword-value pairs,
you can omit the parentheses around the type symbol.  For example just
`string' as a customization type is equivalent to `(string)'.

   All customization types are implemented as widgets; see *note
Introduction: (widget)Top, for details.

* Menu:

* Simple Types::            Simple customization types: sexp, integer, number,
                              string, file, directory, alist.
* Composite Types::         Build new types from other types or data.
* Splicing into Lists::     Splice elements into list with `:inline'.
* Type Keywords::           Keyword-argument pairs in a customization type.
* Defining New Types::      Give your type a name.

File: elisp,  Node: Simple Types,  Next: Composite Types,  Up: Customization Types

14.4.1 Simple Types
-------------------

This section describes all the simple customization types.

`sexp'
     The value may be any Lisp object that can be printed and read
     back.  You can use `sexp' as a fall-back for any option, if you
     don't want to take the time to work out a more specific type to
     use.

`integer'
     The value must be an integer, and is represented textually in the
     customization buffer.

`number'
     The value must be a number (floating point or integer), and is
     represented textually in the customization buffer.

`float'
     The value must be a floating point number, and is represented
     textually in the customization buffer.

`string'
     The value must be a string, and the customization buffer shows
     just the contents, with no delimiting `"' characters and no
     quoting with `\'.

`regexp'
     Like `string' except that the string must be a valid regular
     expression.

`character'
     The value must be a character code.  A character code is actually
     an integer, but this type shows the value by inserting the
     character in the buffer, rather than by showing the number.

`file'
     The value must be a file name, and you can do completion with
     `M-<TAB>'.

`(file :must-match t)'
     The value must be a file name for an existing file, and you can do
     completion with `M-<TAB>'.

`directory'
     The value must be a directory name, and you can do completion with
     `M-<TAB>'.

`hook'
     The value must be a list of functions (or a single function, but
     that is obsolete usage).  This customization type is used for hook
     variables.  You can use the `:options' keyword in a hook variable's
     `defcustom' to specify a list of functions recommended for use in
     the hook; see *note Variable Definitions::.

`alist'
     The value must be a list of cons-cells, the CAR of each cell
     representing a key, and the CDR of the same cell representing an
     associated value.  The user can add and delete key/value pairs, and
     edit both the key and the value of each pair.

     You can specify the key and value types like this:

          (alist :key-type KEY-TYPE :value-type VALUE-TYPE)

     where KEY-TYPE and VALUE-TYPE are customization type
     specifications.  The default key type is `sexp', and the default
     value type is `sexp'.

     The user can add any key matching the specified key type, but you
     can give some keys a preferential treatment by specifying them
     with the `:options' (see *note Variable Definitions::).  The
     specified keys will always be shown in the customize buffer
     (together with a suitable value), with a checkbox to include or
     exclude or disable the key/value pair from the alist.  The user
     will not be able to edit the keys specified by the `:options'
     keyword argument.

     The argument to the `:options' keywords should be a list of
     specifications for reasonable keys in the alist.  Ordinarily, they
     are simply atoms, which stand for themselves as.  For example:

          :options '("foo" "bar" "baz")

     specifies that there are three "known" keys, namely `"foo"',
     `"bar"' and `"baz"', which will always be shown first.

     You may want to restrict the value type for specific keys, for
     example, the value associated with the `"bar"' key can only be an
     integer.  You can specify this by using a list instead of an atom
     in the list.  The first element will specify the key, like before,
     while the second element will specify the value type.  For example:

          :options '("foo" ("bar" integer) "baz")

     Finally, you may want to change how the key is presented.  By
     default, the key is simply shown as a `const', since the user
     cannot change the special keys specified with the `:options'
     keyword.  However, you may want to use a more specialized type for
     presenting the key, like `function-item' if you know it is a
     symbol with a function binding.  This is done by using a
     customization type specification instead of a symbol for the key.

          :options '("foo" ((function-item some-function) integer)
                     "baz")

     Many alists use lists with two elements, instead of cons cells.
     For example,

          (defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
            "Each element is a list of the form (KEY VALUE).")

     instead of

          (defcustom cons-alist '(("foo" . 1) ("bar" . 2) ("baz" . 3))
            "Each element is a cons-cell (KEY . VALUE).")

     Because of the way lists are implemented on top of cons cells, you
     can treat `list-alist' in the example above as a cons cell alist,
     where the value type is a list with a single element containing
     the real value.

          (defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
            "Each element is a list of the form (KEY VALUE)."
            :type '(alist :value-type (group integer)))

     The `group' widget is used here instead of `list' only because the
     formatting is better suited for the purpose.

     Similarly, you can have alists with more values associated with
     each key, using variations of this trick:

          (defcustom person-data '(("brian"  50 t)
                                   ("dorith" 55 nil)
                                   ("ken"    52 t))
            "Alist of basic info about people.
          Each element has the form (NAME AGE MALE-FLAG)."
            :type '(alist :value-type (group integer boolean)))

          (defcustom pets '(("brian")
                            ("dorith" "dog" "guppy")
                            ("ken" "cat"))
            "Alist of people's pets.
          In an element (KEY . VALUE), KEY is the person's name,
          and the VALUE is a list of that person's pets."
            :type '(alist :value-type (repeat string)))

`plist'
     The `plist' custom type is similar to the `alist' (see above),
     except that the information is stored as a property list, i.e. a
     list of this form:

          (KEY VALUE KEY VALUE KEY VALUE ...)

     The default `:key-type' for `plist' is `symbol', rather than
     `sexp'.

`symbol'
     The value must be a symbol.  It appears in the customization
     buffer as the name of the symbol.

`function'
     The value must be either a lambda expression or a function name.
     When it is a function name, you can do completion with `M-<TAB>'.

`variable'
     The value must be a variable name, and you can do completion with
     `M-<TAB>'.

`face'
     The value must be a symbol which is a face name, and you can do
     completion with `M-<TAB>'.

`boolean'
     The value is boolean--either `nil' or `t'.  Note that by using
     `choice' and `const' together (see the next section), you can
     specify that the value must be `nil' or `t', but also specify the
     text to describe each value in a way that fits the specific
     meaning of the alternative.

`coding-system'
     The value must be a coding-system name, and you can do completion
     with `M-<TAB>'.

`color'
     The value must be a valid color name, and you can do completion
     with `M-<TAB>'.  A sample is provided.

File: elisp,  Node: Composite Types,  Next: Splicing into Lists,  Prev: Simple Types,  Up: Customization Types

14.4.2 Composite Types
----------------------

When none of the simple types is appropriate, you can use composite
types, which build new types from other types or from specified data.
The specified types or data are called the "arguments" of the composite
type.  The composite type normally looks like this:

     (CONSTRUCTOR ARGUMENTS...)

but you can also add keyword-value pairs before the arguments, like
this:

     (CONSTRUCTOR {KEYWORD VALUE}... ARGUMENTS...)

   Here is a table of constructors and how to use them to write
composite types:

`(cons CAR-TYPE CDR-TYPE)'
     The value must be a cons cell, its CAR must fit CAR-TYPE, and its
     CDR must fit CDR-TYPE.  For example, `(cons string symbol)' is a
     customization type which matches values such as `("foo" . foo)'.

     In the customization buffer, the CAR and the CDR are displayed and
     edited separately, each according to the type that you specify for
     it.

`(list ELEMENT-TYPES...)'
     The value must be a list with exactly as many elements as the
     ELEMENT-TYPES given; and each element must fit the corresponding
     ELEMENT-TYPE.

     For example, `(list integer string function)' describes a list of
     three elements; the first element must be an integer, the second a
     string, and the third a function.

     In the customization buffer, each element is displayed and edited
     separately, according to the type specified for it.

`(group ELEMENT-TYPES...)'
     This works like `list' except for the formatting of text in the
     Custom buffer.  `list' labels each element value with its tag;
     `group' does not.

`(vector ELEMENT-TYPES...)'
     Like `list' except that the value must be a vector instead of a
     list.  The elements work the same as in `list'.

`(choice ALTERNATIVE-TYPES...)'
     The value must fit at least one of ALTERNATIVE-TYPES.  For
     example, `(choice integer string)' allows either an integer or a
     string.

     In the customization buffer, the user selects an alternative using
     a menu, and can then edit the value in the usual way for that
     alternative.

     Normally the strings in this menu are determined automatically
     from the choices; however, you can specify different strings for
     the menu by including the `:tag' keyword in the alternatives.  For
     example, if an integer stands for a number of spaces, while a
     string is text to use verbatim, you might write the customization
     type this way,

          (choice (integer :tag "Number of spaces")
                  (string :tag "Literal text"))

     so that the menu offers `Number of spaces' and `Literal text'.

     In any alternative for which `nil' is not a valid value, other than
     a `const', you should specify a valid default for that alternative
     using the `:value' keyword.  *Note Type Keywords::.

     If some values are covered by more than one of the alternatives,
     customize will choose the first alternative that the value fits.
     This means you should always list the most specific types first,
     and the most general last.  Here's an example of proper usage:

          (choice (const :tag "Off" nil)
                  symbol (sexp :tag "Other"))

     This way, the special value `nil' is not treated like other
     symbols, and symbols are not treated like other Lisp expressions.

`(radio ELEMENT-TYPES...)'
     This is similar to `choice', except that the choices are displayed
     using `radio buttons' rather than a menu.  This has the advantage
     of displaying documentation for the choices when applicable and so
     is often a good choice for a choice between constant functions
     (`function-item' customization types).

`(const VALUE)'
     The value must be VALUE--nothing else is allowed.

     The main use of `const' is inside of `choice'.  For example,
     `(choice integer (const nil))' allows either an integer or `nil'.

     `:tag' is often used with `const', inside of `choice'.  For
     example,

          (choice (const :tag "Yes" t)
                  (const :tag "No" nil)
                  (const :tag "Ask" foo))

     describes a variable for which `t' means yes, `nil' means no, and
     `foo' means "ask."

`(other VALUE)'
     This alternative can match any Lisp value, but if the user chooses
     this alternative, that selects the value VALUE.

     The main use of `other' is as the last element of `choice'.  For
     example,

          (choice (const :tag "Yes" t)
                  (const :tag "No" nil)
                  (other :tag "Ask" foo))

     describes a variable for which `t' means yes, `nil' means no, and
     anything else means "ask."  If the user chooses `Ask' from the
     menu of alternatives, that specifies the value `foo'; but any
     other value (not `t', `nil' or `foo') displays as `Ask', just like
     `foo'.

`(function-item FUNCTION)'
     Like `const', but used for values which are functions.  This
     displays the documentation string as well as the function name.
     The documentation string is either the one you specify with
     `:doc', or FUNCTION's own documentation string.

`(variable-item VARIABLE)'
     Like `const', but used for values which are variable names.  This
     displays the documentation string as well as the variable name.
     The documentation string is either the one you specify with
     `:doc', or VARIABLE's own documentation string.

`(set TYPES...)'
     The value must be a list, and each element of the list must match
     one of the TYPES specified.

     This appears in the customization buffer as a checklist, so that
     each of TYPES may have either one corresponding element or none.
     It is not possible to specify two different elements that match
     the same one of TYPES.  For example, `(set integer symbol)' allows
     one integer and/or one symbol in the list; it does not allow
     multiple integers or multiple symbols.  As a result, it is rare to
     use nonspecific types such as `integer' in a `set'.

     Most often, the TYPES in a `set' are `const' types, as shown here:

          (set (const :bold) (const :italic))

     Sometimes they describe possible elements in an alist:

          (set (cons :tag "Height" (const height) integer)
               (cons :tag "Width" (const width) integer))

     That lets the user specify a height value optionally and a width
     value optionally.

`(repeat ELEMENT-TYPE)'
     The value must be a list and each element of the list must fit the
     type ELEMENT-TYPE.  This appears in the customization buffer as a
     list of elements, with `[INS]' and `[DEL]' buttons for adding more
     elements or removing elements.

`(restricted-sexp :match-alternatives CRITERIA)'
     This is the most general composite type construct.  The value may
     be any Lisp object that satisfies one of CRITERIA.  CRITERIA
     should be a list, and each element should be one of these
     possibilities:

        * A predicate--that is, a function of one argument that has no
          side effects, and returns either `nil' or non-`nil' according
          to the argument.  Using a predicate in the list says that
          objects for which the predicate returns non-`nil' are
          acceptable.

        * A quoted constant--that is, `'OBJECT'.  This sort of element
          in the list says that OBJECT itself is an acceptable value.

     For example,

          (restricted-sexp :match-alternatives
                           (integerp 't 'nil))

     allows integers, `t' and `nil' as legitimate values.

     The customization buffer shows all legitimate values using their
     read syntax, and the user edits them textually.

   Here is a table of the keywords you can use in keyword-value pairs
in a composite type:

`:tag TAG'
     Use TAG as the name of this alternative, for user communication
     purposes.  This is useful for a type that appears inside of a
     `choice'.

`:match-alternatives CRITERIA'
     Use CRITERIA to match possible values.  This is used only in
     `restricted-sexp'.

`:args ARGUMENT-LIST'
     Use the elements of ARGUMENT-LIST as the arguments of the type
     construct.  For instance, `(const :args (foo))' is equivalent to
     `(const foo)'.  You rarely need to write `:args' explicitly,
     because normally the arguments are recognized automatically as
     whatever follows the last keyword-value pair.

File: elisp,  Node: Splicing into Lists,  Next: Type Keywords,  Prev: Composite Types,  Up: Customization Types

14.4.3 Splicing into Lists
--------------------------

The `:inline' feature lets you splice a variable number of elements
into the middle of a list or vector.  You use it in a `set', `choice'
or `repeat' type which appears among the element-types of a `list' or
`vector'.

   Normally, each of the element-types in a `list' or `vector'
describes one and only one element of the list or vector.  Thus, if an
element-type is a `repeat', that specifies a list of unspecified length
which appears as one element.

   But when the element-type uses `:inline', the value it matches is
merged directly into the containing sequence.  For example, if it
matches a list with three elements, those become three elements of the
overall sequence.  This is analogous to using `,@' in the backquote
construct.

   For example, to specify a list whose first element must be `baz' and
whose remaining arguments should be zero or more of `foo' and `bar',
use this customization type:

     (list (const baz) (set :inline t (const foo) (const bar)))

This matches values such as `(baz)', `(baz foo)', `(baz bar)' and `(baz
foo bar)'.

   When the element-type is a `choice', you use `:inline' not in the
`choice' itself, but in (some of) the alternatives of the `choice'.
For example, to match a list which must start with a file name,
followed either by the symbol `t' or two strings, use this
customization type:

     (list file
           (choice (const t)
                   (list :inline t string string)))

If the user chooses the first alternative in the choice, then the
overall list has two elements and the second element is `t'.  If the
user chooses the second alternative, then the overall list has three
elements and the second and third must be strings.

File: elisp,  Node: Type Keywords,  Next: Defining New Types,  Prev: Splicing into Lists,  Up: Customization Types

14.4.4 Type Keywords
--------------------

You can specify keyword-argument pairs in a customization type after the
type name symbol.  Here are the keywords you can use, and their
meanings:

`:value DEFAULT'
     This is used for a type that appears as an alternative inside of
     `choice'; it specifies the default value to use, at first, if and
     when the user selects this alternative with the menu in the
     customization buffer.

     Of course, if the actual value of the option fits this
     alternative, it will appear showing the actual value, not DEFAULT.

     If `nil' is not a valid value for the alternative, then it is
     essential to specify a valid default with `:value'.

`:format FORMAT-STRING'
     This string will be inserted in the buffer to represent the value
     corresponding to the type.  The following `%' escapes are available
     for use in FORMAT-STRING:

    `%[BUTTON%]'
          Display the text BUTTON marked as a button.  The `:action'
          attribute specifies what the button will do if the user
          invokes it; its value is a function which takes two
          arguments--the widget which the button appears in, and the
          event.

          There is no way to specify two different buttons with
          different actions.

    `%{SAMPLE%}'
          Show SAMPLE in a special face specified by `:sample-face'.

    `%v'
          Substitute the item's value.  How the value is represented
          depends on the kind of item, and (for variables) on the
          customization type.

    `%d'
          Substitute the item's documentation string.

    `%h'
          Like `%d', but if the documentation string is more than one
          line, add an active field to control whether to show all of
          it or just the first line.

    `%t'
          Substitute the tag here.  You specify the tag with the `:tag'
          keyword.

    `%%'
          Display a literal `%'.

`:action ACTION'
     Perform ACTION if the user clicks on a button.

`:button-face FACE'
     Use the face FACE (a face name or a list of face names) for button
     text displayed with `%[...%]'.

`:button-prefix PREFIX'
`:button-suffix SUFFIX'
     These specify the text to display before and after a button.  Each
     can be:

    `nil'
          No text is inserted.

    a string
          The string is inserted literally.

    a symbol
          The symbol's value is used.

`:tag TAG'
     Use TAG (a string) as the tag for the value (or part of the value)
     that corresponds to this type.

`:doc DOC'
     Use DOC as the documentation string for this value (or part of the
     value) that corresponds to this type.  In order for this to work,
     you must specify a value for `:format', and use `%d' or `%h' in
     that value.

     The usual reason to specify a documentation string for a type is to
     provide more information about the meanings of alternatives inside
     a `:choice' type or the parts of some other composite type.

`:help-echo MOTION-DOC'
     When you move to this item with `widget-forward' or
     `widget-backward', it will display the string MOTION-DOC in the
     echo area.  In addition, MOTION-DOC is used as the mouse
     `help-echo' string and may actually be a function or form evaluated
     to yield a help string.  If it is a function, it is called with one
     argument, the widget.

`:match FUNCTION'
     Specify how to decide whether a value matches the type.  The
     corresponding value, FUNCTION, should be a function that accepts
     two arguments, a widget and a value; it should return non-`nil' if
     the value is acceptable.

`:validate FUNCTION'
     Specify a validation function for input.  FUNCTION takes a widget
     as an argument, and should return `nil' if the widget's current
     value is valid for the widget.  Otherwise, it should return the
     widget containing the invalid data, and set that widget's `:error'
     property to a string explaining the error.


File: elisp,  Node: Defining New Types,  Prev: Type Keywords,  Up: Customization Types

14.4.5 Defining New Types
-------------------------

In the previous sections we have described how to construct elaborate
type specifications for `defcustom'.  In some cases you may want to
give such a type specification a name.  The obvious case is when you
are using the same type for many user options: rather than repeat the
specification for each option, you can give the type specification a
name, and use that name each `defcustom'.  The other case is when a
user option's value is a recursive data structure.  To make it possible
for a datatype to refer to itself, it needs to have a name.

   Since custom types are implemented as widgets, the way to define a
new customize type is to define a new widget.  We are not going to
describe the widget interface here in details, see *note Introduction:
(widget)Top, for that.  Instead we are going to demonstrate the minimal
functionality needed for defining new customize types by a simple
example.

     (define-widget 'binary-tree-of-string 'lazy
       "A binary tree made of cons-cells and strings."
       :offset 4
       :tag "Node"
       :type '(choice (string :tag "Leaf" :value "")
                      (cons :tag "Interior"
                            :value ("" . "")
                            binary-tree-of-string
                            binary-tree-of-string)))

     (defcustom foo-bar ""
       "Sample variable holding a binary tree of strings."
       :type 'binary-tree-of-string)

   The function to define a new widget is called `define-widget'.  The
first argument is the symbol we want to make a new widget type.  The
second argument is a symbol representing an existing widget, the new
widget is going to be defined in terms of difference from the existing
widget.  For the purpose of defining new customization types, the
`lazy' widget is perfect, because it accepts a `:type' keyword argument
with the same syntax as the keyword argument to `defcustom' with the
same name.  The third argument is a documentation string for the new
widget.  You will be able to see that string with the `M-x
widget-browse <RET> binary-tree-of-string <RET>' command.

   After these mandatory arguments follow the keyword arguments.  The
most important is `:type', which describes the data type we want to
match with this widget.  Here a `binary-tree-of-string' is described as
being either a string, or a cons-cell whose car and cdr are themselves
both `binary-tree-of-string'.  Note the reference to the widget type we
are currently in the process of defining.  The `:tag' attribute is a
string to name the widget in the user interface, and the `:offset'
argument is there to ensure that child nodes are indented four spaces
relative to the parent node, making the tree structure apparent in the
customization buffer.

   The `defcustom' shows how the new widget can be used as an ordinary
customization type.

   The reason for the name `lazy' is that the other composite widgets
convert their inferior widgets to internal form when the widget is
instantiated in a buffer.  This conversion is recursive, so the
inferior widgets will convert _their_ inferior widgets.  If the data
structure is itself recursive, this conversion is an infinite
recursion.  The `lazy' widget prevents the recursion: it convert its
`:type' argument only when needed.

File: elisp,  Node: Loading,  Next: Byte Compilation,  Prev: Customization,  Up: Top

15 Loading
**********

Loading a file of Lisp code means bringing its contents into the Lisp
environment in the form of Lisp objects.  Emacs finds and opens the
file, reads the text, evaluates each form, and then closes the file.

   The load functions evaluate all the expressions in a file just as
the `eval-buffer' function evaluates all the expressions in a buffer.
The difference is that the load functions read and evaluate the text in
the file as found on disk, not the text in an Emacs buffer.

   The loaded file must contain Lisp expressions, either as source code
or as byte-compiled code.  Each form in the file is called a "top-level
form".  There is no special format for the forms in a loadable file;
any form in a file may equally well be typed directly into a buffer and
evaluated there.  (Indeed, most code is tested this way.)  Most often,
the forms are function definitions and variable definitions.

   A file containing Lisp code is often called a "library".  Thus, the
"Rmail library" is a file containing code for Rmail mode.  Similarly, a
"Lisp library directory" is a directory of files containing Lisp code.

* Menu:

* How Programs Do Loading:: The `load' function and others.
* Load Suffixes::           Details about the suffixes that `load' tries.
* Library Search::          Finding a library to load.
* Loading Non-ASCII::       Non-ASCII characters in Emacs Lisp files.
* Autoload::                Setting up a function to autoload.
* Repeated Loading::        Precautions about loading a file twice.
* Named Features::          Loading a library if it isn't already loaded.
* Where Defined::           Finding which file defined a certain symbol.
* Unloading::		    How to "unload" a library that was loaded.
* Hooks for Loading::	    Providing code to be run when
			      particular libraries are loaded.

File: elisp,  Node: How Programs Do Loading,  Next: Load Suffixes,  Up: Loading

15.1 How Programs Do Loading
============================

Emacs Lisp has several interfaces for loading.  For example, `autoload'
creates a placeholder object for a function defined in a file; trying
to call the autoloading function loads the file to get the function's
real definition (*note Autoload::).  `require' loads a file if it isn't
already loaded (*note Named Features::).  Ultimately, all these
facilities call the `load' function to do the work.

 -- Function: load filename &optional missing-ok nomessage nosuffix
          must-suffix
     This function finds and opens a file of Lisp code, evaluates all
     the forms in it, and closes the file.

     To find the file, `load' first looks for a file named
     `FILENAME.elc', that is, for a file whose name is FILENAME with
     the extension `.elc' appended.  If such a file exists, it is
     loaded.  If there is no file by that name, then `load' looks for a
     file named `FILENAME.el'.  If that file exists, it is loaded.
     Finally, if neither of those names is found, `load' looks for a
     file named FILENAME with nothing appended, and loads it if it
     exists.  (The `load' function is not clever about looking at
     FILENAME.  In the perverse case of a file named `foo.el.el',
     evaluation of `(load "foo.el")' will indeed find it.)

     If Auto Compression mode is enabled, as it is by default, then if
     `load' can not find a file, it searches for a compressed version
     of the file before trying other file names.  It decompresses and
     loads it if it exists.  It looks for compressed versions by
     appending each of the suffixes in `jka-compr-load-suffixes' to the
     file name.  The value of this variable must be a list of strings.
     Its standard value is `(".gz")'.

     If the optional argument NOSUFFIX is non-`nil', then `load' does
     not try the suffixes `.elc' and `.el'.  In this case, you must
     specify the precise file name you want, except that, if Auto
     Compression mode is enabled, `load' will still use
     `jka-compr-load-suffixes' to find compressed versions.  By
     specifying the precise file name and using `t' for NOSUFFIX, you
     can prevent perverse file names such as `foo.el.el' from being
     tried.

     If the optional argument MUST-SUFFIX is non-`nil', then `load'
     insists that the file name used must end in either `.el' or `.elc'
     (possibly extended with a compression suffix), unless it contains
     an explicit directory name.

     If FILENAME is a relative file name, such as `foo' or
     `baz/foo.bar', `load' searches for the file using the variable
     `load-path'.  It appends FILENAME to each of the directories
     listed in `load-path', and loads the first file it finds whose name
     matches.  The current default directory is tried only if it is
     specified in `load-path', where `nil' stands for the default
     directory.  `load' tries all three possible suffixes in the first
     directory in `load-path', then all three suffixes in the second
     directory, and so on.  *Note Library Search::.

     If you get a warning that `foo.elc' is older than `foo.el', it
     means you should consider recompiling `foo.el'.  *Note Byte
     Compilation::.

     When loading a source file (not compiled), `load' performs
     character set translation just as Emacs would do when visiting the
     file.  *Note Coding Systems::.

     Messages like `Loading foo...' and `Loading foo...done' appear in
     the echo area during loading unless NOMESSAGE is non-`nil'.

     Any unhandled errors while loading a file terminate loading.  If
     the load was done for the sake of `autoload', any function
     definitions made during the loading are undone.

     If `load' can't find the file to load, then normally it signals the
     error `file-error' (with `Cannot open load file FILENAME').  But
     if MISSING-OK is non-`nil', then `load' just returns `nil'.

     You can use the variable `load-read-function' to specify a function
     for `load' to use instead of `read' for reading expressions.  See
     below.

     `load' returns `t' if the file loads successfully.

 -- Command: load-file filename
     This command loads the file FILENAME.  If FILENAME is a relative
     file name, then the current default directory is assumed.  This
     command does not use `load-path', and does not append suffixes.
     However, it does look for compressed versions (if Auto Compression
     Mode is enabled).  Use this command if you wish to specify
     precisely the file name to load.

 -- Command: load-library library
     This command loads the library named LIBRARY.  It is equivalent to
     `load', except in how it reads its argument interactively.

 -- Variable: load-in-progress
     This variable is non-`nil' if Emacs is in the process of loading a
     file, and it is `nil' otherwise.

 -- Variable: load-read-function
     This variable specifies an alternate expression-reading function
     for `load' and `eval-region' to use instead of `read'.  The
     function should accept one argument, just as `read' does.

     Normally, the variable's value is `nil', which means those
     functions should use `read'.

     Instead of using this variable, it is cleaner to use another, newer
     feature: to pass the function as the READ-FUNCTION argument to
     `eval-region'.  *Note Eval: Definition of eval-region.

   For information about how `load' is used in building Emacs, see
*note Building Emacs::.

File: elisp,  Node: Load Suffixes,  Next: Library Search,  Prev: How Programs Do Loading,  Up: Loading

15.2 Load Suffixes
==================

We now describe some technical details about the exact suffixes that
`load' tries.

 -- Variable: load-suffixes
     This is a list of suffixes indicating (compiled or source) Emacs
     Lisp files.  It should not include the empty string.  `load' uses
     these suffixes in order when it appends Lisp suffixes to the
     specified file name.  The standard value is `(".elc" ".el")' which
     produces the behavior described in the previous section.

 -- Variable: load-file-rep-suffixes
     This is a list of suffixes that indicate representations of the
     same file.  This list should normally start with the empty string.
     When `load' searches for a file it appends the suffixes in this
     list, in order, to the file name, before searching for another
     file.

     Enabling Auto Compression mode appends the suffixes in
     `jka-compr-load-suffixes' to this list and disabling Auto
     Compression mode removes them again.  The standard value of
     `load-file-rep-suffixes' if Auto Compression mode is disabled is
     `("")'.  Given that the standard value of
     `jka-compr-load-suffixes' is `(".gz")', the standard value of
     `load-file-rep-suffixes' if Auto Compression mode is enabled is
     `("" ".gz")'.

 -- Function: get-load-suffixes
     This function returns the list of all suffixes that `load' should
     try, in order, when its MUST-SUFFIX argument is non-`nil'.  This
     takes both `load-suffixes' and `load-file-rep-suffixes' into
     account.  If `load-suffixes', `jka-compr-load-suffixes' and
     `load-file-rep-suffixes' all have their standard values, this
     function returns `(".elc" ".elc.gz" ".el" ".el.gz")' if Auto
     Compression mode is enabled and `(".elc" ".el")' if Auto
     Compression mode is disabled.

   To summarize, `load' normally first tries the suffixes in the value
of `(get-load-suffixes)' and then those in `load-file-rep-suffixes'.
If NOSUFFIX is non-`nil', it skips the former group, and if MUST-SUFFIX
is non-`nil', it skips the latter group.

File: elisp,  Node: Library Search,  Next: Loading Non-ASCII,  Prev: Load Suffixes,  Up: Loading

15.3 Library Search
===================

When Emacs loads a Lisp library, it searches for the library in a list
of directories specified by the variable `load-path'.

 -- User Option: load-path
     The value of this variable is a list of directories to search when
     loading files with `load'.  Each element is a string (which must be
     a directory name) or `nil' (which stands for the current working
     directory).

   The value of `load-path' is initialized from the environment
variable `EMACSLOADPATH', if that exists; otherwise its default value
is specified in `emacs/src/epaths.h' when Emacs is built.  Then the
list is expanded by adding subdirectories of the directories in the
list.

   The syntax of `EMACSLOADPATH' is the same as used for `PATH'; `:'
(or `;', according to the operating system) separates directory names,
and `.' is used for the current default directory.  Here is an example
of how to set your `EMACSLOADPATH' variable from a `csh' `.login' file:

     setenv EMACSLOADPATH .:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp

   Here is how to set it using `sh':

     export EMACSLOADPATH
     EMACSLOADPATH=.:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp

   Here is an example of code you can place in your init file (*note
Init File::) to add several directories to the front of your default
`load-path':

     (setq load-path
           (append (list nil "/user/bil/emacs"
                         "/usr/local/lisplib"
                         "~/emacs")
                   load-path))

In this example, the path searches the current working directory first,
followed then by the `/user/bil/emacs' directory, the
`/usr/local/lisplib' directory, and the `~/emacs' directory, which are
then followed by the standard directories for Lisp code.

   Dumping Emacs uses a special value of `load-path'.  If the value of
`load-path' at the end of dumping is unchanged (that is, still the same
special value), the dumped Emacs switches to the ordinary `load-path'
value when it starts up, as described above.  But if `load-path' has
any other value at the end of dumping, that value is used for execution
of the dumped Emacs also.

   Therefore, if you want to change `load-path' temporarily for loading
a few libraries in `site-init.el' or `site-load.el', you should bind
`load-path' locally with `let' around the calls to `load'.

   The default value of `load-path', when running an Emacs which has
been installed on the system, includes two special directories (and
their subdirectories as well):

     "/usr/local/share/emacs/VERSION/site-lisp"

and

     "/usr/local/share/emacs/site-lisp"

The first one is for locally installed packages for a particular Emacs
version; the second is for locally installed packages meant for use with
all installed Emacs versions.

   There are several reasons why a Lisp package that works well in one
Emacs version can cause trouble in another.  Sometimes packages need
updating for incompatible changes in Emacs; sometimes they depend on
undocumented internal Emacs data that can change without notice;
sometimes a newer Emacs version incorporates a version of the package,
and should be used only with that version.

   Emacs finds these directories' subdirectories and adds them to
`load-path' when it starts up.  Both immediate subdirectories and
subdirectories multiple levels down are added to `load-path'.

   Not all subdirectories are included, though.  Subdirectories whose
names do not start with a letter or digit are excluded.  Subdirectories
named `RCS' or `CVS' are excluded.  Also, a subdirectory which contains
a file named `.nosearch' is excluded.  You can use these methods to
prevent certain subdirectories of the `site-lisp' directories from
being searched.

   If you run Emacs from the directory where it was built--that is, an
executable that has not been formally installed--then `load-path'
normally contains two additional directories.  These are the `lisp' and
`site-lisp' subdirectories of the main build directory.  (Both are
represented as absolute file names.)

 -- Command: locate-library library &optional nosuffix path
          interactive-call
     This command finds the precise file name for library LIBRARY.  It
     searches for the library in the same way `load' does, and the
     argument NOSUFFIX has the same meaning as in `load': don't add
     suffixes `.elc' or `.el' to the specified name LIBRARY.

     If the PATH is non-`nil', that list of directories is used instead
     of `load-path'.

     When `locate-library' is called from a program, it returns the file
     name as a string.  When the user runs `locate-library'
     interactively, the argument INTERACTIVE-CALL is `t', and this
     tells `locate-library' to display the file name in the echo area.

File: elisp,  Node: Loading Non-ASCII,  Next: Autoload,  Prev: Library Search,  Up: Loading

15.4 Loading Non-ASCII Characters
=================================

When Emacs Lisp programs contain string constants with non-ASCII
characters, these can be represented within Emacs either as unibyte
strings or as multibyte strings (*note Text Representations::).  Which
representation is used depends on how the file is read into Emacs.  If
it is read with decoding into multibyte representation, the text of the
Lisp program will be multibyte text, and its string constants will be
multibyte strings.  If a file containing Latin-1 characters (for
example) is read without decoding, the text of the program will be
unibyte text, and its string constants will be unibyte strings.  *Note
Coding Systems::.

   To make the results more predictable, Emacs always performs decoding
into the multibyte representation when loading Lisp files, even if it
was started with the `--unibyte' option.  This means that string
constants with non-ASCII characters translate into multibyte strings.
The only exception is when a particular file specifies no decoding.

   The reason Emacs is designed this way is so that Lisp programs give
predictable results, regardless of how Emacs was started.  In addition,
this enables programs that depend on using multibyte text to work even
in a unibyte Emacs.  Of course, such programs should be designed to
notice whether the user prefers unibyte or multibyte text, by checking
`default-enable-multibyte-characters', and convert representations
appropriately.

   In most Emacs Lisp programs, the fact that non-ASCII strings are
multibyte strings should not be noticeable, since inserting them in
unibyte buffers converts them to unibyte automatically.  However, if
this does make a difference, you can force a particular Lisp file to be
interpreted as unibyte by writing `-*-unibyte: t;-*-' in a comment on
the file's first line.  With that designator, the file will
unconditionally be interpreted as unibyte, even in an ordinary
multibyte Emacs session.  This can matter when making keybindings to
non-ASCII characters written as `?vLITERAL'.

File: elisp,  Node: Autoload,  Next: Repeated Loading,  Prev: Loading Non-ASCII,  Up: Loading

15.5 Autoload
=============

The "autoload" facility allows you to make a function or macro known in
Lisp, but put off loading the file that defines it.  The first call to
the function automatically reads the proper file to install the real
definition and other associated code, then runs the real definition as
if it had been loaded all along.

   There are two ways to set up an autoloaded function: by calling
`autoload', and by writing a special "magic" comment in the source
before the real definition.  `autoload' is the low-level primitive for
autoloading; any Lisp program can call `autoload' at any time.  Magic
comments are the most convenient way to make a function autoload, for
packages installed along with Emacs.  These comments do nothing on
their own, but they serve as a guide for the command
`update-file-autoloads', which constructs calls to `autoload' and
arranges to execute them when Emacs is built.

 -- Function: autoload function filename &optional docstring
          interactive type
     This function defines the function (or macro) named FUNCTION so as
     to load automatically from FILENAME.  The string FILENAME
     specifies the file to load to get the real definition of FUNCTION.

     If FILENAME does not contain either a directory name, or the
     suffix `.el' or `.elc', then `autoload' insists on adding one of
     these suffixes, and it will not load from a file whose name is
     just FILENAME with no added suffix.  (The variable `load-suffixes'
     specifies the exact required suffixes.)

     The argument DOCSTRING is the documentation string for the
     function.  Specifying the documentation string in the call to
     `autoload' makes it possible to look at the documentation without
     loading the function's real definition.  Normally, this should be
     identical to the documentation string in the function definition
     itself.  If it isn't, the function definition's documentation
     string takes effect when it is loaded.

     If INTERACTIVE is non-`nil', that says FUNCTION can be called
     interactively.  This lets completion in `M-x' work without loading
     FUNCTION's real definition.  The complete interactive
     specification is not given here; it's not needed unless the user
     actually calls FUNCTION, and when that happens, it's time to load
     the real definition.

     You can autoload macros and keymaps as well as ordinary functions.
     Specify TYPE as `macro' if FUNCTION is really a macro.  Specify
     TYPE as `keymap' if FUNCTION is really a keymap.  Various parts of
     Emacs need to know this information without loading the real
     definition.

     An autoloaded keymap loads automatically during key lookup when a
     prefix key's binding is the symbol FUNCTION.  Autoloading does not
     occur for other kinds of access to the keymap.  In particular, it
     does not happen when a Lisp program gets the keymap from the value
     of a variable and calls `define-key'; not even if the variable
     name is the same symbol FUNCTION.

     If FUNCTION already has a non-void function definition that is not
     an autoload object, `autoload' does nothing and returns `nil'.  If
     the function cell of FUNCTION is void, or is already an autoload
     object, then it is defined as an autoload object like this:

          (autoload FILENAME DOCSTRING INTERACTIVE TYPE)

     For example,

          (symbol-function 'run-prolog)
               => (autoload "prolog" 169681 t nil)

     In this case, `"prolog"' is the name of the file to load, 169681
     refers to the documentation string in the `emacs/etc/DOC-VERSION'
     file (*note Documentation Basics::), `t' means the function is
     interactive, and `nil' that it is not a macro or a keymap.

   The autoloaded file usually contains other definitions and may
require or provide one or more features.  If the file is not completely
loaded (due to an error in the evaluation of its contents), any function
definitions or `provide' calls that occurred during the load are
undone.  This is to ensure that the next attempt to call any function
autoloading from this file will try again to load the file.  If not for
this, then some of the functions in the file might be defined by the
aborted load, but fail to work properly for the lack of certain
subroutines not loaded successfully because they come later in the file.

   If the autoloaded file fails to define the desired Lisp function or
macro, then an error is signaled with data `"Autoloading failed to
define function FUNCTION-NAME"'.

   A magic autoload comment (often called an "autoload cookie")
consists of `;;;###autoload', on a line by itself, just before the real
definition of the function in its autoloadable source file.  The
command `M-x update-file-autoloads' writes a corresponding `autoload'
call into `loaddefs.el'.  (The string that serves as the autoload
cookie and the name of the file generated by `update-file-autoloads'
can be changed from the above defaults, see below.)  Building Emacs
loads `loaddefs.el' and thus calls `autoload'.  `M-x
update-directory-autoloads' is even more powerful; it updates autoloads
for all files in the current directory.

   The same magic comment can copy any kind of form into `loaddefs.el'.
If the form following the magic comment is not a function-defining form
or a `defcustom' form, it is copied verbatim.  "Function-defining
forms" include `define-skeleton', `define-derived-mode',
`define-generic-mode' and `define-minor-mode' as well as `defun' and
`defmacro'.  To save space, a `defcustom' form is converted to a
`defvar' in `loaddefs.el', with some additional information if it uses
`:require'.

   You can also use a magic comment to execute a form at build time
_without_ executing it when the file itself is loaded.  To do this,
write the form _on the same line_ as the magic comment.  Since it is in
a comment, it does nothing when you load the source file; but `M-x
update-file-autoloads' copies it to `loaddefs.el', where it is executed
while building Emacs.

   The following example shows how `doctor' is prepared for autoloading
with a magic comment:

     ;;;###autoload
     (defun doctor ()
       "Switch to *doctor* buffer and start giving psychotherapy."
       (interactive)
       (switch-to-buffer "*doctor*")
       (doctor-mode))

Here's what that produces in `loaddefs.el':

     (autoload (quote doctor) "doctor" "\
     Switch to *doctor* buffer and start giving psychotherapy.

     \(fn)" t nil)

The backslash and newline immediately following the double-quote are a
convention used only in the preloaded uncompiled Lisp files such as
`loaddefs.el'; they tell `make-docfile' to put the documentation string
in the `etc/DOC' file.  *Note Building Emacs::.  See also the
commentary in `lib-src/make-docfile.c'.  `(fn)' in the usage part of
the documentation string is replaced with the function's name when the
various help functions (*note Help Functions::) display it.

   If you write a function definition with an unusual macro that is not
one of the known and recognized function definition methods, use of an
ordinary magic autoload comment would copy the whole definition into
`loaddefs.el'.  That is not desirable.  You can put the desired
`autoload' call into `loaddefs.el' instead by writing this:

     ;;;###autoload (autoload 'foo "myfile")
     (mydefunmacro foo
       ...)

   You can use a non-default string as the autoload cookie and have the
corresponding autoload calls written into a file whose name is
different from the default `loaddefs.el'.  Emacs provides two variables
to control this:

 -- Variable: generate-autoload-cookie
     The value of this variable should be a string whose syntax is a
     Lisp comment.  `M-x update-file-autoloads' copies the Lisp form
     that follows the cookie into the autoload file it generates.  The
     default value of this variable is `";;;###autoload"'.

 -- Variable: generated-autoload-file
     The value of this variable names an Emacs Lisp file where the
     autoload calls should go.  The default value is `loaddefs.el', but
     you can override that, e.g., in the "Local Variables" section of a
     `.el' file (*note File Local Variables::).  The autoload file is
     assumed to contain a trailer starting with a formfeed character.

File: elisp,  Node: Repeated Loading,  Next: Named Features,  Prev: Autoload,  Up: Loading

15.6 Repeated Loading
=====================

You can load a given file more than once in an Emacs session.  For
example, after you have rewritten and reinstalled a function definition
by editing it in a buffer, you may wish to return to the original
version; you can do this by reloading the file it came from.

   When you load or reload files, bear in mind that the `load' and
`load-library' functions automatically load a byte-compiled file rather
than a non-compiled file of similar name.  If you rewrite a file that
you intend to save and reinstall, you need to byte-compile the new
version; otherwise Emacs will load the older, byte-compiled file instead
of your newer, non-compiled file!  If that happens, the message
displayed when loading the file includes, `(compiled; note, source is
newer)', to remind you to recompile it.

   When writing the forms in a Lisp library file, keep in mind that the
file might be loaded more than once.  For example, think about whether
each variable should be reinitialized when you reload the library;
`defvar' does not change the value if the variable is already
initialized.  (*Note Defining Variables::.)

   The simplest way to add an element to an alist is like this:

     (push '(leif-mode " Leif") minor-mode-alist)

But this would add multiple elements if the library is reloaded.  To
avoid the problem, use `add-to-list' (*note List Variables::):

     (add-to-list 'minor-mode-alist '(leif-mode " Leif"))

   Occasionally you will want to test explicitly whether a library has
already been loaded.  If the library uses `provide' to provide a named
feature, you can use `featurep' earlier in the file to test whether the
`provide' call has been executed before (*note Named Features::).
Alternatively, you could use something like this:

     (defvar foo-was-loaded nil)

     (unless foo-was-loaded
       EXECUTE-FIRST-TIME-ONLY
       (setq foo-was-loaded t))


File: elisp,  Node: Named Features,  Next: Where Defined,  Prev: Repeated Loading,  Up: Loading

15.7 Features
=============

`provide' and `require' are an alternative to `autoload' for loading
files automatically.  They work in terms of named "features".
Autoloading is triggered by calling a specific function, but a feature
is loaded the first time another program asks for it by name.

   A feature name is a symbol that stands for a collection of functions,
variables, etc.  The file that defines them should "provide" the
feature.  Another program that uses them may ensure they are defined by
"requiring" the feature.  This loads the file of definitions if it
hasn't been loaded already.

   To require the presence of a feature, call `require' with the
feature name as argument.  `require' looks in the global variable
`features' to see whether the desired feature has been provided
already.  If not, it loads the feature from the appropriate file.  This
file should call `provide' at the top level to add the feature to
`features'; if it fails to do so, `require' signals an error.

   For example, in `emacs/lisp/prolog.el', the definition for
`run-prolog' includes the following code:

     (defun run-prolog ()
       "Run an inferior Prolog process, with I/O via buffer *prolog*."
       (interactive)
       (require 'comint)
       (switch-to-buffer (make-comint "prolog" prolog-program-name))
       (inferior-prolog-mode))

The expression `(require 'comint)' loads the file `comint.el' if it has
not yet been loaded.  This ensures that `make-comint' is defined.
Features are normally named after the files that provide them, so that
`require' need not be given the file name.

   The `comint.el' file contains the following top-level expression:

     (provide 'comint)

This adds `comint' to the global `features' list, so that `(require
'comint)' will henceforth know that nothing needs to be done.

   When `require' is used at top level in a file, it takes effect when
you byte-compile that file (*note Byte Compilation::) as well as when
you load it.  This is in case the required package contains macros that
the byte compiler must know about.  It also avoids byte compiler
warnings for functions and variables defined in the file loaded with
`require'.

   Although top-level calls to `require' are evaluated during byte
compilation, `provide' calls are not.  Therefore, you can ensure that a
file of definitions is loaded before it is byte-compiled by including a
`provide' followed by a `require' for the same feature, as in the
following example.

     (provide 'my-feature)  ; Ignored by byte compiler,
                            ;   evaluated by `load'.
     (require 'my-feature)  ; Evaluated by byte compiler.

The compiler ignores the `provide', then processes the `require' by
loading the file in question.  Loading the file does execute the
`provide' call, so the subsequent `require' call does nothing when the
file is loaded.

 -- Function: provide feature &optional subfeatures
     This function announces that FEATURE is now loaded, or being
     loaded, into the current Emacs session.  This means that the
     facilities associated with FEATURE are or will be available for
     other Lisp programs.

     The direct effect of calling `provide' is if not already in
     FEATURES then to add FEATURE to the front of that list and call
     any `eval-after-load' code waiting for it (*note Hooks for
     Loading::).  The argument FEATURE must be a symbol.  `provide'
     returns FEATURE.

     If provided, SUBFEATURES should be a list of symbols indicating a
     set of specific subfeatures provided by this version of FEATURE.
     You can test the presence of a subfeature using `featurep'.  The
     idea of subfeatures is that you use them when a package (which is
     one FEATURE) is complex enough to make it useful to give names to
     various parts or functionalities of the package, which might or
     might not be loaded, or might or might not be present in a given
     version.  *Note Network Feature Testing::, for an example.

          features
               => (bar bish)

          (provide 'foo)
               => foo
          features
               => (foo bar bish)

     When a file is loaded to satisfy an autoload, and it stops due to
     an error in the evaluation of its contents, any function
     definitions or `provide' calls that occurred during the load are
     undone.  *Note Autoload::.

 -- Function: require feature &optional filename noerror
     This function checks whether FEATURE is present in the current
     Emacs session (using `(featurep FEATURE)'; see below).  The
     argument FEATURE must be a symbol.

     If the feature is not present, then `require' loads FILENAME with
     `load'.  If FILENAME is not supplied, then the name of the symbol
     FEATURE is used as the base file name to load.  However, in this
     case, `require' insists on finding FEATURE with an added `.el' or
     `.elc' suffix (possibly extended with a compression suffix); a
     file whose name is just FEATURE won't be used.  (The variable
     `load-suffixes' specifies the exact required Lisp suffixes.)

     If NOERROR is non-`nil', that suppresses errors from actual
     loading of the file.  In that case, `require' returns `nil' if
     loading the file fails.  Normally, `require' returns FEATURE.

     If loading the file succeeds but does not provide FEATURE,
     `require' signals an error, `Required feature FEATURE was not
     provided'.

 -- Function: featurep feature &optional subfeature
     This function returns `t' if FEATURE has been provided in the
     current Emacs session (i.e., if FEATURE is a member of
     `features'.)  If SUBFEATURE is non-`nil', then the function
     returns `t' only if that subfeature is provided as well (i.e. if
     SUBFEATURE is a member of the `subfeature' property of the FEATURE
     symbol.)

 -- Variable: features
     The value of this variable is a list of symbols that are the
     features loaded in the current Emacs session.  Each symbol was put
     in this list with a call to `provide'.  The order of the elements
     in the `features' list is not significant.

File: elisp,  Node: Where Defined,  Next: Unloading,  Prev: Named Features,  Up: Loading

15.8 Which File Defined a Certain Symbol
========================================

 -- Function: symbol-file symbol &optional type
     This function returns the name of the file that defined SYMBOL.
     If TYPE is `nil', then any kind of definition is acceptable.  If
     TYPE is `defun', `defvar', or `defface', that specifies function
     definition, variable definition, or face definition only.

     The value is normally an absolute file name.  It can also be `nil',
     if the definition is not associated with any file.  If SYMBOL
     specifies an autoloaded function, the value can be a relative file
     name without extension.

   The basis for `symbol-file' is the data in the variable
`load-history'.

 -- Variable: load-history
     This variable's value is an alist connecting library file names
     with the names of functions and variables they define, the
     features they provide, and the features they require.

     Each element is a list and describes one library.  The CAR of the
     list is the absolute file name of the library, as a string.  The
     rest of the list elements have these forms:

    `VAR'
          The symbol VAR was defined as a variable.

    `(defun . FUN)'
          The function FUN was defined.

    `(t . FUN)'
          The function FUN was previously an autoload before this
          library redefined it as a function.  The following element is
          always `(defun . FUN)', which represents defining FUN as a
          function.

    `(autoload . FUN)'
          The function FUN was defined as an autoload.

    `(defface . FACE)'
          The face FACE was defined.

    `(require . FEATURE)'
          The feature FEATURE was required.

    `(provide . FEATURE)'
          The feature FEATURE was provided.

     The value of `load-history' may have one element whose CAR is
     `nil'.  This element describes definitions made with `eval-buffer'
     on a buffer that is not visiting a file.

   The command `eval-region' updates `load-history', but does so by
adding the symbols defined to the element for the file being visited,
rather than replacing that element.  *Note Eval::.

File: elisp,  Node: Unloading,  Next: Hooks for Loading,  Prev: Where Defined,  Up: Loading

15.9 Unloading
==============

You can discard the functions and variables loaded by a library to
reclaim memory for other Lisp objects.  To do this, use the function
`unload-feature':

 -- Command: unload-feature feature &optional force
     This command unloads the library that provided feature FEATURE.
     It undefines all functions, macros, and variables defined in that
     library with `defun', `defalias', `defsubst', `defmacro',
     `defconst', `defvar', and `defcustom'.  It then restores any
     autoloads formerly associated with those symbols.  (Loading saves
     these in the `autoload' property of the symbol.)

     Before restoring the previous definitions, `unload-feature' runs
     `remove-hook' to remove functions in the library from certain
     hooks.  These hooks include variables whose names end in `hook' or
     `-hooks', plus those listed in `unload-feature-special-hooks', as
     well as `auto-mode-alist'.  This is to prevent Emacs from ceasing
     to function because important hooks refer to functions that are no
     longer defined.

     Standard unloading activities also undoes ELP profiling of
     functions in that library, unprovides any features provided by the
     library, and cancels timers held in variables defined by the
     library.

     If these measures are not sufficient to prevent malfunction, a
     library can define an explicit unloader named
     `FEATURE-unload-function'.  If that symbol is defined as a
     function, `unload-feature' calls it with no arguments before doing
     anything else.  It can do whatever is appropriate to unload the
     library.  If it returns `nil', `unload-feature' proceeds to take
     the normal unload actions.  Otherwise it considers the job to be
     done.

     Ordinarily, `unload-feature' refuses to unload a library on which
     other loaded libraries depend.  (A library A depends on library B
     if A contains a `require' for B.)  If the optional argument FORCE
     is non-`nil', dependencies are ignored and you can unload any
     library.

   The `unload-feature' function is written in Lisp; its actions are
based on the variable `load-history'.

 -- Variable: unload-feature-special-hooks
     This variable holds a list of hooks to be scanned before unloading
     a library, to remove functions defined in the library.

File: elisp,  Node: Hooks for Loading,  Prev: Unloading,  Up: Loading

15.10 Hooks for Loading
=======================

You can ask for code to be executed if and when a particular library is
loaded, by calling `eval-after-load'.

 -- Function: eval-after-load library form
     This function arranges to evaluate FORM at the end of loading the
     file LIBRARY, each time LIBRARY is loaded.  If LIBRARY is already
     loaded, it evaluates FORM right away.  Don't forget to quote FORM!

     You don't need to give a directory or extension in the file name
     LIBRARY--normally you just give a bare file name, like this:

          (eval-after-load "edebug" '(def-edebug-spec c-point t))

     To restrict which files can trigger the evaluation, include a
     directory or an extension or both in LIBRARY.  Only a file whose
     absolute true name (i.e., the name with all symbolic links chased
     out) matches all the given name components will match.  In the
     following example, `my_inst.elc' or `my_inst.elc.gz' in some
     directory `..../foo/bar' will trigger the evaluation, but not
     `my_inst.el':

          (eval-after-load "foo/bar/my_inst.elc" ...)

     LIBRARY can also be a feature (i.e. a symbol), in which case FORM
     is evaluated when `(provide LIBRARY)' is called.

     An error in FORM does not undo the load, but does prevent
     execution of the rest of FORM.

   In general, well-designed Lisp programs should not use this feature.
The clean and modular ways to interact with a Lisp library are (1)
examine and set the library's variables (those which are meant for
outside use), and (2) call the library's functions.  If you wish to do
(1), you can do it immediately--there is no need to wait for when the
library is loaded.  To do (2), you must load the library (preferably
with `require').

   But it is OK to use `eval-after-load' in your personal
customizations if you don't feel they must meet the design standards for
programs meant for wider use.

 -- Variable: after-load-alist
     This variable, an alist built by `eval-after-load', holds the
     expressions to evaluate when particular libraries are loaded.  Each
     element looks like this:

          (REGEXP-OR-FEATURE FORMS...)

     The key REGEXP-OR-FEATURE is either a regular expression or a
     symbol, and the value is a list of forms.  The forms are evaluated
     when the key matches the absolute true name of the file being
     `load'ed or the symbol being `provide'd.

File: elisp,  Node: Byte Compilation,  Next: Advising Functions,  Prev: Loading,  Up: Top

16 Byte Compilation
*******************

Emacs Lisp has a "compiler" that translates functions written in Lisp
into a special representation called "byte-code" that can be executed
more efficiently.  The compiler replaces Lisp function definitions with
byte-code.  When a byte-code function is called, its definition is
evaluated by the "byte-code interpreter".

   Because the byte-compiled code is evaluated by the byte-code
interpreter, instead of being executed directly by the machine's
hardware (as true compiled code is), byte-code is completely
transportable from machine to machine without recompilation.  It is not,
however, as fast as true compiled code.

   Compiling a Lisp file with the Emacs byte compiler always reads the
file as multibyte text, even if Emacs was started with `--unibyte',
unless the file specifies otherwise.  This is so that compilation gives
results compatible with running the same file without compilation.
*Note Loading Non-ASCII::.

   In general, any version of Emacs can run byte-compiled code produced
by recent earlier versions of Emacs, but the reverse is not true.

   If you do not want a Lisp file to be compiled, ever, put a file-local
variable binding for `no-byte-compile' into it, like this:

     ;; -*-no-byte-compile: t; -*-

   *Note Compilation Errors::, for how to investigate errors occurring
in byte compilation.

* Menu:

* 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.
* Compiler Errors::             Handling compiler error messages.
* Byte-Code Objects::		The data type used for byte-compiled functions.
* Disassembly::                 Disassembling byte-code; how to read byte-code.

File: elisp,  Node: Speed of Byte-Code,  Next: Compilation Functions,  Up: Byte Compilation

16.1 Performance of Byte-Compiled Code
======================================

A byte-compiled function is not as efficient as a primitive function
written in C, but runs much faster than the version written in Lisp.
Here is an example:

     (defun silly-loop (n)
       "Return time before and after N iterations of a loop."
       (let ((t1 (current-time-string)))
         (while (> (setq n (1- n))
                   0))
         (list t1 (current-time-string))))
     => silly-loop

     (silly-loop 50000000)
     => ("Wed Mar 11 21:10:19 2009"
         "Wed Mar 11 21:10:41 2009")  ; 22 seconds

     (byte-compile 'silly-loop)
     => [Compiled code not shown]

     (silly-loop 50000000)
     => ("Wed Mar 11 21:12:26 2009"
         "Wed Mar 11 21:12:32 2009")  ; 6 seconds

   In this example, the interpreted code required 22 seconds to run,
whereas the byte-compiled code required 6 seconds.  These results are
representative, but actual results will vary greatly.

File: elisp,  Node: Compilation Functions,  Next: Docs and Compilation,  Prev: Speed of Byte-Code,  Up: Byte Compilation

16.2 The Compilation Functions
==============================

You can byte-compile an individual function or macro definition with
the `byte-compile' function.  You can compile a whole file with
`byte-compile-file', or several files with `byte-recompile-directory'
or `batch-byte-compile'.

   The byte compiler produces error messages and warnings about each
file in a buffer called `*Compile-Log*'.  These report things in your
program that suggest a problem but are not necessarily erroneous.

   Be careful when writing macro calls in files that you may someday
byte-compile.  Macro calls are expanded when they are compiled, so the
macros must already be defined for proper compilation.  For more
details, see *note Compiling Macros::.  If a program does not work the
same way when compiled as it does when interpreted, erroneous macro
definitions are one likely cause (*note Problems with Macros::).
Inline (`defsubst') functions are less troublesome; if you compile a
call to such a function before its definition is known, the call will
still work right, it will just run slower.

   Normally, compiling a file does not evaluate the file's contents or
load the file.  But it does execute any `require' calls at top level in
the file.  One way to ensure that necessary macro definitions are
available during compilation is to require the file that defines them
(*note Named Features::).  To avoid loading the macro definition files
when someone _runs_ the compiled program, write `eval-when-compile'
around the `require' calls (*note Eval During Compile::).

 -- Function: byte-compile symbol
     This function byte-compiles the function definition of SYMBOL,
     replacing the previous definition with the compiled one.  The
     function definition of SYMBOL must be the actual code for the
     function; i.e., the compiler does not follow indirection to
     another symbol.  `byte-compile' returns the new, compiled
     definition of SYMBOL.

     If SYMBOL's definition is a byte-code function object,
     `byte-compile' does nothing and returns `nil'.  Lisp records only
     one function definition for any symbol, and if that is already
     compiled, non-compiled code is not available anywhere.  So there
     is no way to "compile the same definition again."

          (defun factorial (integer)
            "Compute factorial of INTEGER."
            (if (= 1 integer) 1
              (* integer (factorial (1- integer)))))
          => factorial

          (byte-compile 'factorial)
          =>
          #[(integer)
            "^H\301U\203^H^@\301\207\302^H\303^HS!\"\207"
            [integer 1 * factorial]
            4 "Compute factorial of INTEGER."]

     The result is a byte-code function object.  The string it contains
     is the actual byte-code; each character in it is an instruction or
     an operand of an instruction.  The vector contains all the
     constants, variable names and function names used by the function,
     except for certain primitives that are coded as special
     instructions.

     If the argument to `byte-compile' is a `lambda' expression, it
     returns the corresponding compiled code, but does not store it
     anywhere.

 -- Command: compile-defun &optional arg
     This command reads the defun containing point, compiles it, and
     evaluates the result.  If you use this on a defun that is actually
     a function definition, the effect is to install a compiled version
     of that function.

     `compile-defun' normally displays the result of evaluation in the
     echo area, but if ARG is non-`nil', it inserts the result in the
     current buffer after the form it compiled.

 -- Command: byte-compile-file filename &optional load
     This function compiles a file of Lisp code named FILENAME into a
     file of byte-code.  The output file's name is made by changing the
     `.el' suffix into `.elc'; if FILENAME does not end in `.el', it
     adds `.elc' to the end of FILENAME.

     Compilation works by reading the input file one form at a time.
     If it is a definition of a function or macro, the compiled
     function or macro definition is written out.  Other forms are
     batched together, then each batch is compiled, and written so that
     its compiled code will be executed when the file is read.  All
     comments are discarded when the input file is read.

     This command returns `t' if there were no errors and `nil'
     otherwise.  When called interactively, it prompts for the file
     name.

     If LOAD is non-`nil', this command loads the compiled file after
     compiling it.  Interactively, LOAD is the prefix argument.

          % ls -l push*
          -rw-r--r--  1 lewis     791 Oct  5 20:31 push.el

          (byte-compile-file "~/emacs/push.el")
               => t

          % ls -l push*
          -rw-r--r--  1 lewis     791 Oct  5 20:31 push.el
          -rw-rw-rw-  1 lewis     638 Oct  8 20:25 push.elc

 -- Command: byte-recompile-directory directory &optional flag force
     This command recompiles every `.el' file in DIRECTORY (or its
     subdirectories) that needs recompilation.  A file needs
     recompilation if a `.elc' file exists but is older than the `.el'
     file.

     When a `.el' file has no corresponding `.elc' file, FLAG says what
     to do.  If it is `nil', this command ignores these files.  If FLAG
     is 0, it compiles them.  If it is neither `nil' nor 0, it asks the
     user whether to compile each such file, and asks about each
     subdirectory as well.

     Interactively, `byte-recompile-directory' prompts for DIRECTORY
     and FLAG is the prefix argument.

     If FORCE is non-`nil', this command recompiles every `.el' file
     that has a `.elc' file.

     The returned value is unpredictable.

 -- Function: batch-byte-compile &optional noforce
     This function runs `byte-compile-file' on files specified on the
     command line.  This function must be used only in a batch
     execution of Emacs, as it kills Emacs on completion.  An error in
     one file does not prevent processing of subsequent files, but no
     output file will be generated for it, and the Emacs process will
     terminate with a nonzero status code.

     If NOFORCE is non-`nil', this function does not recompile files
     that have an up-to-date `.elc' file.

          % emacs -batch -f batch-byte-compile *.el

 -- Function: byte-code code-string data-vector max-stack
     This function actually interprets byte-code.  A byte-compiled
     function is actually defined with a body that calls `byte-code'.
     Don't call this function yourself--only the byte compiler knows
     how to generate valid calls to this function.

     In Emacs version 18, byte-code was always executed by way of a
     call to the function `byte-code'.  Nowadays, byte-code is usually
     executed as part of a byte-code function object, and only rarely
     through an explicit call to `byte-code'.

File: elisp,  Node: Docs and Compilation,  Next: Dynamic Loading,  Prev: Compilation Functions,  Up: Byte Compilation

16.3 Documentation Strings and Compilation
==========================================

Functions and variables loaded from a byte-compiled file access their
documentation strings dynamically from the file whenever needed.  This
saves space within Emacs, and makes loading faster because the
documentation strings themselves need not be processed while loading the
file.  Actual access to the documentation strings becomes slower as a
result, but this normally is not enough to bother users.

   Dynamic access to documentation strings does have drawbacks:

   * If you delete or move the compiled file after loading it, Emacs
     can no longer access the documentation strings for the functions
     and variables in the file.

   * If you alter the compiled file (such as by compiling a new
     version), then further access to documentation strings in this
     file will probably give nonsense results.

   If your site installs Emacs following the usual procedures, these
problems will never normally occur.  Installing a new version uses a new
directory with a different name; as long as the old version remains
installed, its files will remain unmodified in the places where they are
expected to be.

   However, if you have built Emacs yourself and use it from the
directory where you built it, you will experience this problem
occasionally if you edit and recompile Lisp files.  When it happens, you
can cure the problem by reloading the file after recompiling it.

   You can turn off this feature at compile time by setting
`byte-compile-dynamic-docstrings' to `nil'; this is useful mainly if
you expect to change the file, and you want Emacs processes that have
already loaded it to keep working when the file changes.  You can do
this globally, or for one source file by specifying a file-local
binding for the variable.  One way to do that is by adding this string
to the file's first line:

     -*-byte-compile-dynamic-docstrings: nil;-*-

 -- Variable: byte-compile-dynamic-docstrings
     If this is non-`nil', the byte compiler generates compiled files
     that are set up for dynamic loading of documentation strings.

   The dynamic documentation string feature writes compiled files that
use a special Lisp reader construct, `#@COUNT'.  This construct skips
the next COUNT characters.  It also uses the `#$' construct, which
stands for "the name of this file, as a string."  It is usually best
not to use these constructs in Lisp source files, since they are not
designed to be clear to humans reading the file.

File: elisp,  Node: Dynamic Loading,  Next: Eval During Compile,  Prev: Docs and Compilation,  Up: Byte Compilation

16.4 Dynamic Loading of Individual Functions
============================================

When you compile a file, you can optionally enable the "dynamic
function loading" feature (also known as "lazy loading").  With dynamic
function loading, loading the file doesn't fully read the function
definitions in the file.  Instead, each function definition contains a
place-holder which refers to the file.  The first time each function is
called, it reads the full definition from the file, to replace the
place-holder.

   The advantage of dynamic function loading is that loading the file
becomes much faster.  This is a good thing for a file which contains
many separate user-callable functions, if using one of them does not
imply you will probably also use the rest.  A specialized mode which
provides many keyboard commands often has that usage pattern: a user may
invoke the mode, but use only a few of the commands it provides.

   The dynamic loading feature has certain disadvantages:

   * If you delete or move the compiled file after loading it, Emacs
     can no longer load the remaining function definitions not already
     loaded.

   * If you alter the compiled file (such as by compiling a new
     version), then trying to load any function not already loaded will
     usually yield nonsense results.

   These problems will never happen in normal circumstances with
installed Emacs files.  But they are quite likely to happen with Lisp
files that you are changing.  The easiest way to prevent these problems
is to reload the new compiled file immediately after each recompilation.

   The byte compiler uses the dynamic function loading feature if the
variable `byte-compile-dynamic' is non-`nil' at compilation time.  Do
not set this variable globally, since dynamic loading is desirable only
for certain files.  Instead, enable the feature for specific source
files with file-local variable bindings.  For example, you could do it
by writing this text in the source file's first line:

     -*-byte-compile-dynamic: t;-*-

 -- Variable: byte-compile-dynamic
     If this is non-`nil', the byte compiler generates compiled files
     that are set up for dynamic function loading.

 -- Function: fetch-bytecode function
     If FUNCTION is a byte-code function object, this immediately
     finishes loading the byte code of FUNCTION from its byte-compiled
     file, if it is not fully loaded already.  Otherwise, it does
     nothing.  It always returns FUNCTION.

File: elisp,  Node: Eval During Compile,  Next: Compiler Errors,  Prev: Dynamic Loading,  Up: Byte Compilation

16.5 Evaluation During Compilation
==================================

These features permit you to write code to be evaluated during
compilation of a program.

 -- Special Form: eval-and-compile body...
     This form marks BODY to be evaluated both when you compile the
     containing code and when you run it (whether compiled or not).

     You can get a similar result by putting BODY in a separate file
     and referring to that file with `require'.  That method is
     preferable when BODY is large.  Effectively `require' is
     automatically `eval-and-compile', the package is loaded both when
     compiling and executing.

     `autoload' is also effectively `eval-and-compile' too.  It's
     recognized when compiling, so uses of such a function don't produce
     "not known to be defined" warnings.

     Most uses of `eval-and-compile' are fairly sophisticated.

     If a macro has a helper function to build its result, and that
     macro is used both locally and outside the package, then
     `eval-and-compile' should be used to get the helper both when
     compiling and then later when running.

     If functions are defined programmatically (with `fset' say), then
     `eval-and-compile' can be used to have that done at compile-time
     as well as run-time, so calls to those functions are checked (and
     warnings about "not known to be defined" suppressed).

 -- Special Form: eval-when-compile body...
     This form marks BODY to be evaluated at compile time but not when
     the compiled program is loaded.  The result of evaluation by the
     compiler becomes a constant which appears in the compiled program.
     If you load the source file, rather than compiling it, BODY is
     evaluated normally.

     If you have a constant that needs some calculation to produce,
     `eval-when-compile' can do that at compile-time.  For example,

          (defvar my-regexp
            (eval-when-compile (regexp-opt '("aaa" "aba" "abb"))))

     If you're using another package, but only need macros from it (the
     byte compiler will expand those), then `eval-when-compile' can be
     used to load it for compiling, but not executing.  For example,

          (eval-when-compile
            (require 'my-macro-package))  ;; only macros needed from this

     The same sort of thing goes for macros and `defsubst' functions
     defined locally and only for use within the file.  They are needed
     for compiling the file, but in most cases they are not needed for
     execution of the compiled file.  For example,

          (eval-when-compile
            (unless (fboundp 'some-new-thing)
              (defmacro 'some-new-thing ()
                (compatibility code))))

     This is often good for code that's only a fallback for
     compatibility with other versions of Emacs.

     *Common Lisp Note:* At top level, `eval-when-compile' is analogous
     to the Common Lisp idiom `(eval-when (compile eval) ...)'.
     Elsewhere, the Common Lisp `#.' reader macro (but not when
     interpreting) is closer to what `eval-when-compile' does.

File: elisp,  Node: Compiler Errors,  Next: Byte-Code Objects,  Prev: Eval During Compile,  Up: Byte Compilation

16.6 Compiler Errors
====================

Byte compilation outputs all errors and warnings into the buffer
`*Compile-Log*'.  The messages include file names and line numbers that
identify the location of the problem.  The usual Emacs commands for
operating on compiler diagnostics work properly on these messages.

   However, the warnings about functions that were used but not defined
are always "located" at the end of the file, so these commands won't
find the places they are really used.  To do that, you must search for
the function names.

   You can suppress the compiler warning for calling an undefined
function FUNC by conditionalizing the function call on an `fboundp'
test, like this:

     (if (fboundp 'FUNC) ...(FUNC ...)...)

The call to FUNC must be in the THEN-FORM of the `if', and FUNC must
appear quoted in the call to `fboundp'.  (This feature operates for
`cond' as well.)

   You can tell the compiler that a function is defined using
`declare-function' (*note Declaring Functions::).  Likewise, you can
tell the compiler that a variable is defined using `defvar' with no
initial value.

   You can suppress the compiler warning for a specific use of an
undefined variable VARIABLE by conditionalizing its use on a `boundp'
test, like this:

     (if (boundp 'VARIABLE) ...VARIABLE...)

The reference to VARIABLE must be in the THEN-FORM of the `if', and
VARIABLE must appear quoted in the call to `boundp'.

   You can suppress any and all compiler warnings within a certain
expression using the construct `with-no-warnings':

 -- Special Form: with-no-warnings body...
     In execution, this is equivalent to `(progn BODY...)', but the
     compiler does not issue warnings for anything that occurs inside
     BODY.

     We recommend that you use this construct around the smallest
     possible piece of code, to avoid missing possible warnings other
     than one one you intend to suppress.

   More precise control of warnings is possible by setting the variable
`byte-compile-warnings'.

File: elisp,  Node: Byte-Code Objects,  Next: Disassembly,  Prev: Compiler Errors,  Up: Byte Compilation

16.7 Byte-Code Function Objects
===============================

Byte-compiled functions have a special data type: they are "byte-code
function objects".

   Internally, a byte-code function object is much like a vector;
however, the evaluator handles this data type specially when it appears
as a function to be called.  The printed representation for a byte-code
function object is like that for a vector, with an additional `#'
before the opening `['.

   A byte-code function object must have at least four elements; there
is no maximum number, but only the first six elements have any normal
use.  They are:

ARGLIST
     The list of argument symbols.

BYTE-CODE
     The string containing the byte-code instructions.

CONSTANTS
     The vector of Lisp objects referenced by the byte code.  These
     include symbols used as function names and variable names.

STACKSIZE
     The maximum stack size this function needs.

DOCSTRING
     The documentation string (if any); otherwise, `nil'.  The value may
     be a number or a list, in case the documentation string is stored
     in a file.  Use the function `documentation' to get the real
     documentation string (*note Accessing Documentation::).

INTERACTIVE
     The interactive spec (if any).  This can be a string or a Lisp
     expression.  It is `nil' for a function that isn't interactive.

   Here's an example of a byte-code function object, in printed
representation.  It is the definition of the command `backward-sexp'.

     #[(&optional arg)
       "^H\204^F^@\301^P\302^H[!\207"
       [arg 1 forward-sexp]
       2
       254435
       "p"]

   The primitive way to create a byte-code object is with
`make-byte-code':

 -- Function: make-byte-code &rest elements
     This function constructs and returns a byte-code function object
     with ELEMENTS as its elements.

   You should not try to come up with the elements for a byte-code
function yourself, because if they are inconsistent, Emacs may crash
when you call the function.  Always leave it to the byte compiler to
create these objects; it makes the elements consistent (we hope).

   You can access the elements of a byte-code object using `aref'; you
can also use `vconcat' to create a vector with the same elements.

File: elisp,  Node: Disassembly,  Prev: Byte-Code Objects,  Up: Byte Compilation

16.8 Disassembled Byte-Code
===========================

People do not write byte-code; that job is left to the byte compiler.
But we provide a disassembler to satisfy a cat-like curiosity.  The
disassembler converts the byte-compiled code into human-readable form.

   The byte-code interpreter is implemented as a simple stack machine.
It pushes values onto a stack of its own, then pops them off to use them
in calculations whose results are themselves pushed back on the stack.
When a byte-code function returns, it pops a value off the stack and
returns it as the value of the function.

   In addition to the stack, byte-code functions can use, bind, and set
ordinary Lisp variables, by transferring values between variables and
the stack.

 -- Command: disassemble object &optional buffer-or-name
     This command displays the disassembled code for OBJECT.  In
     interactive use, or if BUFFER-OR-NAME is `nil' or omitted, the
     output goes in a buffer named `*Disassemble*'.  If BUFFER-OR-NAME
     is non-`nil', it must be a buffer or the name of an existing
     buffer.  Then the output goes there, at point, and point is left
     before the output.

     The argument OBJECT can be a function name, a lambda expression or
     a byte-code object.  If it is a lambda expression, `disassemble'
     compiles it and disassembles the resulting compiled code.

   Here are two examples of using the `disassemble' function.  We have
added explanatory comments to help you relate the byte-code to the Lisp
source; these do not appear in the output of `disassemble'.

     (defun factorial (integer)
       "Compute factorial of an integer."
       (if (= 1 integer) 1
         (* integer (factorial (1- integer)))))
          => factorial

     (factorial 4)
          => 24

     (disassemble 'factorial)
          -| byte-code for factorial:
      doc: Compute factorial of an integer.
      args: (integer)

     0   varref   integer        ; Get the value of `integer'
                                 ;   and push it onto the stack.
     1   constant 1              ; Push 1 onto stack.

     2   eqlsign                 ; Pop top two values off stack, compare
                                 ;   them, and push result onto stack.

     3   goto-if-nil 1           ; Pop and test top of stack;
                                 ;   if `nil', go to 1,
                                 ;   else continue.
     6   constant 1              ; Push 1 onto top of stack.
     7   return                  ; Return the top element
                                 ;   of the stack.

     8:1 varref   integer        ; Push value of `integer' onto stack.
     9   constant factorial      ; Push `factorial' onto stack.
     10  varref   integer        ; Push value of `integer' onto stack.
     11  sub1                    ; Pop `integer', decrement value,
                                 ;   push new value onto stack.
     12  call     1              ; Call function `factorial' using
                                 ;   the first (i.e., the top) element
                                 ;   of the stack as the argument;
                                 ;   push returned value onto stack.

     13 mult                     ; Pop top two values off stack, multiply
                                 ;   them, and push result onto stack.
     14 return                   ; Return the top element of stack.

   The `silly-loop' function is somewhat more complex:

     (defun silly-loop (n)
       "Return time before and after N iterations of a loop."
       (let ((t1 (current-time-string)))
         (while (> (setq n (1- n))
                   0))
         (list t1 (current-time-string))))
          => silly-loop

     (disassemble 'silly-loop)
          -| byte-code for silly-loop:
      doc: Return time before and after N iterations of a loop.
      args: (n)

     0   constant current-time-string  ; Push
                                       ;   `current-time-string'
                                       ;   onto top of stack.

     1   call     0              ; Call `current-time-string'
                                 ;   with no argument,
                                 ;   pushing result onto stack.

     2   varbind  t1             ; Pop stack and bind `t1'
                                 ;   to popped value.

     3:1 varref   n              ; Get value of `n' from
                                 ;   the environment and push
                                 ;   the value onto the stack.
     4   sub1                    ; Subtract 1 from top of stack.

     5   dup                     ; Duplicate the top of the stack;
                                 ;   i.e., copy the top of
                                 ;   the stack and push the
                                 ;   copy onto the stack.
     6   varset   n              ; Pop the top of the stack,
                                 ;   and bind `n' to the value.

                                 ; In effect, the sequence `dup varset'
                                 ;   copies the top of the stack
                                 ;   into the value of `n'
                                 ;   without popping it.

     7   constant 0              ; Push 0 onto stack.
     8   gtr                     ; Pop top two values off stack,
                                 ;   test if N is greater than 0
                                 ;   and push result onto stack.

     9   goto-if-not-nil 1       ; Goto 1 if `n' > 0
                                 ;   (this continues the while loop)
                                 ;   else continue.

     12  varref   t1             ; Push value of `t1' onto stack.
     13  constant current-time-string  ; Push `current-time-string'
                                       ;   onto top of stack.
     14  call     0              ; Call `current-time-string' again.

     15  unbind   1              ; Unbind `t1' in local environment.
     16  list2                   ; Pop top two elements off stack,
                                 ;   create a list of them,
                                 ;   and push list onto stack.
     17  return                  ; Return value of the top of stack.

File: elisp,  Node: Advising Functions,  Next: Debugging,  Prev: Byte Compilation,  Up: Top

17 Advising Emacs Lisp Functions
********************************

The "advice" feature lets you add to the existing definition of a
function, by "advising the function".  This is a cleaner method for a
library to customize functions defined within Emacs--cleaner than
redefining the whole function.

   Each function can have multiple "pieces of advice", separately
defined.  Each defined piece of advice can be "enabled" or "disabled"
explicitly.  All the enabled pieces of advice for any given function
actually take effect when you "activate" advice for that function, or
when you define or redefine the function.  Note that enabling a piece
of advice and activating advice for a function are not the same thing.

   *Usage Note:* Advice is useful for altering the behavior of existing
calls to an existing function.  If you want the new behavior for new
calls, or for key bindings, you should define a new function (or a new
command) which uses the existing function.

   *Usage note:* Advising a function can cause confusion in debugging,
since people who debug calls to the original function may not notice
that it has been modified with advice.  Therefore, if you have the
possibility to change the code of that function (or ask someone to do
so) to run a hook, please solve the problem that way.  Advice should be
reserved for the cases where you cannot get the function changed.

   In particular, this means that a file in Emacs should not put advice
on a function in Emacs.  There are currently a few exceptions to this
convention, but we aim to correct them.

* Menu:

* Simple Advice::           A simple example to explain the basics of advice.
* Defining Advice::         Detailed description of `defadvice'.
* Around-Advice::           Wrapping advice around a function's definition.
* Computed Advice::         ...is to `defadvice' as `fset' is to `defun'.
* Activation of Advice::    Advice doesn't do anything until you activate it.
* Enabling Advice::         You can enable or disable each piece of advice.
* Preactivation::           Preactivation is a way of speeding up the
                              loading of compiled advice.
* Argument Access in Advice:: How advice can access the function's arguments.
* Advising Primitives::     Accessing arguments when advising a primitive.
* Combined Definition::     How advice is implemented.

File: elisp,  Node: Simple Advice,  Next: Defining Advice,  Up: Advising Functions

17.1 A Simple Advice Example
============================

The command `next-line' moves point down vertically one or more lines;
it is the standard binding of `C-n'.  When used on the last line of the
buffer, this command inserts a newline to create a line to move to if
`next-line-add-newlines' is non-`nil' (its default is `nil'.)

   Suppose you wanted to add a similar feature to `previous-line',
which would insert a new line at the beginning of the buffer for the
command to move to (when `next-line-add-newlines' is non-`nil').  How
could you do this?

   You could do it by redefining the whole function, but that is not
modular.  The advice feature provides a cleaner alternative: you can
effectively add your code to the existing function definition, without
actually changing or even seeing that definition.  Here is how to do
this:

     (defadvice previous-line (before next-line-at-end
                                      (&optional arg try-vscroll))
       "Insert an empty line when moving up from the top line."
       (if (and next-line-add-newlines (= arg 1)
                (save-excursion (beginning-of-line) (bobp)))
           (progn
             (beginning-of-line)
             (newline))))

   This expression defines a "piece of advice" for the function
`previous-line'.  This piece of advice is named `next-line-at-end', and
the symbol `before' says that it is "before-advice" which should run
before the regular definition of `previous-line'.  `(&optional arg
try-vscroll)' specifies how the advice code can refer to the function's
arguments.

   When this piece of advice runs, it creates an additional line, in the
situation where that is appropriate, but does not move point to that
line.  This is the correct way to write the advice, because the normal
definition will run afterward and will move back to the newly inserted
line.

   Defining the advice doesn't immediately change the function
`previous-line'.  That happens when you "activate" the advice, like
this:

     (ad-activate 'previous-line)

This is what actually begins to use the advice that has been defined so
far for the function `previous-line'.  Henceforth, whenever that
function is run, whether invoked by the user with `C-p' or `M-x', or
called from Lisp, it runs the advice first, and its regular definition
second.

   This example illustrates before-advice, which is one "class" of
advice: it runs before the function's base definition.  There are two
other advice classes: "after-advice", which runs after the base
definition, and "around-advice", which lets you specify an expression
to wrap around the invocation of the base definition.

File: elisp,  Node: Defining Advice,  Next: Around-Advice,  Prev: Simple Advice,  Up: Advising Functions

17.2 Defining Advice
====================

To define a piece of advice, use the macro `defadvice'.  A call to
`defadvice' has the following syntax, which is based on the syntax of
`defun' and `defmacro', but adds more:

     (defadvice FUNCTION (CLASS NAME
                              [POSITION] [ARGLIST]
                              FLAGS...)
       [DOCUMENTATION-STRING]
       [INTERACTIVE-FORM]
       BODY-FORMS...)

Here, FUNCTION is the name of the function (or macro or special form)
to be advised.  From now on, we will write just "function" when
describing the entity being advised, but this always includes macros and
special forms.

   In place of the argument list in an ordinary definition, an advice
definition calls for several different pieces of information.

   CLASS specifies the "class" of the advice--one of `before', `after',
or `around'.  Before-advice runs before the function itself;
after-advice runs after the function itself; around-advice is wrapped
around the execution of the function itself.  After-advice and
around-advice can override the return value by setting
`ad-return-value'.

 -- Variable: ad-return-value
     While advice is executing, after the function's original
     definition has been executed, this variable holds its return
     value, which will ultimately be returned to the caller after
     finishing all the advice.  After-advice and around-advice can
     arrange to return some other value by storing it in this variable.

   The argument NAME is the name of the advice, a non-`nil' symbol.
The advice name uniquely identifies one piece of advice, within all the
pieces of advice in a particular class for a particular FUNCTION.  The
name allows you to refer to the piece of advice--to redefine it, or to
enable or disable it.

   The optional POSITION specifies where, in the current list of advice
of the specified CLASS, this new advice should be placed.  It should be
either `first', `last' or a number that specifies a zero-based position
(`first' is equivalent to 0).  If no position is specified, the default
is `first'.  Position values outside the range of existing positions in
this class are mapped to the beginning or the end of the range,
whichever is closer.  The POSITION value is ignored when redefining an
existing piece of advice.

   The optional ARGLIST can be used to define the argument list for the
sake of advice.  This becomes the argument list of the combined
definition that is generated in order to run the advice (*note Combined
Definition::).  Therefore, the advice expressions can use the argument
variables in this list to access argument values.

   The argument list used in advice need not be the same as the argument
list used in the original function, but must be compatible with it, so
that it can handle the ways the function is actually called.  If two
pieces of advice for a function both specify an argument list, they must
specify the same argument list.

   *Note Argument Access in Advice::, for more information about
argument lists and advice, and a more flexible way for advice to access
the arguments.

   The remaining elements, FLAGS, are symbols that specify further
information about how to use this piece of advice.  Here are the valid
symbols and their meanings:

`activate'
     Activate the advice for FUNCTION now.  Changes in a function's
     advice always take effect the next time you activate advice for the
     function; this flag says to do so, for FUNCTION, immediately after
     defining this piece of advice.

     This flag has no immediate effect if FUNCTION itself is not
     defined yet (a situation known as "forward advice"), because it is
     impossible to activate an undefined function's advice.  However,
     defining FUNCTION will automatically activate its advice.

`protect'
     Protect this piece of advice against non-local exits and errors in
     preceding code and advice.  Protecting advice places it as a
     cleanup in an `unwind-protect' form, so that it will execute even
     if the previous code gets an error or uses `throw'.  *Note
     Cleanups::.

`compile'
     Compile the combined definition that is used to run the advice.
     This flag is ignored unless `activate' is also specified.  *Note
     Combined Definition::.

`disable'
     Initially disable this piece of advice, so that it will not be used
     unless subsequently explicitly enabled.  *Note Enabling Advice::.

`preactivate'
     Activate advice for FUNCTION when this `defadvice' is compiled or
     macroexpanded.  This generates a compiled advised definition
     according to the current advice state, which will be used during
     activation if appropriate.  *Note Preactivation::.

     This is useful only if this `defadvice' is byte-compiled.

   The optional DOCUMENTATION-STRING serves to document this piece of
advice.  When advice is active for FUNCTION, the documentation for
FUNCTION (as returned by `documentation') combines the documentation
strings of all the advice for FUNCTION with the documentation string of
its original function definition.

   The optional INTERACTIVE-FORM form can be supplied to change the
interactive behavior of the original function.  If more than one piece
of advice has an INTERACTIVE-FORM, then the first one (the one with the
smallest position) found among all the advice takes precedence.

   The possibly empty list of BODY-FORMS specifies the body of the
advice.  The body of an advice can access or change the arguments, the
return value, the binding environment, and perform any other kind of
side effect.

   *Warning:* When you advise a macro, keep in mind that macros are
expanded when a program is compiled, not when a compiled program is run.
All subroutines used by the advice need to be available when the byte
compiler expands the macro.

 -- Command: ad-unadvise function
     This command deletes the advice from FUNCTION.

 -- Command: ad-unadvise-all
     This command deletes all pieces of advice from all functions.

File: elisp,  Node: Around-Advice,  Next: Computed Advice,  Prev: Defining Advice,  Up: Advising Functions

17.3 Around-Advice
==================

Around-advice lets you "wrap" a Lisp expression "around" the original
function definition.  You specify where the original function
definition should go by means of the special symbol `ad-do-it'.  Where
this symbol occurs inside the around-advice body, it is replaced with a
`progn' containing the forms of the surrounded code.  Here is an
example:

     (defadvice foo (around foo-around)
       "Ignore case in `foo'."
       (let ((case-fold-search t))
         ad-do-it))

Its effect is to make sure that case is ignored in searches when the
original definition of `foo' is run.

 -- Variable: ad-do-it
     This is not really a variable, rather a place-holder that looks
     like a variable.  You use it in around-advice to specify the place
     to run the function's original definition and other "earlier"
     around-advice.

   If the around-advice does not use `ad-do-it', then it does not run
the original function definition.  This provides a way to override the
original definition completely.  (It also overrides lower-positioned
pieces of around-advice).

   If the around-advice uses `ad-do-it' more than once, the original
definition is run at each place.  In this way, around-advice can execute
the original definition (and lower-positioned pieces of around-advice)
several times.  Another way to do that is by using `ad-do-it' inside of
a loop.

File: elisp,  Node: Computed Advice,  Next: Activation of Advice,  Prev: Around-Advice,  Up: Advising Functions

17.4 Computed Advice
====================

The macro `defadvice' resembles `defun' in that the code for the
advice, and all other information about it, are explicitly stated in
the source code.  You can also create advice whose details are computed,
using the function `ad-add-advice'.

 -- Function: ad-add-advice function advice class position
     Calling `ad-add-advice' adds ADVICE as a piece of advice to
     FUNCTION in class CLASS.  The argument ADVICE has this form:

          (NAME PROTECTED ENABLED DEFINITION)

     Here, PROTECTED and ENABLED are flags; if PROTECTED is non-`nil',
     the advice is protected against non-local exits (*note Defining
     Advice::), and if ENABLED is `nil' the advice is initially
     disabled (*note Enabling Advice::).  DEFINITION should have the
     form

          (advice . LAMBDA)

     where LAMBDA is a lambda expression; this lambda expression is
     called in order to perform the advice.  *Note Lambda Expressions::.

     If the FUNCTION argument to `ad-add-advice' already has one or
     more pieces of advice in the specified CLASS, then POSITION
     specifies where in the list to put the new piece of advice.  The
     value of POSITION can either be `first', `last', or a number
     (counting from 0 at the beginning of the list).  Numbers outside
     the range are mapped to the beginning or the end of the range,
     whichever is closer.  The POSITION value is ignored when
     redefining an existing piece of advice.

     If FUNCTION already has a piece of ADVICE with the same name, then
     the position argument is ignored and the old advice is replaced
     with the new one.

File: elisp,  Node: Activation of Advice,  Next: Enabling Advice,  Prev: Computed Advice,  Up: Advising Functions

17.5 Activation of Advice
=========================

By default, advice does not take effect when you define it--only when
you "activate" advice for the function that was advised.  However, the
advice will be activated automatically if you define or redefine the
function later.  You can request the activation of advice for a
function when you define the advice, by specifying the `activate' flag
in the `defadvice'.  But normally you activate the advice for a
function by calling the function `ad-activate' or one of the other
activation commands listed below.

   Separating the activation of advice from the act of defining it
permits you to add several pieces of advice to one function
efficiently, without redefining the function over and over as each
advice is added.  More importantly, it permits defining advice for a
function before that function is actually defined.

   When a function's advice is first activated, the function's original
definition is saved, and all enabled pieces of advice for that function
are combined with the original definition to make a new definition.
(Pieces of advice that are currently disabled are not used; see *note
Enabling Advice::.)  This definition is installed, and optionally
byte-compiled as well, depending on conditions described below.

   In all of the commands to activate advice, if COMPILE is `t' (or
anything but `nil' or a negative number), the command also compiles the
combined definition which implements the advice.  If it is `nil' or a
negative number, what happens depends on
`ad-default-compilation-action' as described below.

 -- Command: ad-activate function &optional compile
     This command activates all the advice defined for FUNCTION.

   Activating advice does nothing if FUNCTION's advice is already
active.  But if there is new advice, added since the previous time you
activated advice for FUNCTION, it activates the new advice.

 -- Command: ad-deactivate function
     This command deactivates the advice for FUNCTION.

 -- Command: ad-update function &optional compile
     This command activates the advice for FUNCTION if its advice is
     already activated.  This is useful if you change the advice.

 -- Command: ad-activate-all &optional compile
     This command activates the advice for all functions.

 -- Command: ad-deactivate-all
     This command deactivates the advice for all functions.

 -- Command: ad-update-all &optional compile
     This command activates the advice for all functions whose advice
     is already activated.  This is useful if you change the advice of
     some functions.

 -- Command: ad-activate-regexp regexp &optional compile
     This command activates all pieces of advice whose names match
     REGEXP.  More precisely, it activates all advice for any function
     which has at least one piece of advice that matches REGEXP.

 -- Command: ad-deactivate-regexp regexp
     This command deactivates all pieces of advice whose names match
     REGEXP.  More precisely, it deactivates all advice for any
     function which has at least one piece of advice that matches
     REGEXP.

 -- Command: ad-update-regexp regexp &optional compile
     This command activates pieces of advice whose names match REGEXP,
     but only those for functions whose advice is already activated.

     Reactivating a function's advice is useful for putting into effect
     all the changes that have been made in its advice (including
     enabling and disabling specific pieces of advice; *note Enabling
     Advice::) since the last time it was activated.

 -- Command: ad-start-advice
     Turn on automatic advice activation when a function is defined or
     redefined.  This is the default mode.

 -- Command: ad-stop-advice
     Turn off automatic advice activation when a function is defined or
     redefined.

 -- User Option: ad-default-compilation-action
     This variable controls whether to compile the combined definition
     that results from activating advice for a function.

     A value of `always' specifies to compile unconditionally.  A value
     of `never' specifies never compile the advice.

     A value of `maybe' specifies to compile if the byte compiler is
     already loaded.  A value of `like-original' specifies to compile
     the advice if the original definition of the advised function is
     compiled or a built-in function.

     This variable takes effect only if the COMPILE argument of
     `ad-activate' (or any of the above functions) did not force
     compilation.

   If the advised definition was constructed during "preactivation"
(*note Preactivation::), then that definition must already be compiled,
because it was constructed during byte-compilation of the file that
contained the `defadvice' with the `preactivate' flag.

File: elisp,  Node: Enabling Advice,  Next: Preactivation,  Prev: Activation of Advice,  Up: Advising Functions

17.6 Enabling and Disabling Advice
==================================

Each piece of advice has a flag that says whether it is enabled or not.
By enabling or disabling a piece of advice, you can turn it on and off
without having to undefine and redefine it.  For example, here is how
to disable a particular piece of advice named `my-advice' for the
function `foo':

     (ad-disable-advice 'foo 'before 'my-advice)

   This function by itself only changes the enable flag for a piece of
advice.  To make the change take effect in the advised definition, you
must activate the advice for `foo' again:

     (ad-activate 'foo)

 -- Command: ad-disable-advice function class name
     This command disables the piece of advice named NAME in class
     CLASS on FUNCTION.

 -- Command: ad-enable-advice function class name
     This command enables the piece of advice named NAME in class CLASS
     on FUNCTION.

   You can also disable many pieces of advice at once, for various
functions, using a regular expression.  As always, the changes take real
effect only when you next reactivate advice for the functions in
question.

 -- Command: ad-disable-regexp regexp
     This command disables all pieces of advice whose names match
     REGEXP, in all classes, on all functions.

 -- Command: ad-enable-regexp regexp
     This command enables all pieces of advice whose names match
     REGEXP, in all classes, on all functions.

File: elisp,  Node: Preactivation,  Next: Argument Access in Advice,  Prev: Enabling Advice,  Up: Advising Functions

17.7 Preactivation
==================

Constructing a combined definition to execute advice is moderately
expensive.  When a library advises many functions, this can make loading
the library slow.  In that case, you can use "preactivation" to
construct suitable combined definitions in advance.

   To use preactivation, specify the `preactivate' flag when you define
the advice with `defadvice'.  This `defadvice' call creates a combined
definition which embodies this piece of advice (whether enabled or not)
plus any other currently enabled advice for the same function, and the
function's own definition.  If the `defadvice' is compiled, that
compiles the combined definition also.

   When the function's advice is subsequently activated, if the enabled
advice for the function matches what was used to make this combined
definition, then the existing combined definition is used, thus avoiding
the need to construct one.  Thus, preactivation never causes wrong
results--but it may fail to do any good, if the enabled advice at the
time of activation doesn't match what was used for preactivation.

   Here are some symptoms that can indicate that a preactivation did not
work properly, because of a mismatch.

   * Activation of the advised function takes longer than usual.

   * The byte compiler gets loaded while an advised function gets
     activated.

   * `byte-compile' is included in the value of `features' even though
     you did not ever explicitly use the byte compiler.

   Compiled preactivated advice works properly even if the function
itself is not defined until later; however, the function needs to be
defined when you _compile_ the preactivated advice.

   There is no elegant way to find out why preactivated advice is not
being used.  What you can do is to trace the function
`ad-cache-id-verification-code' (with the function
`trace-function-background') before the advised function's advice is
activated.  After activation, check the value returned by
`ad-cache-id-verification-code' for that function: `verified' means
that the preactivated advice was used, while other values give some
information about why they were considered inappropriate.

   *Warning:* There is one known case that can make preactivation fail,
in that a preconstructed combined definition is used even though it
fails to match the current state of advice.  This can happen when two
packages define different pieces of advice with the same name, in the
same class, for the same function.  But you should avoid that anyway.

File: elisp,  Node: Argument Access in Advice,  Next: Advising Primitives,  Prev: Preactivation,  Up: Advising Functions

17.8 Argument Access in Advice
==============================

The simplest way to access the arguments of an advised function in the
body of a piece of advice is to use the same names that the function
definition uses.  To do this, you need to know the names of the argument
variables of the original function.

   While this simple method is sufficient in many cases, it has a
disadvantage: it is not robust, because it hard-codes the argument names
into the advice.  If the definition of the original function changes,
the advice might break.

   Another method is to specify an argument list in the advice itself.
This avoids the need to know the original function definition's argument
names, but it has a limitation: all the advice on any particular
function must use the same argument list, because the argument list
actually used for all the advice comes from the first piece of advice
for that function.

   A more robust method is to use macros that are translated into the
proper access forms at activation time, i.e., when constructing the
advised definition.  Access macros access actual arguments by position
regardless of how these actual arguments get distributed onto the
argument variables of a function.  This is robust because in Emacs Lisp
the meaning of an argument is strictly determined by its position in the
argument list.

 -- Macro: ad-get-arg position
     This returns the actual argument that was supplied at POSITION.

 -- Macro: ad-get-args position
     This returns the list of actual arguments supplied starting at
     POSITION.

 -- Macro: ad-set-arg position value
     This sets the value of the actual argument at POSITION to VALUE

 -- Macro: ad-set-args position value-list
     This sets the list of actual arguments starting at POSITION to
     VALUE-LIST.

   Now an example.  Suppose the function `foo' is defined as

     (defun foo (x y &optional z &rest r) ...)

and is then called with

     (foo 0 1 2 3 4 5 6)

which means that X is 0, Y is 1, Z is 2 and R is `(3 4 5 6)' within the
body of `foo'.  Here is what `ad-get-arg' and `ad-get-args' return in
this case:

     (ad-get-arg 0) => 0
     (ad-get-arg 1) => 1
     (ad-get-arg 2) => 2
     (ad-get-arg 3) => 3
     (ad-get-args 2) => (2 3 4 5 6)
     (ad-get-args 4) => (4 5 6)

   Setting arguments also makes sense in this example:

     (ad-set-arg 5 "five")

has the effect of changing the sixth argument to `"five"'.  If this
happens in advice executed before the body of `foo' is run, then R will
be `(3 4 "five" 6)' within that body.

   Here is an example of setting a tail of the argument list:

     (ad-set-args 0 '(5 4 3 2 1 0))

If this happens in advice executed before the body of `foo' is run,
then within that body, X will be 5, Y will be 4, Z will be 3, and R
will be `(2 1 0)' inside the body of `foo'.

   These argument constructs are not really implemented as Lisp macros.
Instead they are implemented specially by the advice mechanism.

File: elisp,  Node: Advising Primitives,  Next: Combined Definition,  Prev: Argument Access in Advice,  Up: Advising Functions

17.9 Advising Primitives
========================

Advising a primitive function (*note What Is a Function::) is risky.
Some primitive functions are used by the advice mechanism; advising
them could cause an infinite recursion.  Also, many primitive functions
are called directly from C code.  Calls to the primitive from Lisp code
will take note of the advice, but calls from C code will ignore the
advice.

   When the advice facility constructs the combined definition, it needs
to know the argument list of the original function.  This is not always
possible for primitive functions.  When advice cannot determine the
argument list, it uses `(&rest ad-subr-args)', which always works but
is inefficient because it constructs a list of the argument values.
You can use `ad-define-subr-args' to declare the proper argument names
for a primitive function:

 -- Function: ad-define-subr-args function arglist
     This function specifies that ARGLIST should be used as the
     argument list for function FUNCTION.

   For example,

     (ad-define-subr-args 'fset '(sym newdef))

specifies the argument list for the function `fset'.

File: elisp,  Node: Combined Definition,  Prev: Advising Primitives,  Up: Advising Functions

17.10 The Combined Definition
=============================

Suppose that a function has N pieces of before-advice (numbered from 0
through N-1), M pieces of around-advice and K pieces of after-advice.
Assuming no piece of advice is protected, the combined definition
produced to implement the advice for a function looks like this:

     (lambda ARGLIST
       [ [ADVISED-DOCSTRING] [(interactive ...)] ]
       (let (ad-return-value)
         before-0-body-form...
              ....
         before-N-1-body-form...
         around-0-body-form...
            around-1-body-form...
                  ....
               around-M-1-body-form...
                  (setq ad-return-value
                        apply original definition to ARGLIST)
               end-of-around-M-1-body-form...
                  ....
            end-of-around-1-body-form...
         end-of-around-0-body-form...
         after-0-body-form...
               ....
         after-K-1-body-form...
         ad-return-value))

   Macros are redefined as macros, which means adding `macro' to the
beginning of the combined definition.

   The interactive form is present if the original function or some
piece of advice specifies one.  When an interactive primitive function
is advised, advice uses a special method: it calls the primitive with
`call-interactively' so that it will read its own arguments.  In this
case, the advice cannot access the arguments.

   The body forms of the various advice in each class are assembled
according to their specified order.  The forms of around-advice L are
included in one of the forms of around-advice L - 1.

   The innermost part of the around advice onion is

     apply original definition to ARGLIST

whose form depends on the type of the original function.  The variable
`ad-return-value' is set to whatever this returns.  The variable is
visible to all pieces of advice, which can access and modify it before
it is actually returned from the advised function.

   The semantic structure of advised functions that contain protected
pieces of advice is the same.  The only difference is that
`unwind-protect' forms ensure that the protected advice gets executed
even if some previous piece of advice had an error or a non-local exit.
If any around-advice is protected, then the whole around-advice onion
is protected as a result.

File: elisp,  Node: Debugging,  Next: Read and Print,  Prev: Advising Functions,  Up: Top

18 Debugging Lisp Programs
**************************

There are three ways to investigate a problem in an Emacs Lisp program,
depending on what you are doing with the program when the problem
appears.

   * If the problem occurs when you run the program, you can use a Lisp
     debugger to investigate what is happening during execution.  In
     addition to the ordinary debugger, Emacs comes with a source-level
     debugger, Edebug.  This chapter describes both of them.

   * If the problem is syntactic, so that Lisp cannot even read the
     program, you can use the Emacs facilities for editing Lisp to
     localize it.

   * If the problem occurs when trying to compile the program with the
     byte compiler, you need to know how to examine the compiler's
     input buffer.

* Menu:

* Debugger::            How the Emacs Lisp debugger is implemented.
* Edebug::		A source-level Emacs Lisp debugger.
* Syntax Errors::       How to find syntax errors.
* Test Coverage::       Ensuring you have tested all branches in your code.
* Compilation Errors::  How to find errors that show up in byte compilation.

   Another useful debugging tool is the dribble file.  When a dribble
file is open, Emacs copies all keyboard input characters to that file.
Afterward, you can examine the file to find out what input was used.
*Note Terminal Input::.

   For debugging problems in terminal descriptions, the
`open-termscript' function can be useful.  *Note Terminal Output::.

File: elisp,  Node: Debugger,  Next: Edebug,  Up: Debugging

18.1 The Lisp Debugger
======================

The ordinary "Lisp debugger" provides the ability to suspend evaluation
of a form.  While evaluation is suspended (a state that is commonly
known as a "break"), you may examine the run time stack, examine the
values of local or global variables, or change those values.  Since a
break is a recursive edit, all the usual editing facilities of Emacs
are available; you can even run programs that will enter the debugger
recursively.  *Note Recursive Editing::.

* Menu:

* Error Debugging::       Entering the debugger when an error happens.
* Infinite Loops::	  Stopping and debugging a program that doesn't exit.
* 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.

File: elisp,  Node: Error Debugging,  Next: Infinite Loops,  Up: Debugger

18.1.1 Entering the Debugger on an Error
----------------------------------------

The most important time to enter the debugger is when a Lisp error
happens.  This allows you to investigate the immediate causes of the
error.

   However, entry to the debugger is not a normal consequence of an
error.  Many commands frequently cause Lisp errors when invoked
inappropriately, and during ordinary editing it would be very
inconvenient to enter the debugger each time this happens.  So if you
want errors to enter the debugger, set the variable `debug-on-error' to
non-`nil'.  (The command `toggle-debug-on-error' provides an easy way
to do this.)

 -- User Option: debug-on-error
     This variable determines whether the debugger is called when an
     error is signaled and not handled.  If `debug-on-error' is `t',
     all kinds of errors call the debugger, except those listed in
     `debug-ignored-errors' (see below).  If it is `nil', none call the
     debugger.  (Note that `eval-expression-debug-on-error' affects the
     setting of this variable in some cases; see below.)

     The value can also be a list of error conditions that should call
     the debugger.  For example, if you set it to the list
     `(void-variable)', then only errors about a variable that has no
     value invoke the debugger.

     When this variable is non-`nil', Emacs does not create an error
     handler around process filter functions and sentinels.  Therefore,
     errors in these functions also invoke the debugger.  *Note
     Processes::.

 -- User Option: debug-ignored-errors
     This variable specifies certain kinds of errors that should not
     enter the debugger.  Its value is a list of error condition
     symbols and/or regular expressions.  If the error has any of those
     condition symbols, or if the error message matches any of the
     regular expressions, then that error does not enter the debugger,
     regardless of the value of `debug-on-error'.

     The normal value of this variable lists several errors that happen
     often during editing but rarely result from bugs in Lisp programs.
     However, "rarely" is not "never"; if your program fails with an
     error that matches this list, you will need to change this list in
     order to debug the error.  The easiest way is usually to set
     `debug-ignored-errors' to `nil'.

 -- User Option: eval-expression-debug-on-error
     If this variable has a non-`nil' value, then `debug-on-error' is
     set to `t' when evaluating with the command `eval-expression'.  If
     `eval-expression-debug-on-error' is `nil', then the value of
     `debug-on-error' is not changed.  *Note Evaluating Emacs-Lisp
     Expressions: (emacs)Lisp Eval.

 -- User Option: debug-on-signal
     Normally, errors that are caught by `condition-case' never run the
     debugger, even if `debug-on-error' is non-`nil'.  In other words,
     `condition-case' gets a chance to handle the error before the
     debugger gets a chance.

     If you set `debug-on-signal' to a non-`nil' value, then the
     debugger gets the first chance at every error; an error will
     invoke the debugger regardless of any `condition-case', if it fits
     the criteria specified by the values of `debug-on-error' and
     `debug-ignored-errors'.

     *Warning:* This variable is strong medicine!  Various parts of
     Emacs handle errors in the normal course of affairs, and you may
     not even realize that errors happen there.  If you set
     `debug-on-signal' to a non-`nil' value, those errors will enter
     the debugger.

     *Warning:* `debug-on-signal' has no effect when `debug-on-error'
     is `nil'.

   To debug an error that happens during loading of the init file, use
the option `--debug-init'.  This binds `debug-on-error' to `t' while
loading the init file, and bypasses the `condition-case' which normally
catches errors in the init file.

File: elisp,  Node: Infinite Loops,  Next: Function Debugging,  Prev: Error Debugging,  Up: Debugger

18.1.2 Debugging Infinite Loops
-------------------------------

When a program loops infinitely and fails to return, your first problem
is to stop the loop.  On most operating systems, you can do this with
`C-g', which causes a "quit".

   Ordinary quitting gives no information about why the program was
looping.  To get more information, you can set the variable
`debug-on-quit' to non-`nil'.  Quitting with `C-g' is not considered an
error, and `debug-on-error' has no effect on the handling of `C-g'.
Likewise, `debug-on-quit' has no effect on errors.

   Once you have the debugger running in the middle of the infinite
loop, you can proceed from the debugger using the stepping commands.
If you step through the entire loop, you will probably get enough
information to solve the problem.

 -- User Option: debug-on-quit
     This variable determines whether the debugger is called when `quit'
     is signaled and not handled.  If `debug-on-quit' is non-`nil',
     then the debugger is called whenever you quit (that is, type
     `C-g').  If `debug-on-quit' is `nil', then the debugger is not
     called when you quit.  *Note Quitting::.

File: elisp,  Node: Function Debugging,  Next: Explicit Debug,  Prev: Infinite Loops,  Up: Debugger

18.1.3 Entering the Debugger on a Function Call
-----------------------------------------------

To investigate a problem that happens in the middle of a program, one
useful technique is to enter the debugger whenever a certain function is
called.  You can do this to the function in which the problem occurs,
and then step through the function, or you can do this to a function
called shortly before the problem, step quickly over the call to that
function, and then step through its caller.

 -- Command: debug-on-entry function-name
     This function requests FUNCTION-NAME to invoke the debugger each
     time it is called.  It works by inserting the form
     `(implement-debug-on-entry)' into the function definition as the
     first form.

     Any function or macro defined as Lisp code may be set to break on
     entry, regardless of whether it is interpreted code or compiled
     code.  If the function is a command, it will enter the debugger
     when called from Lisp and when called interactively (after the
     reading of the arguments).  You can also set debug-on-entry for
     primitive functions (i.e., those written in C) this way, but it
     only takes effect when the primitive is called from Lisp code.
     Debug-on-entry is not allowed for special forms.

     When `debug-on-entry' is called interactively, it prompts for
     FUNCTION-NAME in the minibuffer.  If the function is already set
     up to invoke the debugger on entry, `debug-on-entry' does nothing.
     `debug-on-entry' always returns FUNCTION-NAME.

     *Warning:* if you redefine a function after using `debug-on-entry'
     on it, the code to enter the debugger is discarded by the
     redefinition.  In effect, redefining the function cancels the
     break-on-entry feature for that function.

     Here's an example to illustrate use of this function:

          (defun fact (n)
            (if (zerop n) 1
                (* n (fact (1- n)))))
               => fact
          (debug-on-entry 'fact)
               => fact
          (fact 3)

          ------ Buffer: *Backtrace* ------
          Debugger entered--entering a function:
          * fact(3)
            eval((fact 3))
            eval-last-sexp-1(nil)
            eval-last-sexp(nil)
            call-interactively(eval-last-sexp)
          ------ Buffer: *Backtrace* ------

          (symbol-function 'fact)
               => (lambda (n)
                    (debug (quote debug))
                    (if (zerop n) 1 (* n (fact (1- n)))))

 -- Command: cancel-debug-on-entry &optional function-name
     This function undoes the effect of `debug-on-entry' on
     FUNCTION-NAME.  When called interactively, it prompts for
     FUNCTION-NAME in the minibuffer.  If FUNCTION-NAME is omitted or
     `nil', it cancels break-on-entry for all functions.  Calling
     `cancel-debug-on-entry' does nothing to a function which is not
     currently set up to break on entry.

File: elisp,  Node: Explicit Debug,  Next: Using Debugger,  Prev: Function Debugging,  Up: Debugger

18.1.4 Explicit Entry to the Debugger
-------------------------------------

You can cause the debugger to be called at a certain point in your
program by writing the expression `(debug)' at that point.  To do this,
visit the source file, insert the text `(debug)' at the proper place,
and type `C-M-x' (`eval-defun', a Lisp mode key binding).  *Warning:*
if you do this for temporary debugging purposes, be sure to undo this
insertion before you save the file!

   The place where you insert `(debug)' must be a place where an
additional form can be evaluated and its value ignored.  (If the value
of `(debug)' isn't ignored, it will alter the execution of the
program!)  The most common suitable places are inside a `progn' or an
implicit `progn' (*note Sequencing::).

File: elisp,  Node: Using Debugger,  Next: Debugger Commands,  Prev: Explicit Debug,  Up: Debugger

18.1.5 Using the Debugger
-------------------------

When the debugger is entered, it displays the previously selected
buffer in one window and a buffer named `*Backtrace*' in another
window.  The backtrace buffer contains one line for each level of Lisp
function execution currently going on.  At the beginning of this buffer
is a message describing the reason that the debugger was invoked (such
as the error message and associated data, if it was invoked due to an
error).

   The backtrace buffer is read-only and uses a special major mode,
Debugger mode, in which letters are defined as debugger commands.  The
usual Emacs editing commands are available; thus, you can switch windows
to examine the buffer that was being edited at the time of the error,
switch buffers, visit files, or do any other sort of editing.  However,
the debugger is a recursive editing level (*note Recursive Editing::)
and it is wise to go back to the backtrace buffer and exit the debugger
(with the `q' command) when you are finished with it.  Exiting the
debugger gets out of the recursive edit and kills the backtrace buffer.

   The backtrace buffer shows you the functions that are executing and
their argument values.  It also allows you to specify a stack frame by
moving point to the line describing that frame.  (A stack frame is the
place where the Lisp interpreter records information about a particular
invocation of a function.)  The frame whose line point is on is
considered the "current frame".  Some of the debugger commands operate
on the current frame.  If a line starts with a star, that means that
exiting that frame will call the debugger again.  This is useful for
examining the return value of a function.

   If a function name is underlined, that means the debugger knows
where its source code is located.  You can click `Mouse-2' on that
name, or move to it and type <RET>, to visit the source code.

   The debugger itself must be run byte-compiled, since it makes
assumptions about how many stack frames are used for the debugger
itself.  These assumptions are false if the debugger is running
interpreted.

File: elisp,  Node: Debugger Commands,  Next: Invoking the Debugger,  Prev: Using Debugger,  Up: Debugger

18.1.6 Debugger Commands
------------------------

The debugger buffer (in Debugger mode) provides special commands in
addition to the usual Emacs commands.  The most important use of
debugger commands is for stepping through code, so that you can see how
control flows.  The debugger can step through the control structures of
an interpreted function, but cannot do so in a byte-compiled function.
If you would like to step through a byte-compiled function, replace it
with an interpreted definition of the same function.  (To do this,
visit the source for the function and type `C-M-x' on its definition.)
You cannot use the Lisp debugger to step through a primitive function.

   Here is a list of Debugger mode commands:

`c'
     Exit the debugger and continue execution.  When continuing is
     possible, it resumes execution of the program as if the debugger
     had never been entered (aside from any side-effects that you
     caused by changing variable values or data structures while inside
     the debugger).

     Continuing is possible after entry to the debugger due to function
     entry or exit, explicit invocation, or quitting.  You cannot
     continue if the debugger was entered because of an error.

`d'
     Continue execution, but enter the debugger the next time any Lisp
     function is called.  This allows you to step through the
     subexpressions of an expression, seeing what values the
     subexpressions compute, and what else they do.

     The stack frame made for the function call which enters the
     debugger in this way will be flagged automatically so that the
     debugger will be called again when the frame is exited.  You can
     use the `u' command to cancel this flag.

`b'
     Flag the current frame so that the debugger will be entered when
     the frame is exited.  Frames flagged in this way are marked with
     stars in the backtrace buffer.

`u'
     Don't enter the debugger when the current frame is exited.  This
     cancels a `b' command on that frame.  The visible effect is to
     remove the star from the line in the backtrace buffer.

`j'
     Flag the current frame like `b'.  Then continue execution like
     `c', but temporarily disable break-on-entry for all functions that
     are set up to do so by `debug-on-entry'.

`e'
     Read a Lisp expression in the minibuffer, evaluate it, and print
     the value in the echo area.  The debugger alters certain important
     variables, and the current buffer, as part of its operation; `e'
     temporarily restores their values from outside the debugger, so
     you can examine and change them.  This makes the debugger more
     transparent.  By contrast, `M-:' does nothing special in the
     debugger; it shows you the variable values within the debugger.

`R'
     Like `e', but also save the result of evaluation in the buffer
     `*Debugger-record*'.

`q'
     Terminate the program being debugged; return to top-level Emacs
     command execution.

     If the debugger was entered due to a `C-g' but you really want to
     quit, and not debug, use the `q' command.

`r'
     Return a value from the debugger.  The value is computed by
     reading an expression with the minibuffer and evaluating it.

     The `r' command is useful when the debugger was invoked due to exit
     from a Lisp call frame (as requested with `b' or by entering the
     frame with `d'); then the value specified in the `r' command is
     used as the value of that frame.  It is also useful if you call
     `debug' and use its return value.  Otherwise, `r' has the same
     effect as `c', and the specified return value does not matter.

     You can't use `r' when the debugger was entered due to an error.

`l'
     Display a list of functions that will invoke the debugger when
     called.  This is a list of functions that are set to break on
     entry by means of `debug-on-entry'.  *Warning:* if you redefine
     such a function and thus cancel the effect of `debug-on-entry', it
     may erroneously show up in this list.

File: elisp,  Node: Invoking the Debugger,  Next: Internals of Debugger,  Prev: Debugger Commands,  Up: Debugger

18.1.7 Invoking the Debugger
----------------------------

Here we describe in full detail the function `debug' that is used to
invoke the debugger.

 -- Function: debug &rest debugger-args
     This function enters the debugger.  It switches buffers to a buffer
     named `*Backtrace*' (or `*Backtrace*<2>' if it is the second
     recursive entry to the debugger, etc.), and fills it with
     information about the stack of Lisp function calls.  It then
     enters a recursive edit, showing the backtrace buffer in Debugger
     mode.

     The Debugger mode `c', `d', `j', and `r' commands exit the
     recursive edit; then `debug' switches back to the previous buffer
     and returns to whatever called `debug'.  This is the only way the
     function `debug' can return to its caller.

     The use of the DEBUGGER-ARGS is that `debug' displays the rest of
     its arguments at the top of the `*Backtrace*' buffer, so that the
     user can see them.  Except as described below, this is the _only_
     way these arguments are used.

     However, certain values for first argument to `debug' have a
     special significance.  (Normally, these values are used only by the
     internals of Emacs, and not by programmers calling `debug'.)  Here
     is a table of these special values:

    `lambda'
          A first argument of `lambda' means `debug' was called because
          of entry to a function when `debug-on-next-call' was
          non-`nil'.  The debugger displays `Debugger entered--entering
          a function:' as a line of text at the top of the buffer.

    `debug'
          `debug' as first argument means `debug' was called because of
          entry to a function that was set to debug on entry.  The
          debugger displays the string `Debugger entered--entering a
          function:', just as in the `lambda' case.  It also marks the
          stack frame for that function so that it will invoke the
          debugger when exited.

    `t'
          When the first argument is `t', this indicates a call to
          `debug' due to evaluation of a function call form when
          `debug-on-next-call' is non-`nil'.  The debugger displays
          `Debugger entered--beginning evaluation of function call
          form:' as the top line in the buffer.

    `exit'
          When the first argument is `exit', it indicates the exit of a
          stack frame previously marked to invoke the debugger on exit.
          The second argument given to `debug' in this case is the
          value being returned from the frame.  The debugger displays
          `Debugger entered--returning value:' in the top line of the
          buffer, followed by the value being returned.

    `error'
          When the first argument is `error', the debugger indicates
          that it is being entered because an error or `quit' was
          signaled and not handled, by displaying `Debugger
          entered--Lisp error:' followed by the error signaled and any
          arguments to `signal'.  For example,

               (let ((debug-on-error t))
                 (/ 1 0))

               ------ Buffer: *Backtrace* ------
               Debugger entered--Lisp error: (arith-error)
                 /(1 0)
               ...
               ------ Buffer: *Backtrace* ------

          If an error was signaled, presumably the variable
          `debug-on-error' is non-`nil'.  If `quit' was signaled, then
          presumably the variable `debug-on-quit' is non-`nil'.

    `nil'
          Use `nil' as the first of the DEBUGGER-ARGS when you want to
          enter the debugger explicitly.  The rest of the DEBUGGER-ARGS
          are printed on the top line of the buffer.  You can use this
          feature to display messages--for example, to remind yourself
          of the conditions under which `debug' is called.

File: elisp,  Node: Internals of Debugger,  Prev: Invoking the Debugger,  Up: Debugger

18.1.8 Internals of the Debugger
--------------------------------

This section describes functions and variables used internally by the
debugger.

 -- Variable: debugger
     The value of this variable is the function to call to invoke the
     debugger.  Its value must be a function of any number of
     arguments, or, more typically, the name of a function.  This
     function should invoke some kind of debugger.  The default value
     of the variable is `debug'.

     The first argument that Lisp hands to the function indicates why it
     was called.  The convention for arguments is detailed in the
     description of `debug' (*note Invoking the Debugger::).

 -- Command: backtrace
     This function prints a trace of Lisp function calls currently
     active.  This is the function used by `debug' to fill up the
     `*Backtrace*' buffer.  It is written in C, since it must have
     access to the stack to determine which function calls are active.
     The return value is always `nil'.

     In the following example, a Lisp expression calls `backtrace'
     explicitly.  This prints the backtrace to the stream
     `standard-output', which, in this case, is the buffer
     `backtrace-output'.

     Each line of the backtrace represents one function call.  The line
     shows the values of the function's arguments if they are all
     known; if they are still being computed, the line says so.  The
     arguments of special forms are elided.

          (with-output-to-temp-buffer "backtrace-output"
            (let ((var 1))
              (save-excursion
                (setq var (eval '(progn
                                   (1+ var)
                                   (list 'testing (backtrace))))))))

               => (testing nil)

          ----------- Buffer: backtrace-output ------------
            backtrace()
            (list ...computing arguments...)
            (progn ...)
            eval((progn (1+ var) (list (quote testing) (backtrace))))
            (setq ...)
            (save-excursion ...)
            (let ...)
            (with-output-to-temp-buffer ...)
            eval((with-output-to-temp-buffer ...))
            eval-last-sexp-1(nil)
            eval-last-sexp(nil)
            call-interactively(eval-last-sexp)
          ----------- Buffer: backtrace-output ------------

 -- Variable: debug-on-next-call
     If this variable is non-`nil', it says to call the debugger before
     the next `eval', `apply' or `funcall'.  Entering the debugger sets
     `debug-on-next-call' to `nil'.

     The `d' command in the debugger works by setting this variable.

 -- Function: backtrace-debug level flag
     This function sets the debug-on-exit flag of the stack frame LEVEL
     levels down the stack, giving it the value FLAG.  If FLAG is
     non-`nil', this will cause the debugger to be entered when that
     frame later exits.  Even a nonlocal exit through that frame will
     enter the debugger.

     This function is used only by the debugger.

 -- Variable: command-debug-status
     This variable records the debugging status of the current
     interactive command.  Each time a command is called interactively,
     this variable is bound to `nil'.  The debugger can set this
     variable to leave information for future debugger invocations
     during the same command invocation.

     The advantage of using this variable rather than an ordinary global
     variable is that the data will never carry over to a subsequent
     command invocation.

 -- Function: backtrace-frame frame-number
     The function `backtrace-frame' is intended for use in Lisp
     debuggers.  It returns information about what computation is
     happening in the stack frame FRAME-NUMBER levels down.

     If that frame has not evaluated the arguments yet, or is a special
     form, the value is `(nil FUNCTION ARG-FORMS...)'.

     If that frame has evaluated its arguments and called its function
     already, the return value is `(t FUNCTION ARG-VALUES...)'.

     In the return value, FUNCTION is whatever was supplied as the CAR
     of the evaluated list, or a `lambda' expression in the case of a
     macro call.  If the function has a `&rest' argument, that is
     represented as the tail of the list ARG-VALUES.

     If FRAME-NUMBER is out of range, `backtrace-frame' returns `nil'.

File: elisp,  Node: Edebug,  Next: Syntax Errors,  Prev: Debugger,  Up: Debugging

18.2 Edebug
===========

Edebug is a source-level debugger for Emacs Lisp programs, with which
you can:

   * Step through evaluation, stopping before and after each expression.

   * Set conditional or unconditional breakpoints.

   * Stop when a specified condition is true (the global break event).

   * Trace slow or fast, stopping briefly at each stop point, or at
     each breakpoint.

   * Display expression results and evaluate expressions as if outside
     of Edebug.

   * Automatically re-evaluate a list of expressions and display their
     results each time Edebug updates the display.

   * Output trace information on function calls and returns.

   * Stop when an error occurs.

   * Display a backtrace, omitting Edebug's own frames.

   * Specify argument evaluation for macros and defining forms.

   * Obtain rudimentary coverage testing and frequency counts.

   The first three sections below should tell you enough about Edebug to
start using it.

* Menu:

* Using Edebug::		Introduction to use of Edebug.
* Instrumenting::		You must instrument your code
				  in order to debug it with Edebug.
* Modes: Edebug Execution Modes. Execution modes, stopping more or less often.
* Jumping::			Commands to jump to a specified place.
* Misc: Edebug Misc.		Miscellaneous commands.
* Breaks::                      Setting breakpoints to make the program stop.
* Trapping Errors::		Trapping errors with Edebug.
* Views: Edebug Views.		Views inside and outside of Edebug.
* Eval: Edebug Eval.		Evaluating expressions within Edebug.
* Eval List::			Expressions whose values are displayed
				  each time you enter Edebug.
* Printing in Edebug::		Customization of printing.
* Trace Buffer::		How to produce trace output in a buffer.
* Coverage Testing::		How to test evaluation coverage.
* The Outside Context::		Data that Edebug saves and restores.
* Edebug and Macros::	        Specifying how to handle macro calls.
* Options: Edebug Options.	Option variables for customizing Edebug.

File: elisp,  Node: Using Edebug,  Next: Instrumenting,  Up: Edebug

18.2.1 Using Edebug
-------------------

To debug a Lisp program with Edebug, you must first "instrument" the
Lisp code that you want to debug.  A simple way to do this is to first
move point into the definition of a function or macro and then do `C-u
C-M-x' (`eval-defun' with a prefix argument).  See *note
Instrumenting::, for alternative ways to instrument code.

   Once a function is instrumented, any call to the function activates
Edebug.  Depending on which Edebug execution mode you have selected,
activating Edebug may stop execution and let you step through the
function, or it may update the display and continue execution while
checking for debugging commands.  The default execution mode is step,
which stops execution.  *Note Edebug Execution Modes::.

   Within Edebug, you normally view an Emacs buffer showing the source
of the Lisp code you are debugging.  This is referred to as the "source
code buffer", and it is temporarily read-only.

   An arrow in the left fringe indicates the line where the function is
executing.  Point initially shows where within the line the function is
executing, but this ceases to be true if you move point yourself.

   If you instrument the definition of `fac' (shown below) and then
execute `(fac 3)', here is what you would normally see.  Point is at
the open-parenthesis before `if'.

     (defun fac (n)
     =>-!-(if (< 0 n)
           (* n (fac (1- n)))
         1))

   The places within a function where Edebug can stop execution are
called "stop points".  These occur both before and after each
subexpression that is a list, and also after each variable reference.
Here we use periods to show the stop points in the function `fac':

     (defun fac (n)
       .(if .(< 0 n.).
           .(* n. .(fac .(1- n.).).).
         1).)

   The special commands of Edebug are available in the source code
buffer in addition to the commands of Emacs Lisp mode.  For example,
you can type the Edebug command <SPC> to execute until the next stop
point.  If you type <SPC> once after entry to `fac', here is the
display you will see:

     (defun fac (n)
     =>(if -!-(< 0 n)
           (* n (fac (1- n)))
         1))

   When Edebug stops execution after an expression, it displays the
expression's value in the echo area.

   Other frequently used commands are `b' to set a breakpoint at a stop
point, `g' to execute until a breakpoint is reached, and `q' to exit
Edebug and return to the top-level command loop.  Type `?' to display a
list of all Edebug commands.

File: elisp,  Node: Instrumenting,  Next: Edebug Execution Modes,  Prev: Using Edebug,  Up: Edebug

18.2.2 Instrumenting for Edebug
-------------------------------

In order to use Edebug to debug Lisp code, you must first "instrument"
the code.  Instrumenting code inserts additional code into it, to
invoke Edebug at the proper places.

   When you invoke command `C-M-x' (`eval-defun') with a prefix
argument on a function definition, it instruments the definition before
evaluating it.  (This does not modify the source code itself.)  If the
variable `edebug-all-defs' is non-`nil', that inverts the meaning of
the prefix argument: in this case, `C-M-x' instruments the definition
_unless_ it has a prefix argument.  The default value of
`edebug-all-defs' is `nil'.  The command `M-x edebug-all-defs' toggles
the value of the variable `edebug-all-defs'.

   If `edebug-all-defs' is non-`nil', then the commands `eval-region',
`eval-current-buffer', and `eval-buffer' also instrument any
definitions they evaluate.  Similarly, `edebug-all-forms' controls
whether `eval-region' should instrument _any_ form, even non-defining
forms.  This doesn't apply to loading or evaluations in the minibuffer.
The command `M-x edebug-all-forms' toggles this option.

   Another command, `M-x edebug-eval-top-level-form', is available to
instrument any top-level form regardless of the values of
`edebug-all-defs' and `edebug-all-forms'.

   While Edebug is active, the command `I' (`edebug-instrument-callee')
instruments the definition of the function or macro called by the list
form after point, if is not already instrumented.  This is possible
only if Edebug knows where to find the source for that function; for
this reason, after loading Edebug, `eval-region' records the position
of every definition it evaluates, even if not instrumenting it.  See
also the `i' command (*note Jumping::), which steps into the call after
instrumenting the function.

   Edebug knows how to instrument all the standard special forms,
`interactive' forms with an expression argument, anonymous lambda
expressions, and other defining forms.  However, Edebug cannot determine
on its own what a user-defined macro will do with the arguments of a
macro call, so you must provide that information using Edebug
specifications; for details, *note Edebug and Macros::.

   When Edebug is about to instrument code for the first time in a
session, it runs the hook `edebug-setup-hook', then sets it to `nil'.
You can use this to load Edebug specifications associated with a
package you are using, but only when you use Edebug.

   To remove instrumentation from a definition, simply re-evaluate its
definition in a way that does not instrument.  There are two ways of
evaluating forms that never instrument them: from a file with `load',
and from the minibuffer with `eval-expression' (`M-:').

   If Edebug detects a syntax error while instrumenting, it leaves point
at the erroneous code and signals an `invalid-read-syntax' error.

   *Note Edebug Eval::, for other evaluation functions available inside
of Edebug.

File: elisp,  Node: Edebug Execution Modes,  Next: Jumping,  Prev: Instrumenting,  Up: Edebug

18.2.3 Edebug Execution Modes
-----------------------------

Edebug supports several execution modes for running the program you are
debugging.  We call these alternatives "Edebug execution modes"; do not
confuse them with major or minor modes.  The current Edebug execution
mode determines how far Edebug continues execution before
stopping--whether it stops at each stop point, or continues to the next
breakpoint, for example--and how much Edebug displays the progress of
the evaluation before it stops.

   Normally, you specify the Edebug execution mode by typing a command
to continue the program in a certain mode.  Here is a table of these
commands; all except for `S' resume execution of the program, at least
for a certain distance.

`S'
     Stop: don't execute any more of the program, but wait for more
     Edebug commands (`edebug-stop').

`<SPC>'
     Step: stop at the next stop point encountered (`edebug-step-mode').

`n'
     Next: stop at the next stop point encountered after an expression
     (`edebug-next-mode').  Also see `edebug-forward-sexp' in *note
     Jumping::.

`t'
     Trace: pause (normally one second) at each Edebug stop point
     (`edebug-trace-mode').

`T'
     Rapid trace: update the display at each stop point, but don't
     actually pause (`edebug-Trace-fast-mode').

`g'
     Go: run until the next breakpoint (`edebug-go-mode').  *Note
     Breakpoints::.

`c'
     Continue: pause one second at each breakpoint, and then continue
     (`edebug-continue-mode').

`C'
     Rapid continue: move point to each breakpoint, but don't pause
     (`edebug-Continue-fast-mode').

`G'
     Go non-stop: ignore breakpoints (`edebug-Go-nonstop-mode').  You
     can still stop the program by typing `S', or any editing command.

   In general, the execution modes earlier in the above list run the
program more slowly or stop sooner than the modes later in the list.

   While executing or tracing, you can interrupt the execution by typing
any Edebug command.  Edebug stops the program at the next stop point and
then executes the command you typed.  For example, typing `t' during
execution switches to trace mode at the next stop point.  You can use
`S' to stop execution without doing anything else.

   If your function happens to read input, a character you type
intending to interrupt execution may be read by the function instead.
You can avoid such unintended results by paying attention to when your
program wants input.

   Keyboard macros containing the commands in this section do not
completely work: exiting from Edebug, to resume the program, loses track
of the keyboard macro.  This is not easy to fix.  Also, defining or
executing a keyboard macro outside of Edebug does not affect commands
inside Edebug.  This is usually an advantage.  See also the
`edebug-continue-kbd-macro' option in *note Edebug Options::.

   When you enter a new Edebug level, the initial execution mode comes
from the value of the variable `edebug-initial-mode' (*note Edebug
Options::).  By default, this specifies step mode.  Note that you may
reenter the same Edebug level several times if, for example, an
instrumented function is called several times from one command.

 -- User Option: edebug-sit-for-seconds
     This option specifies how many seconds to wait between execution
     steps in trace mode or continue mode.  The default is 1 second.

File: elisp,  Node: Jumping,  Next: Edebug Misc,  Prev: Edebug Execution Modes,  Up: Edebug

18.2.4 Jumping
--------------

The commands described in this section execute until they reach a
specified location.  All except `i' make a temporary breakpoint to
establish the place to stop, then switch to go mode.  Any other
breakpoint reached before the intended stop point will also stop
execution.  *Note Breakpoints::, for the details on breakpoints.

   These commands may fail to work as expected in case of nonlocal exit,
as that can bypass the temporary breakpoint where you expected the
program to stop.

`h'
     Proceed to the stop point near where point is (`edebug-goto-here').

`f'
     Run the program for one expression (`edebug-forward-sexp').

`o'
     Run the program until the end of the containing sexp
     (`edebug-step-out').

`i'
     Step into the function or macro called by the form after point.

   The `h' command proceeds to the stop point at or after the current
location of point, using a temporary breakpoint.

   The `f' command runs the program forward over one expression.  More
precisely, it sets a temporary breakpoint at the position that
`forward-sexp' would reach, then executes in go mode so that the
program will stop at breakpoints.

   With a prefix argument N, the temporary breakpoint is placed N sexps
beyond point.  If the containing list ends before N more elements, then
the place to stop is after the containing expression.

   You must check that the position `forward-sexp' finds is a place
that the program will really get to.  In `cond', for example, this may
not be true.

   For flexibility, the `f' command does `forward-sexp' starting at
point, rather than at the stop point.  If you want to execute one
expression _from the current stop point_, first type `w'
(`edebug-where') to move point there, and then type `f'.

   The `o' command continues "out of" an expression.  It places a
temporary breakpoint at the end of the sexp containing point.  If the
containing sexp is a function definition itself, `o' continues until
just before the last sexp in the definition.  If that is where you are
now, it returns from the function and then stops.  In other words, this
command does not exit the currently executing function unless you are
positioned after the last sexp.

   The `i' command steps into the function or macro called by the list
form after point, and stops at its first stop point.  Note that the form
need not be the one about to be evaluated.  But if the form is a
function call about to be evaluated, remember to use this command before
any of the arguments are evaluated, since otherwise it will be too late.

   The `i' command instruments the function or macro it's supposed to
step into, if it isn't instrumented already.  This is convenient, but
keep in mind that the function or macro remains instrumented unless you
explicitly arrange to deinstrument it.

File: elisp,  Node: Edebug Misc,  Next: Breaks,  Prev: Jumping,  Up: Edebug

18.2.5 Miscellaneous Edebug Commands
------------------------------------

Some miscellaneous Edebug commands are described here.

`?'
     Display the help message for Edebug (`edebug-help').

`C-]'
     Abort one level back to the previous command level
     (`abort-recursive-edit').

`q'
     Return to the top level editor command loop (`top-level').  This
     exits all recursive editing levels, including all levels of Edebug
     activity.  However, instrumented code protected with
     `unwind-protect' or `condition-case' forms may resume debugging.

`Q'
     Like `q', but don't stop even for protected code
     (`edebug-top-level-nonstop').

`r'
     Redisplay the most recently known expression result in the echo
     area (`edebug-previous-result').

`d'
     Display a backtrace, excluding Edebug's own functions for clarity
     (`edebug-backtrace').

     You cannot use debugger commands in the backtrace buffer in Edebug
     as you would in the standard debugger.

     The backtrace buffer is killed automatically when you continue
     execution.

   You can invoke commands from Edebug that activate Edebug again
recursively.  Whenever Edebug is active, you can quit to the top level
with `q' or abort one recursive edit level with `C-]'.  You can display
a backtrace of all the pending evaluations with `d'.

File: elisp,  Node: Breaks,  Next: Trapping Errors,  Prev: Edebug Misc,  Up: Edebug

18.2.6 Breaks
-------------

Edebug's step mode stops execution when the next stop point is reached.
There are three other ways to stop Edebug execution once it has started:
breakpoints, the global break condition, and source breakpoints.

* Menu:

* Breakpoints::                 Breakpoints at stop points.
* Global Break Condition::	Breaking on an event.
* Source Breakpoints::  	Embedding breakpoints in source code.

File: elisp,  Node: Breakpoints,  Next: Global Break Condition,  Up: Breaks

18.2.6.1 Edebug Breakpoints
...........................

While using Edebug, you can specify "breakpoints" in the program you
are testing: these are places where execution should stop.  You can set
a breakpoint at any stop point, as defined in *note Using Edebug::.  For
setting and unsetting breakpoints, the stop point that is affected is
the first one at or after point in the source code buffer.  Here are the
Edebug commands for breakpoints:

`b'
     Set a breakpoint at the stop point at or after point
     (`edebug-set-breakpoint').  If you use a prefix argument, the
     breakpoint is temporary--it turns off the first time it stops the
     program.

`u'
     Unset the breakpoint (if any) at the stop point at or after point
     (`edebug-unset-breakpoint').

`x CONDITION <RET>'
     Set a conditional breakpoint which stops the program only if
     evaluating CONDITION produces a non-`nil' value
     (`edebug-set-conditional-breakpoint').  With a prefix argument,
     the breakpoint is temporary.

`B'
     Move point to the next breakpoint in the current definition
     (`edebug-next-breakpoint').

   While in Edebug, you can set a breakpoint with `b' and unset one
with `u'.  First move point to the Edebug stop point of your choice,
then type `b' or `u' to set or unset a breakpoint there.  Unsetting a
breakpoint where none has been set has no effect.

   Re-evaluating or reinstrumenting a definition removes all of its
previous breakpoints.

   A "conditional breakpoint" tests a condition each time the program
gets there.  Any errors that occur as a result of evaluating the
condition are ignored, as if the result were `nil'.  To set a
conditional breakpoint, use `x', and specify the condition expression
in the minibuffer.  Setting a conditional breakpoint at a stop point
that has a previously established conditional breakpoint puts the
previous condition expression in the minibuffer so you can edit it.

   You can make a conditional or unconditional breakpoint "temporary"
by using a prefix argument with the command to set the breakpoint.
When a temporary breakpoint stops the program, it is automatically
unset.

   Edebug always stops or pauses at a breakpoint, except when the Edebug
mode is Go-nonstop.  In that mode, it ignores breakpoints entirely.

   To find out where your breakpoints are, use the `B' command, which
moves point to the next breakpoint following point, within the same
function, or to the first breakpoint if there are no following
breakpoints.  This command does not continue execution--it just moves
point in the buffer.

File: elisp,  Node: Global Break Condition,  Next: Source Breakpoints,  Prev: Breakpoints,  Up: Breaks

18.2.6.2 Global Break Condition
...............................

A "global break condition" stops execution when a specified condition
is satisfied, no matter where that may occur.  Edebug evaluates the
global break condition at every stop point; if it evaluates to a
non-`nil' value, then execution stops or pauses depending on the
execution mode, as if a breakpoint had been hit.  If evaluating the
condition gets an error, execution does not stop.

   The condition expression is stored in
`edebug-global-break-condition'.  You can specify a new expression
using the `X' command from the source code buffer while Edebug is
active, or using `C-x X X' from any buffer at any time, as long as
Edebug is loaded (`edebug-set-global-break-condition').

   The global break condition is the simplest way to find where in your
code some event occurs, but it makes code run much more slowly.  So you
should reset the condition to `nil' when not using it.

File: elisp,  Node: Source Breakpoints,  Prev: Global Break Condition,  Up: Breaks

18.2.6.3 Source Breakpoints
...........................

All breakpoints in a definition are forgotten each time you
reinstrument it.  If you wish to make a breakpoint that won't be
forgotten, you can write a "source breakpoint", which is simply a call
to the function `edebug' in your source code.  You can, of course, make
such a call conditional.  For example, in the `fac' function, you can
insert the first line as shown below, to stop when the argument reaches
zero:

     (defun fac (n)
       (if (= n 0) (edebug))
       (if (< 0 n)
           (* n (fac (1- n)))
         1))

   When the `fac' definition is instrumented and the function is
called, the call to `edebug' acts as a breakpoint.  Depending on the
execution mode, Edebug stops or pauses there.

   If no instrumented code is being executed when `edebug' is called,
that function calls `debug'.

File: elisp,  Node: Trapping Errors,  Next: Edebug Views,  Prev: Breaks,  Up: Edebug

18.2.7 Trapping Errors
----------------------

Emacs normally displays an error message when an error is signaled and
not handled with `condition-case'.  While Edebug is active and
executing instrumented code, it normally responds to all unhandled
errors.  You can customize this with the options `edebug-on-error' and
`edebug-on-quit'; see *note Edebug Options::.

   When Edebug responds to an error, it shows the last stop point
encountered before the error.  This may be the location of a call to a
function which was not instrumented, and within which the error actually
occurred.  For an unbound variable error, the last known stop point
might be quite distant from the offending variable reference.  In that
case, you might want to display a full backtrace (*note Edebug Misc::).

   If you change `debug-on-error' or `debug-on-quit' while Edebug is
active, these changes will be forgotten when Edebug becomes inactive.
Furthermore, during Edebug's recursive edit, these variables are bound
to the values they had outside of Edebug.

File: elisp,  Node: Edebug Views,  Next: Edebug Eval,  Prev: Trapping Errors,  Up: Edebug

18.2.8 Edebug Views
-------------------

These Edebug commands let you view aspects of the buffer and window
status as they were before entry to Edebug.  The outside window
configuration is the collection of windows and contents that were in
effect outside of Edebug.

`v'
     Switch to viewing the outside window configuration
     (`edebug-view-outside').  Type `C-x X w' to return to Edebug.

`p'
     Temporarily display the outside current buffer with point at its
     outside position (`edebug-bounce-point'), pausing for one second
     before returning to Edebug.  With a prefix argument N, pause for N
     seconds instead.

`w'
     Move point back to the current stop point in the source code buffer
     (`edebug-where').

     If you use this command in a different window displaying the same
     buffer, that window will be used instead to display the current
     definition in the future.

`W'
     Toggle whether Edebug saves and restores the outside window
     configuration (`edebug-toggle-save-windows').

     With a prefix argument, `W' only toggles saving and restoring of
     the selected window.  To specify a window that is not displaying
     the source code buffer, you must use `C-x X W' from the global
     keymap.

   You can view the outside window configuration with `v' or just
bounce to the point in the current buffer with `p', even if it is not
normally displayed.

   After moving point, you may wish to jump back to the stop point.
You can do that with `w' from a source code buffer.  You can jump back
to the stop point in the source code buffer from any buffer using `C-x
X w'.

   Each time you use `W' to turn saving _off_, Edebug forgets the saved
outside window configuration--so that even if you turn saving back
_on_, the current window configuration remains unchanged when you next
exit Edebug (by continuing the program).  However, the automatic
redisplay of `*edebug*' and `*edebug-trace*' may conflict with the
buffers you wish to see unless you have enough windows open.

File: elisp,  Node: Edebug Eval,  Next: Eval List,  Prev: Edebug Views,  Up: Edebug

18.2.9 Evaluation
-----------------

While within Edebug, you can evaluate expressions "as if" Edebug were
not running.  Edebug tries to be invisible to the expression's
evaluation and printing.  Evaluation of expressions that cause side
effects will work as expected, except for changes to data that Edebug
explicitly saves and restores.  *Note The Outside Context::, for details
on this process.

`e EXP <RET>'
     Evaluate expression EXP in the context outside of Edebug
     (`edebug-eval-expression').  That is, Edebug tries to minimize its
     interference with the evaluation.

`M-: EXP <RET>'
     Evaluate expression EXP in the context of Edebug itself
     (`eval-expression').

`C-x C-e'
     Evaluate the expression before point, in the context outside of
     Edebug (`edebug-eval-last-sexp').

   Edebug supports evaluation of expressions containing references to
lexically bound symbols created by the following constructs in `cl.el':
`lexical-let', `macrolet', and `symbol-macrolet'.

File: elisp,  Node: Eval List,  Next: Printing in Edebug,  Prev: Edebug Eval,  Up: Edebug

18.2.10 Evaluation List Buffer
------------------------------

You can use the "evaluation list buffer", called `*edebug*', to
evaluate expressions interactively.  You can also set up the
"evaluation list" of expressions to be evaluated automatically each
time Edebug updates the display.

`E'
     Switch to the evaluation list buffer `*edebug*'
     (`edebug-visit-eval-list').

   In the `*edebug*' buffer you can use the commands of Lisp
Interaction mode (*note Lisp Interaction: (emacs)Lisp Interaction.) as
well as these special commands:

`C-j'
     Evaluate the expression before point, in the outside context, and
     insert the value in the buffer (`edebug-eval-print-last-sexp').

`C-x C-e'
     Evaluate the expression before point, in the context outside of
     Edebug (`edebug-eval-last-sexp').

`C-c C-u'
     Build a new evaluation list from the contents of the buffer
     (`edebug-update-eval-list').

`C-c C-d'
     Delete the evaluation list group that point is in
     (`edebug-delete-eval-item').

`C-c C-w'
     Switch back to the source code buffer at the current stop point
     (`edebug-where').

   You can evaluate expressions in the evaluation list window with
`C-j' or `C-x C-e', just as you would in `*scratch*'; but they are
evaluated in the context outside of Edebug.

   The expressions you enter interactively (and their results) are lost
when you continue execution; but you can set up an "evaluation list"
consisting of expressions to be evaluated each time execution stops.

   To do this, write one or more "evaluation list groups" in the
evaluation list buffer.  An evaluation list group consists of one or
more Lisp expressions.  Groups are separated by comment lines.

   The command `C-c C-u' (`edebug-update-eval-list') rebuilds the
evaluation list, scanning the buffer and using the first expression of
each group.  (The idea is that the second expression of the group is the
value previously computed and displayed.)

   Each entry to Edebug redisplays the evaluation list by inserting each
expression in the buffer, followed by its current value.  It also
inserts comment lines so that each expression becomes its own group.
Thus, if you type `C-c C-u' again without changing the buffer text, the
evaluation list is effectively unchanged.

   If an error occurs during an evaluation from the evaluation list,
the error message is displayed in a string as if it were the result.
Therefore, expressions using variables that are not currently valid do
not interrupt your debugging.

   Here is an example of what the evaluation list window looks like
after several expressions have been added to it:

     (current-buffer)
     #<buffer *scratch*>
     ;---------------------------------------------------------------
     (selected-window)
     #<window 16 on *scratch*>
     ;---------------------------------------------------------------
     (point)
     196
     ;---------------------------------------------------------------
     bad-var
     "Symbol's value as variable is void: bad-var"
     ;---------------------------------------------------------------
     (recursion-depth)
     0
     ;---------------------------------------------------------------
     this-command
     eval-last-sexp
     ;---------------------------------------------------------------

   To delete a group, move point into it and type `C-c C-d', or simply
delete the text for the group and update the evaluation list with `C-c
C-u'.  To add a new expression to the evaluation list, insert the
expression at a suitable place, insert a new comment line, then type
`C-c C-u'.  You need not insert dashes in the comment line--its
contents don't matter.

   After selecting `*edebug*', you can return to the source code buffer
with `C-c C-w'.  The `*edebug*' buffer is killed when you continue
execution, and recreated next time it is needed.

File: elisp,  Node: Printing in Edebug,  Next: Trace Buffer,  Prev: Eval List,  Up: Edebug

18.2.11 Printing in Edebug
--------------------------

If an expression in your program produces a value containing circular
list structure, you may get an error when Edebug attempts to print it.

   One way to cope with circular structure is to set `print-length' or
`print-level' to truncate the printing.  Edebug does this for you; it
binds `print-length' and `print-level' to the values of the variables
`edebug-print-length' and `edebug-print-level' (so long as they have
non-`nil' values).  *Note Output Variables::.

 -- User Option: edebug-print-length
     If non-`nil', Edebug binds `print-length' to this value while
     printing results.  The default value is `50'.

 -- User Option: edebug-print-level
     If non-`nil', Edebug binds `print-level' to this value while
     printing results.  The default value is `50'.

   You can also print circular structures and structures that share
elements more informatively by binding `print-circle' to a non-`nil'
value.

   Here is an example of code that creates a circular structure:

     (setq a '(x y))
     (setcar a a)

Custom printing prints this as `Result: #1=(#1# y)'.  The `#1='
notation labels the structure that follows it with the label `1', and
the `#1#' notation references the previously labeled structure.  This
notation is used for any shared elements of lists or vectors.

 -- User Option: edebug-print-circle
     If non-`nil', Edebug binds `print-circle' to this value while
     printing results.  The default value is `t'.

   Other programs can also use custom printing; see `cust-print.el' for
details.

File: elisp,  Node: Trace Buffer,  Next: Coverage Testing,  Prev: Printing in Edebug,  Up: Edebug

18.2.12 Trace Buffer
--------------------

Edebug can record an execution trace, storing it in a buffer named
`*edebug-trace*'.  This is a log of function calls and returns, showing
the function names and their arguments and values.  To enable trace
recording, set `edebug-trace' to a non-`nil' value.

   Making a trace buffer is not the same thing as using trace execution
mode (*note Edebug Execution Modes::).

   When trace recording is enabled, each function entry and exit adds
lines to the trace buffer.  A function entry record consists of
`::::{', followed by the function name and argument values.  A function
exit record consists of `::::}', followed by the function name and
result of the function.

   The number of `:'s in an entry shows its recursion depth.  You can
use the braces in the trace buffer to find the matching beginning or
end of function calls.

   You can customize trace recording for function entry and exit by
redefining the functions `edebug-print-trace-before' and
`edebug-print-trace-after'.

 -- Macro: edebug-tracing string body...
     This macro requests additional trace information around the
     execution of the BODY forms.  The argument STRING specifies text
     to put in the trace buffer, after the `{' or `}'.  All the
     arguments are evaluated, and `edebug-tracing' returns the value of
     the last form in BODY.

 -- Function: edebug-trace format-string &rest format-args
     This function inserts text in the trace buffer.  It computes the
     text with `(apply 'format FORMAT-STRING FORMAT-ARGS)'.  It also
     appends a newline to separate entries.

   `edebug-tracing' and `edebug-trace' insert lines in the trace buffer
whenever they are called, even if Edebug is not active.  Adding text to
the trace buffer also scrolls its window to show the last lines
inserted.

File: elisp,  Node: Coverage Testing,  Next: The Outside Context,  Prev: Trace Buffer,  Up: Edebug

18.2.13 Coverage Testing
------------------------

Edebug provides rudimentary coverage testing and display of execution
frequency.

   Coverage testing works by comparing the result of each expression
with the previous result; each form in the program is considered
"covered" if it has returned two different values since you began
testing coverage in the current Emacs session.  Thus, to do coverage
testing on your program, execute it under various conditions and note
whether it behaves correctly; Edebug will tell you when you have tried
enough different conditions that each form has returned two different
values.

   Coverage testing makes execution slower, so it is only done if
`edebug-test-coverage' is non-`nil'.  Frequency counting is performed
for all executions of an instrumented function, even if the execution
mode is Go-nonstop, and regardless of whether coverage testing is
enabled.

   Use `C-x X =' (`edebug-display-freq-count') to display both the
coverage information and the frequency counts for a definition.  Just
`=' (`edebug-temp-display-freq-count') displays the same information
temporarily, only until you type another key.

 -- Command: edebug-display-freq-count
     This command displays the frequency count data for each line of the
     current definition.

     It inserts frequency counts as comment lines after each line of
     code.  You can undo all insertions with one `undo' command.  The
     counts appear under the `(' before an expression or the `)' after
     an expression, or on the last character of a variable.  To simplify
     the display, a count is not shown if it is equal to the count of an
     earlier expression on the same line.

     The character `=' following the count for an expression says that
     the expression has returned the same value each time it was
     evaluated.  In other words, it is not yet "covered" for coverage
     testing purposes.

     To clear the frequency count and coverage data for a definition,
     simply reinstrument it with `eval-defun'.

   For example, after evaluating `(fac 5)' with a source breakpoint,
and setting `edebug-test-coverage' to `t', when the breakpoint is
reached, the frequency data looks like this:

     (defun fac (n)
       (if (= n 0) (edebug))
     ;#6           1      = =5
       (if (< 0 n)
     ;#5         =
           (* n (fac (1- n)))
     ;#    5               0
         1))
     ;#   0

   The comment lines show that `fac' was called 6 times.  The first
`if' statement returned 5 times with the same result each time; the
same is true of the condition on the second `if'.  The recursive call
of `fac' did not return at all.

File: elisp,  Node: The Outside Context,  Next: Edebug and Macros,  Prev: Coverage Testing,  Up: Edebug

18.2.14 The Outside Context
---------------------------

Edebug tries to be transparent to the program you are debugging, but it
does not succeed completely.  Edebug also tries to be transparent when
you evaluate expressions with `e' or with the evaluation list buffer,
by temporarily restoring the outside context.  This section explains
precisely what context Edebug restores, and how Edebug fails to be
completely transparent.

* Menu:

* Checking Whether to Stop::	When Edebug decides what to do.
* Edebug Display Update::	When Edebug updates the display.
* Edebug Recursive Edit::	When Edebug stops execution.

File: elisp,  Node: Checking Whether to Stop,  Next: Edebug Display Update,  Up: The Outside Context

18.2.14.1 Checking Whether to Stop
..................................

Whenever Edebug is entered, it needs to save and restore certain data
before even deciding whether to make trace information or stop the
program.

   * `max-lisp-eval-depth' and `max-specpdl-size' are both increased to
     reduce Edebug's impact on the stack.  You could, however, still
     run out of stack space when using Edebug.

   * The state of keyboard macro execution is saved and restored.  While
     Edebug is active, `executing-kbd-macro' is bound to `nil' unless
     `edebug-continue-kbd-macro' is non-`nil'.

File: elisp,  Node: Edebug Display Update,  Next: Edebug Recursive Edit,  Prev: Checking Whether to Stop,  Up: The Outside Context

18.2.14.2 Edebug Display Update
...............................

When Edebug needs to display something (e.g., in trace mode), it saves
the current window configuration from "outside" Edebug (*note Window
Configurations::).  When you exit Edebug (by continuing the program),
it restores the previous window configuration.

   Emacs redisplays only when it pauses.  Usually, when you continue
execution, the program re-enters Edebug at a breakpoint or after
stepping, without pausing or reading input in between.  In such cases,
Emacs never gets a chance to redisplay the "outside" configuration.
Consequently, what you see is the same window configuration as the last
time Edebug was active, with no interruption.

   Entry to Edebug for displaying something also saves and restores the
following data (though some of them are deliberately not restored if an
error or quit signal occurs).

   * Which buffer is current, and the positions of point and the mark
     in the current buffer, are saved and restored.

   * The outside window configuration is saved and restored if
     `edebug-save-windows' is non-`nil' (*note Edebug Options::).

     The window configuration is not restored on error or quit, but the
     outside selected window _is_ reselected even on error or quit in
     case a `save-excursion' is active.  If the value of
     `edebug-save-windows' is a list, only the listed windows are saved
     and restored.

     The window start and horizontal scrolling of the source code
     buffer are not restored, however, so that the display remains
     coherent within Edebug.

   * The value of point in each displayed buffer is saved and restored
     if `edebug-save-displayed-buffer-points' is non-`nil'.

   * The variables `overlay-arrow-position' and `overlay-arrow-string'
     are saved and restored, so you can safely invoke Edebug from the
     recursive edit elsewhere in the same buffer.

   * `cursor-in-echo-area' is locally bound to `nil' so that the cursor
     shows up in the window.

File: elisp,  Node: Edebug Recursive Edit,  Prev: Edebug Display Update,  Up: The Outside Context

18.2.14.3 Edebug Recursive Edit
...............................

When Edebug is entered and actually reads commands from the user, it
saves (and later restores) these additional data:

   * The current match data.  *Note Match Data::.

   * The variables `last-command', `this-command', `last-input-event',
     `last-command-event', `last-event-frame', `last-nonmenu-event', and
     `track-mouse'.  Commands used within Edebug do not affect these
     variables outside of Edebug.

     Executing commands within Edebug can change the key sequence that
     would be returned by `this-command-keys', and there is no way to
     reset the key sequence from Lisp.

     Edebug cannot save and restore the value of
     `unread-command-events'.  Entering Edebug while this variable has a
     nontrivial value can interfere with execution of the program you
     are debugging.

   * Complex commands executed while in Edebug are added to the variable
     `command-history'.  In rare cases this can alter execution.

   * Within Edebug, the recursion depth appears one deeper than the
     recursion depth outside Edebug.  This is not true of the
     automatically updated evaluation list window.

   * `standard-output' and `standard-input' are bound to `nil' by the
     `recursive-edit', but Edebug temporarily restores them during
     evaluations.

   * The state of keyboard macro definition is saved and restored.
     While Edebug is active, `defining-kbd-macro' is bound to
     `edebug-continue-kbd-macro'.

File: elisp,  Node: Edebug and Macros,  Next: Edebug Options,  Prev: The Outside Context,  Up: Edebug

18.2.15 Edebug and Macros
-------------------------

To make Edebug properly instrument expressions that call macros, some
extra care is needed.  This subsection explains the details.

* Menu:

* Instrumenting Macro Calls::   The basic problem.
* Specification List::		How to specify complex patterns of evaluation.
* Backtracking::		What Edebug does when matching fails.
* Specification Examples::	To help understand specifications.

File: elisp,  Node: Instrumenting Macro Calls,  Next: Specification List,  Up: Edebug and Macros

18.2.15.1 Instrumenting Macro Calls
...................................

When Edebug instruments an expression that calls a Lisp macro, it needs
additional information about the macro to do the job properly.  This is
because there is no a-priori way to tell which subexpressions of the
macro call are forms to be evaluated.  (Evaluation may occur explicitly
in the macro body, or when the resulting expansion is evaluated, or any
time later.)

   Therefore, you must define an Edebug specification for each macro
that Edebug will encounter, to explain the format of calls to that
macro.  To do this, add a `debug' declaration to the macro definition.
Here is a simple example that shows the specification for the `for'
example macro (*note Argument Evaluation::).

     (defmacro for (var from init to final do &rest body)
       "Execute a simple \"for\" loop.
     For example, (for i from 1 to 10 do (print i))."
       (declare (debug (symbolp "from" form "to" form "do" &rest form)))
       ...)

   The Edebug specification says which parts of a call to the macro are
forms to be evaluated.  For simple macros, the specification often
looks very similar to the formal argument list of the macro definition,
but specifications are much more general than macro arguments.  *Note
Defining Macros::, for more explanation of the `declare' form.

   You can also define an edebug specification for a macro separately
from the macro definition with `def-edebug-spec'.  Adding `debug'
declarations is preferred, and more convenient, for macro definitions
in Lisp, but `def-edebug-spec' makes it possible to define Edebug
specifications for special forms implemented in C.

 -- Macro: def-edebug-spec macro specification
     Specify which expressions of a call to macro MACRO are forms to be
     evaluated.  SPECIFICATION should be the edebug specification.
     Neither argument is evaluated.

     The MACRO argument can actually be any symbol, not just a macro
     name.

   Here is a table of the possibilities for SPECIFICATION and how each
directs processing of arguments.

`t'
     All arguments are instrumented for evaluation.

`0'
     None of the arguments is instrumented.

a symbol
     The symbol must have an Edebug specification, which is used
     instead.  This indirection is repeated until another kind of
     specification is found.  This allows you to inherit the
     specification from another macro.

a list
     The elements of the list describe the types of the arguments of a
     calling form.  The possible elements of a specification list are
     described in the following sections.

   If a macro has no Edebug specification, neither through a `debug'
declaration nor through a `def-edebug-spec' call, the variable
`edebug-eval-macro-args' comes into play.

 -- User Option: edebug-eval-macro-args
     This controls the way Edebug treats macro arguments with no
     explicit Edebug specification.  If it is `nil' (the default), none
     of the arguments is instrumented for evaluation.  Otherwise, all
     arguments are instrumented.

File: elisp,  Node: Specification List,  Next: Backtracking,  Prev: Instrumenting Macro Calls,  Up: Edebug and Macros

18.2.15.2 Specification List
............................

A "specification list" is required for an Edebug specification if some
arguments of a macro call are evaluated while others are not.  Some
elements in a specification list match one or more arguments, but others
modify the processing of all following elements.  The latter, called
"specification keywords", are symbols beginning with `&' (such as
`&optional').

   A specification list may contain sublists which match arguments that
are themselves lists, or it may contain vectors used for grouping.
Sublists and groups thus subdivide the specification list into a
hierarchy of levels.  Specification keywords apply only to the
remainder of the sublist or group they are contained in.

   When a specification list involves alternatives or repetition,
matching it against an actual macro call may require backtracking.  For
more details, *note Backtracking::.

   Edebug specifications provide the power of regular expression
matching, plus some context-free grammar constructs: the matching of
sublists with balanced parentheses, recursive processing of forms, and
recursion via indirect specifications.

   Here's a table of the possible elements of a specification list, with
their meanings (see *note Specification Examples::, for the referenced
examples):

`sexp'
     A single unevaluated Lisp object, which is not instrumented.

`form'
     A single evaluated expression, which is instrumented.

`place'
     A place to store a value, as in the Common Lisp `setf' construct.

`body'
     Short for `&rest form'.  See `&rest' below.

`function-form'
     A function form: either a quoted function symbol, a quoted lambda
     expression, or a form (that should evaluate to a function symbol or
     lambda expression).  This is useful when an argument that's a
     lambda expression might be quoted with `quote' rather than
     `function', since it instruments the body of the lambda expression
     either way.

`lambda-expr'
     A lambda expression with no quoting.

`&optional'
     All following elements in the specification list are optional; as
     soon as one does not match, Edebug stops matching at this level.

     To make just a few elements optional followed by non-optional
     elements, use `[&optional SPECS...]'.  To specify that several
     elements must all match or none, use `&optional [SPECS...]'.  See
     the `defun' example.

`&rest'
     All following elements in the specification list are repeated zero
     or more times.  In the last repetition, however, it is not a
     problem if the expression runs out before matching all of the
     elements of the specification list.

     To repeat only a few elements, use `[&rest SPECS...]'.  To specify
     several elements that must all match on every repetition, use
     `&rest [SPECS...]'.

`&or'
     Each of the following elements in the specification list is an
     alternative.  One of the alternatives must match, or the `&or'
     specification fails.

     Each list element following `&or' is a single alternative.  To
     group two or more list elements as a single alternative, enclose
     them in `[...]'.

`&not'
     Each of the following elements is matched as alternatives as if by
     using `&or', but if any of them match, the specification fails.
     If none of them match, nothing is matched, but the `&not'
     specification succeeds.

`&define'
     Indicates that the specification is for a defining form.  The
     defining form itself is not instrumented (that is, Edebug does not
     stop before and after the defining form), but forms inside it
     typically will be instrumented.  The `&define' keyword should be
     the first element in a list specification.

`nil'
     This is successful when there are no more arguments to match at the
     current argument list level; otherwise it fails.  See sublist
     specifications and the backquote example.

`gate'
     No argument is matched but backtracking through the gate is
     disabled while matching the remainder of the specifications at
     this level.  This is primarily used to generate more specific
     syntax error messages.  See *note Backtracking::, for more
     details.  Also see the `let' example.

`OTHER-SYMBOL'
     Any other symbol in a specification list may be a predicate or an
     indirect specification.

     If the symbol has an Edebug specification, this "indirect
     specification" should be either a list specification that is used
     in place of the symbol, or a function that is called to process the
     arguments.  The specification may be defined with `def-edebug-spec'
     just as for macros.  See the `defun' example.

     Otherwise, the symbol should be a predicate.  The predicate is
     called with the argument and the specification fails if the
     predicate returns `nil', and the argument is not instrumented.

     Some suitable predicates include `symbolp', `integerp', `stringp',
     `vectorp', and `atom'.

`[ELEMENTS...]'
     A vector of elements groups the elements into a single "group
     specification".  Its meaning has nothing to do with vectors.

`"STRING"'
     The argument should be a symbol named STRING.  This specification
     is equivalent to the quoted symbol, `'SYMBOL', where the name of
     SYMBOL is the STRING, but the string form is preferred.

`(vector ELEMENTS...)'
     The argument should be a vector whose elements must match the
     ELEMENTS in the specification.  See the backquote example.

`(ELEMENTS...)'
     Any other list is a "sublist specification" and the argument must
     be a list whose elements match the specification ELEMENTS.

     A sublist specification may be a dotted list and the corresponding
     list argument may then be a dotted list.  Alternatively, the last
     CDR of a dotted list specification may be another sublist
     specification (via a grouping or an indirect specification, e.g.,
     `(spec .  [(more specs...)])') whose elements match the non-dotted
     list arguments.  This is useful in recursive specifications such
     as in the backquote example.  Also see the description of a `nil'
     specification above for terminating such recursion.

     Note that a sublist specification written as `(specs .  nil)' is
     equivalent to `(specs)', and `(specs .  (sublist-elements...))' is
     equivalent to `(specs sublist-elements...)'.

   Here is a list of additional specifications that may appear only
after `&define'.  See the `defun' example.

`name'
     The argument, a symbol, is the name of the defining form.

     A defining form is not required to have a name field; and it may
     have multiple name fields.

`:name'
     This construct does not actually match an argument.  The element
     following `:name' should be a symbol; it is used as an additional
     name component for the definition.  You can use this to add a
     unique, static component to the name of the definition.  It may be
     used more than once.

`arg'
     The argument, a symbol, is the name of an argument of the defining
     form.  However, lambda-list keywords (symbols starting with `&')
     are not allowed.

`lambda-list'
     This matches a lambda list--the argument list of a lambda
     expression.

`def-body'
     The argument is the body of code in a definition.  This is like
     `body', described above, but a definition body must be instrumented
     with a different Edebug call that looks up information associated
     with the definition.  Use `def-body' for the highest level list of
     forms within the definition.

`def-form'
     The argument is a single, highest-level form in a definition.
     This is like `def-body', except it is used to match a single form
     rather than a list of forms.  As a special case, `def-form' also
     means that tracing information is not output when the form is
     executed.  See the `interactive' example.

File: elisp,  Node: Backtracking,  Next: Specification Examples,  Prev: Specification List,  Up: Edebug and Macros

18.2.15.3 Backtracking in Specifications
........................................

If a specification fails to match at some point, this does not
necessarily mean a syntax error will be signaled; instead,
"backtracking" will take place until all alternatives have been
exhausted.  Eventually every element of the argument list must be
matched by some element in the specification, and every required element
in the specification must match some argument.

   When a syntax error is detected, it might not be reported until much
later, after higher-level alternatives have been exhausted, and with the
point positioned further from the real error.  But if backtracking is
disabled when an error occurs, it can be reported immediately.  Note
that backtracking is also reenabled automatically in several situations;
when a new alternative is established by `&optional', `&rest', or
`&or', or at the start of processing a sublist, group, or indirect
specification.  The effect of enabling or disabling backtracking is
limited to the remainder of the level currently being processed and
lower levels.

   Backtracking is disabled while matching any of the form
specifications (that is, `form', `body', `def-form', and `def-body').
These specifications will match any form so any error must be in the
form itself rather than at a higher level.

   Backtracking is also disabled after successfully matching a quoted
symbol or string specification, since this usually indicates a
recognized construct.  But if you have a set of alternative constructs
that all begin with the same symbol, you can usually work around this
constraint by factoring the symbol out of the alternatives, e.g.,
`["foo" &or [first case] [second case] ...]'.

   Most needs are satisfied by these two ways that backtracking is
automatically disabled, but occasionally it is useful to explicitly
disable backtracking by using the `gate' specification.  This is useful
when you know that no higher alternatives could apply.  See the example
of the `let' specification.

File: elisp,  Node: Specification Examples,  Prev: Backtracking,  Up: Edebug and Macros

18.2.15.4 Specification Examples
................................

It may be easier to understand Edebug specifications by studying the
examples provided here.

   A `let' special form has a sequence of bindings and a body.  Each of
the bindings is either a symbol or a sublist with a symbol and optional
expression.  In the specification below, notice the `gate' inside of
the sublist to prevent backtracking once a sublist is found.

     (def-edebug-spec let
       ((&rest
         &or symbolp (gate symbolp &optional form))
        body))

   Edebug uses the following specifications for `defun' and the
associated argument list and `interactive' specifications.  It is
necessary to handle interactive forms specially since an expression
argument is actually evaluated outside of the function body.  (The
specification for `defmacro' is very similar to that for `defun', but
allows for the `declare' statement.)

     (def-edebug-spec defun
       (&define name lambda-list
                [&optional stringp]   ; Match the doc string, if present.
                [&optional ("interactive" interactive)]
                def-body))

     (def-edebug-spec lambda-list
       (([&rest arg]
         [&optional ["&optional" arg &rest arg]]
         &optional ["&rest" arg]
         )))

     (def-edebug-spec interactive
       (&optional &or stringp def-form))    ; Notice: `def-form'

   The specification for backquote below illustrates how to match
dotted lists and use `nil' to terminate recursion.  It also illustrates
how components of a vector may be matched.  (The actual specification
defined by Edebug is a little different, and does not support dotted
lists because doing so causes very deep recursion that could fail.)

     (def-edebug-spec \` (backquote-form))   ; Alias just for clarity.

     (def-edebug-spec backquote-form
       (&or ([&or "," ",@"] &or ("quote" backquote-form) form)
            (backquote-form . [&or nil backquote-form])
            (vector &rest backquote-form)
            sexp))

File: elisp,  Node: Edebug Options,  Prev: Edebug and Macros,  Up: Edebug

18.2.16 Edebug Options
----------------------

These options affect the behavior of Edebug:

 -- User Option: edebug-setup-hook
     Functions to call before Edebug is used.  Each time it is set to a
     new value, Edebug will call those functions once and then
     `edebug-setup-hook' is reset to `nil'.  You could use this to load
     up Edebug specifications associated with a package you are using
     but only when you also use Edebug.  *Note Instrumenting::.

 -- User Option: edebug-all-defs
     If this is non-`nil', normal evaluation of defining forms such as
     `defun' and `defmacro' instruments them for Edebug.  This applies
     to `eval-defun', `eval-region', `eval-buffer', and
     `eval-current-buffer'.

     Use the command `M-x edebug-all-defs' to toggle the value of this
     option.  *Note Instrumenting::.

 -- User Option: edebug-all-forms
     If this is non-`nil', the commands `eval-defun', `eval-region',
     `eval-buffer', and `eval-current-buffer' instrument all forms,
     even those that don't define anything.  This doesn't apply to
     loading or evaluations in the minibuffer.

     Use the command `M-x edebug-all-forms' to toggle the value of this
     option.  *Note Instrumenting::.

 -- User Option: edebug-save-windows
     If this is non-`nil', Edebug saves and restores the window
     configuration.  That takes some time, so if your program does not
     care what happens to the window configurations, it is better to
     set this variable to `nil'.

     If the value is a list, only the listed windows are saved and
     restored.

     You can use the `W' command in Edebug to change this variable
     interactively.  *Note Edebug Display Update::.

 -- User Option: edebug-save-displayed-buffer-points
     If this is non-`nil', Edebug saves and restores point in all
     displayed buffers.

     Saving and restoring point in other buffers is necessary if you are
     debugging code that changes the point of a buffer that is
     displayed in a non-selected window.  If Edebug or the user then
     selects the window, point in that buffer will move to the window's
     value of point.

     Saving and restoring point in all buffers is expensive, since it
     requires selecting each window twice, so enable this only if you
     need it.  *Note Edebug Display Update::.

 -- User Option: edebug-initial-mode
     If this variable is non-`nil', it specifies the initial execution
     mode for Edebug when it is first activated.  Possible values are
     `step', `next', `go', `Go-nonstop', `trace', `Trace-fast',
     `continue', and `Continue-fast'.

     The default value is `step'.  *Note Edebug Execution Modes::.

 -- User Option: edebug-trace
     If this is non-`nil', trace each function entry and exit.  Tracing
     output is displayed in a buffer named `*edebug-trace*', one
     function entry or exit per line, indented by the recursion level.

     Also see `edebug-tracing', in *note Trace Buffer::.

 -- User Option: edebug-test-coverage
     If non-`nil', Edebug tests coverage of all expressions debugged.
     *Note Coverage Testing::.

 -- User Option: edebug-continue-kbd-macro
     If non-`nil', continue defining or executing any keyboard macro
     that is executing outside of Edebug.   Use this with caution since
     it is not debugged.  *Note Edebug Execution Modes::.

 -- User Option: edebug-on-error
     Edebug binds `debug-on-error' to this value, if `debug-on-error'
     was previously `nil'.  *Note Trapping Errors::.

 -- User Option: edebug-on-quit
     Edebug binds `debug-on-quit' to this value, if `debug-on-quit' was
     previously `nil'.  *Note Trapping Errors::.

   If you change the values of `edebug-on-error' or `edebug-on-quit'
while Edebug is active, their values won't be used until the _next_
time Edebug is invoked via a new command.

 -- User Option: edebug-global-break-condition
     If non-`nil', an expression to test for at every stop point.  If
     the result is non-`nil', then break.  Errors are ignored.  *Note
     Global Break Condition::.

File: elisp,  Node: Syntax Errors,  Next: Test Coverage,  Prev: Edebug,  Up: Debugging

18.3 Debugging Invalid Lisp Syntax
==================================

The Lisp reader reports invalid syntax, but cannot say where the real
problem is.  For example, the error "End of file during parsing" in
evaluating an expression indicates an excess of open parentheses (or
square brackets).  The reader detects this imbalance at the end of the
file, but it cannot figure out where the close parenthesis should have
been.  Likewise, "Invalid read syntax: ")"" indicates an excess close
parenthesis or missing open parenthesis, but does not say where the
missing parenthesis belongs.  How, then, to find what to change?

   If the problem is not simply an imbalance of parentheses, a useful
technique is to try `C-M-e' at the beginning of each defun, and see if
it goes to the place where that defun appears to end.  If it does not,
there is a problem in that defun.

   However, unmatched parentheses are the most common syntax errors in
Lisp, and we can give further advice for those cases.  (In addition,
just moving point through the code with Show Paren mode enabled might
find the mismatch.)

* Menu:

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

File: elisp,  Node: Excess Open,  Next: Excess Close,  Up: Syntax Errors

18.3.1 Excess Open Parentheses
------------------------------

The first step is to find the defun that is unbalanced.  If there is an
excess open parenthesis, the way to do this is to go to the end of the
file and type `C-u C-M-u'.  This will move you to the beginning of the
first defun that is unbalanced.

   The next step is to determine precisely what is wrong.  There is no
way to be sure of this except by studying the program, but often the
existing indentation is a clue to where the parentheses should have
been.  The easiest way to use this clue is to reindent with `C-M-q' and
see what moves.  *But don't do this yet!*  Keep reading, first.

   Before you do this, make sure the defun has enough close parentheses.
Otherwise, `C-M-q' will get an error, or will reindent all the rest of
the file until the end.  So move to the end of the defun and insert a
close parenthesis there.  Don't use `C-M-e' to move there, since that
too will fail to work until the defun is balanced.

   Now you can go to the beginning of the defun and type `C-M-q'.
Usually all the lines from a certain point to the end of the function
will shift to the right.  There is probably a missing close parenthesis,
or a superfluous open parenthesis, near that point.  (However, don't
assume this is true; study the code to make sure.)  Once you have found
the discrepancy, undo the `C-M-q' with `C-_', since the old indentation
is probably appropriate to the intended parentheses.

   After you think you have fixed the problem, use `C-M-q' again.  If
the old indentation actually fit the intended nesting of parentheses,
and you have put back those parentheses, `C-M-q' should not change
anything.

File: elisp,  Node: Excess Close,  Prev: Excess Open,  Up: Syntax Errors

18.3.2 Excess Close Parentheses
-------------------------------

To deal with an excess close parenthesis, first go to the beginning of
the file, then type `C-u -1 C-M-u' to find the end of the first
unbalanced defun.

   Then find the actual matching close parenthesis by typing `C-M-f' at
the beginning of that defun.  This will leave you somewhere short of
the place where the defun ought to end.  It is possible that you will
find a spurious close parenthesis in that vicinity.

   If you don't see a problem at that point, the next thing to do is to
type `C-M-q' at the beginning of the defun.  A range of lines will
probably shift left; if so, the missing open parenthesis or spurious
close parenthesis is probably near the first of those lines.  (However,
don't assume this is true; study the code to make sure.)  Once you have
found the discrepancy, undo the `C-M-q' with `C-_', since the old
indentation is probably appropriate to the intended parentheses.

   After you think you have fixed the problem, use `C-M-q' again.  If
the old indentation actually fits the intended nesting of parentheses,
and you have put back those parentheses, `C-M-q' should not change
anything.

File: elisp,  Node: Test Coverage,  Next: Compilation Errors,  Prev: Syntax Errors,  Up: Debugging

18.4 Test Coverage
==================

You can do coverage testing for a file of Lisp code by loading the
`testcover' library and using the command `M-x testcover-start <RET>
FILE <RET>' to instrument the code.  Then test your code by calling it
one or more times.  Then use the command `M-x testcover-mark-all' to
display colored highlights on the code to show where coverage is
insufficient.  The command `M-x testcover-next-mark' will move point
forward to the next highlighted spot.

   Normally, a red highlight indicates the form was never completely
evaluated; a brown highlight means it always evaluated to the same
value (meaning there has been little testing of what is done with the
result).  However, the red highlight is skipped for forms that can't
possibly complete their evaluation, such as `error'.  The brown
highlight is skipped for forms that are expected to always evaluate to
the same value, such as `(setq x 14)'.

   For difficult cases, you can add do-nothing macros to your code to
give advice to the test coverage tool.

 -- Macro: 1value form
     Evaluate FORM and return its value, but inform coverage testing
     that FORM's value should always be the same.

 -- Macro: noreturn form
     Evaluate FORM, informing coverage testing that FORM should never
     return.  If it ever does return, you get a run-time error.

   Edebug also has a coverage testing feature (*note Coverage
Testing::).  These features partly duplicate each other, and it would
be cleaner to combine them.

File: elisp,  Node: Compilation Errors,  Prev: Test Coverage,  Up: Debugging

18.5 Debugging Problems in Compilation
======================================

When an error happens during byte compilation, it is normally due to
invalid syntax in the program you are compiling.  The compiler prints a
suitable error message in the `*Compile-Log*' buffer, and then stops.
The message may state a function name in which the error was found, or
it may not.  Either way, here is how to find out where in the file the
error occurred.

   What you should do is switch to the buffer ` *Compiler Input*'.
(Note that the buffer name starts with a space, so it does not show up
in `M-x list-buffers'.)  This buffer contains the program being
compiled, and point shows how far the byte compiler was able to read.

   If the error was due to invalid Lisp syntax, point shows exactly
where the invalid syntax was _detected_.  The cause of the error is not
necessarily near by!  Use the techniques in the previous section to find
the error.

   If the error was detected while compiling a form that had been read
successfully, then point is located at the end of the form.  In this
case, this technique can't localize the error precisely, but can still
show you which function to check.

File: elisp,  Node: Read and Print,  Next: Minibuffers,  Prev: Debugging,  Up: Top

19 Reading and Printing Lisp Objects
************************************

"Printing" and "reading" are the operations of converting Lisp objects
to textual form and vice versa.  They use the printed representations
and read syntax described in *note Lisp Data Types::.

   This chapter describes the Lisp functions for reading and printing.
It also describes "streams", which specify where to get the text (if
reading) or where to put it (if printing).

* Menu:

* 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.
* Output Variables::  Variables that control what the printing functions do.

File: elisp,  Node: Streams Intro,  Next: Input Streams,  Up: Read and Print

19.1 Introduction to Reading and Printing
=========================================

"Reading" a Lisp object means parsing a Lisp expression in textual form
and producing a corresponding Lisp object.  This is how Lisp programs
get into Lisp from files of Lisp code.  We call the text the "read
syntax" of the object.  For example, the text `(a . 5)' is the read
syntax for a cons cell whose CAR is `a' and whose CDR is the number 5.

   "Printing" a Lisp object means producing text that represents that
object--converting the object to its "printed representation" (*note
Printed Representation::).  Printing the cons cell described above
produces the text `(a . 5)'.

   Reading and printing are more or less inverse operations: printing
the object that results from reading a given piece of text often
produces the same text, and reading the text that results from printing
an object usually produces a similar-looking object.  For example,
printing the symbol `foo' produces the text `foo', and reading that text
returns the symbol `foo'.  Printing a list whose elements are `a' and
`b' produces the text `(a b)', and reading that text produces a list
(but not the same list) with elements `a' and `b'.

   However, these two operations are not precisely inverse to each
other.  There are three kinds of exceptions:

   * Printing can produce text that cannot be read.  For example,
     buffers, windows, frames, subprocesses and markers print as text
     that starts with `#'; if you try to read this text, you get an
     error.  There is no way to read those data types.

   * One object can have multiple textual representations.  For example,
     `1' and `01' represent the same integer, and `(a b)' and `(a .
     (b))' represent the same list.  Reading will accept any of the
     alternatives, but printing must choose one of them.

   * Comments can appear at certain points in the middle of an object's
     read sequence without affecting the result of reading it.

File: elisp,  Node: Input Streams,  Next: Input Functions,  Prev: Streams Intro,  Up: Read and Print

19.2 Input Streams
==================

Most of the Lisp functions for reading text take an "input stream" as
an argument.  The input stream specifies where or how to get the
characters of the text to be read.  Here are the possible types of input
stream:

BUFFER
     The input characters are read from BUFFER, starting with the
     character directly after point.  Point advances as characters are
     read.

MARKER
     The input characters are read from the buffer that MARKER is in,
     starting with the character directly after the marker.  The marker
     position advances as characters are read.  The value of point in
     the buffer has no effect when the stream is a marker.

STRING
     The input characters are taken from STRING, starting at the first
     character in the string and using as many characters as required.

FUNCTION
     The input characters are generated by FUNCTION, which must support
     two kinds of calls:

        * When it is called with no arguments, it should return the
          next character.

        * When it is called with one argument (always a character),
          FUNCTION should save the argument and arrange to return it on
          the next call.  This is called "unreading" the character; it
          happens when the Lisp reader reads one character too many and
          wants to "put it back where it came from."  In this case, it
          makes no difference what value FUNCTION returns.

`t'
     `t' used as a stream means that the input is read from the
     minibuffer.  In fact, the minibuffer is invoked once and the text
     given by the user is made into a string that is then used as the
     input stream.  If Emacs is running in batch mode, standard input
     is used instead of the minibuffer.  For example,
          (message "%s" (read t))
     will read a Lisp expression from standard input and print the
     result to standard output.

`nil'
     `nil' supplied as an input stream means to use the value of
     `standard-input' instead; that value is the "default input
     stream", and must be a non-`nil' input stream.

SYMBOL
     A symbol as input stream is equivalent to the symbol's function
     definition (if any).

   Here is an example of reading from a stream that is a buffer, showing
where point is located before and after:

     ---------- Buffer: foo ----------
     This-!- is the contents of foo.
     ---------- Buffer: foo ----------

     (read (get-buffer "foo"))
          => is
     (read (get-buffer "foo"))
          => the

     ---------- Buffer: foo ----------
     This is the-!- contents of foo.
     ---------- Buffer: foo ----------

Note that the first read skips a space.  Reading skips any amount of
whitespace preceding the significant text.

   Here is an example of reading from a stream that is a marker,
initially positioned at the beginning of the buffer shown.  The value
read is the symbol `This'.


     ---------- Buffer: foo ----------
     This is the contents of foo.
     ---------- Buffer: foo ----------

     (setq m (set-marker (make-marker) 1 (get-buffer "foo")))
          => #<marker at 1 in foo>
     (read m)
          => This
     m
          => #<marker at 5 in foo>   ;; Before the first space.

   Here we read from the contents of a string:

     (read "(When in) the course")
          => (When in)

   The following example reads from the minibuffer.  The prompt is:
`Lisp expression: '.  (That is always the prompt used when you read
from the stream `t'.)  The user's input is shown following the prompt.

     (read t)
          => 23
     ---------- Buffer: Minibuffer ----------
     Lisp expression: 23 <RET>
     ---------- Buffer: Minibuffer ----------

   Finally, here is an example of a stream that is a function, named
`useless-stream'.  Before we use the stream, we initialize the variable
`useless-list' to a list of characters.  Then each call to the function
`useless-stream' obtains the next character in the list or unreads a
character by adding it to the front of the list.

     (setq useless-list (append "XY()" nil))
          => (88 89 40 41)

     (defun useless-stream (&optional unread)
       (if unread
           (setq useless-list (cons unread useless-list))
         (prog1 (car useless-list)
                (setq useless-list (cdr useless-list)))))
          => useless-stream

Now we read using the stream thus constructed:

     (read 'useless-stream)
          => XY

     useless-list
          => (40 41)

Note that the open and close parentheses remain in the list.  The Lisp
reader encountered the open parenthesis, decided that it ended the
input, and unread it.  Another attempt to read from the stream at this
point would read `()' and return `nil'.

 -- Function: get-file-char
     This function is used internally as an input stream to read from
     the input file opened by the function `load'.  Don't use this
     function yourself.

File: elisp,  Node: Input Functions,  Next: Output Streams,  Prev: Input Streams,  Up: Read and Print

19.3 Input Functions
====================

This section describes the Lisp functions and variables that pertain to
reading.

   In the functions below, STREAM stands for an input stream (see the
previous section).  If STREAM is `nil' or omitted, it defaults to the
value of `standard-input'.

   An `end-of-file' error is signaled if reading encounters an
unterminated list, vector, or string.

 -- Function: read &optional stream
     This function reads one textual Lisp expression from STREAM,
     returning it as a Lisp object.  This is the basic Lisp input
     function.

 -- Function: read-from-string string &optional start end
     This function reads the first textual Lisp expression from the
     text in STRING.  It returns a cons cell whose CAR is that
     expression, and whose CDR is an integer giving the position of the
     next remaining character in the string (i.e., the first one not
     read).

     If START is supplied, then reading begins at index START in the
     string (where the first character is at index 0).  If you specify
     END, then reading is forced to stop just before that index, as if
     the rest of the string were not there.

     For example:

          (read-from-string "(setq x 55) (setq y 5)")
               => ((setq x 55) . 11)
          (read-from-string "\"A short string\"")
               => ("A short string" . 16)

          ;; Read starting at the first character.
          (read-from-string "(list 112)" 0)
               => ((list 112) . 10)
          ;; Read starting at the second character.
          (read-from-string "(list 112)" 1)
               => (list . 5)
          ;; Read starting at the seventh character,
          ;;   and stopping at the ninth.
          (read-from-string "(list 112)" 6 8)
               => (11 . 8)

 -- Variable: standard-input
     This variable holds the default input stream--the stream that
     `read' uses when the STREAM argument is `nil'.  The default is
     `t', meaning use the minibuffer.

 -- Variable: read-circle
     If non-`nil', this variable enables the reading of circular and
     shared structures.  *Note Circular Objects::.  Its default value is
     `t'.

File: elisp,  Node: Output Streams,  Next: Output Functions,  Prev: Input Functions,  Up: Read and Print

19.4 Output Streams
===================

An output stream specifies what to do with the characters produced by
printing.  Most print functions accept an output stream as an optional
argument.  Here are the possible types of output stream:

BUFFER
     The output characters are inserted into BUFFER at point.  Point
     advances as characters are inserted.

MARKER
     The output characters are inserted into the buffer that MARKER
     points into, at the marker position.  The marker position advances
     as characters are inserted.  The value of point in the buffer has
     no effect on printing when the stream is a marker, and this kind
     of printing does not move point (except that if the marker points
     at or before the position of point, point advances with the
     surrounding text, as usual).

FUNCTION
     The output characters are passed to FUNCTION, which is responsible
     for storing them away.  It is called with a single character as
     argument, as many times as there are characters to be output, and
     is responsible for storing the characters wherever you want to put
     them.

`t'
     The output characters are displayed in the echo area.

`nil'
     `nil' specified as an output stream means to use the value of
     `standard-output' instead; that value is the "default output
     stream", and must not be `nil'.

SYMBOL
     A symbol as output stream is equivalent to the symbol's function
     definition (if any).

   Many of the valid output streams are also valid as input streams.
The difference between input and output streams is therefore more a
matter of how you use a Lisp object, than of different types of object.

   Here is an example of a buffer used as an output stream.  Point is
initially located as shown immediately before the `h' in `the'.  At the
end, point is located directly before that same `h'.

     ---------- Buffer: foo ----------
     This is t-!-he contents of foo.
     ---------- Buffer: foo ----------

     (print "This is the output" (get-buffer "foo"))
          => "This is the output"

     ---------- Buffer: foo ----------
     This is t
     "This is the output"
     -!-he contents of foo.
     ---------- Buffer: foo ----------

   Now we show a use of a marker as an output stream.  Initially, the
marker is in buffer `foo', between the `t' and the `h' in the word
`the'.  At the end, the marker has advanced over the inserted text so
that it remains positioned before the same `h'.  Note that the location
of point, shown in the usual fashion, has no effect.

     ---------- Buffer: foo ----------
     This is the -!-output
     ---------- Buffer: foo ----------

     (setq m (copy-marker 10))
          => #<marker at 10 in foo>

     (print "More output for foo." m)
          => "More output for foo."

     ---------- Buffer: foo ----------
     This is t
     "More output for foo."
     he -!-output
     ---------- Buffer: foo ----------

     m
          => #<marker at 34 in foo>

   The following example shows output to the echo area:

     (print "Echo Area output" t)
          => "Echo Area output"
     ---------- Echo Area ----------
     "Echo Area output"
     ---------- Echo Area ----------

   Finally, we show the use of a function as an output stream.  The
function `eat-output' takes each character that it is given and conses
it onto the front of the list `last-output' (*note Building Lists::).
At the end, the list contains all the characters output, but in reverse
order.

     (setq last-output nil)
          => nil

     (defun eat-output (c)
       (setq last-output (cons c last-output)))
          => eat-output

     (print "This is the output" 'eat-output)
          => "This is the output"

     last-output
          => (10 34 116 117 112 116 117 111 32 101 104
         116 32 115 105 32 115 105 104 84 34 10)

Now we can put the output in the proper order by reversing the list:

     (concat (nreverse last-output))
          => "
     \"This is the output\"
     "

Calling `concat' converts the list to a string so you can see its
contents more clearly.

File: elisp,  Node: Output Functions,  Next: Output Variables,  Prev: Output Streams,  Up: Read and Print

19.5 Output Functions
=====================

This section describes the Lisp functions for printing Lisp
objects--converting objects into their printed representation.

   Some of the Emacs printing functions add quoting characters to the
output when necessary so that it can be read properly.  The quoting
characters used are `"' and `\'; they distinguish strings from symbols,
and prevent punctuation characters in strings and symbols from being
taken as delimiters when reading.  *Note Printed Representation::, for
full details.  You specify quoting or no quoting by the choice of
printing function.

   If the text is to be read back into Lisp, then you should print with
quoting characters to avoid ambiguity.  Likewise, if the purpose is to
describe a Lisp object clearly for a Lisp programmer.  However, if the
purpose of the output is to look nice for humans, then it is usually
better to print without quoting.

   Lisp objects can refer to themselves.  Printing a self-referential
object in the normal way would require an infinite amount of text, and
the attempt could cause infinite recursion.  Emacs detects such
recursion and prints `#LEVEL' instead of recursively printing an object
already being printed.  For example, here `#0' indicates a recursive
reference to the object at level 0 of the current print operation:

     (setq foo (list nil))
          => (nil)
     (setcar foo foo)
          => (#0)

   In the functions below, STREAM stands for an output stream.  (See
the previous section for a description of output streams.)  If STREAM
is `nil' or omitted, it defaults to the value of `standard-output'.

 -- Function: print object &optional stream
     The `print' function is a convenient way of printing.  It outputs
     the printed representation of OBJECT to STREAM, printing in
     addition one newline before OBJECT and another after it.  Quoting
     characters are used.  `print' returns OBJECT.  For example:

          (progn (print 'The\ cat\ in)
                 (print "the hat")
                 (print " came back"))
               -|
               -| The\ cat\ in
               -|
               -| "the hat"
               -|
               -| " came back"
               => " came back"

 -- Function: prin1 object &optional stream
     This function outputs the printed representation of OBJECT to
     STREAM.  It does not print newlines to separate output as `print'
     does, but it does use quoting characters just like `print'.  It
     returns OBJECT.

          (progn (prin1 'The\ cat\ in)
                 (prin1 "the hat")
                 (prin1 " came back"))
               -| The\ cat\ in"the hat"" came back"
               => " came back"

 -- Function: princ object &optional stream
     This function outputs the printed representation of OBJECT to
     STREAM.  It returns OBJECT.

     This function is intended to produce output that is readable by
     people, not by `read', so it doesn't insert quoting characters and
     doesn't put double-quotes around the contents of strings.  It does
     not add any spacing between calls.

          (progn
            (princ 'The\ cat)
            (princ " in the \"hat\""))
               -| The cat in the "hat"
               => " in the \"hat\""

 -- Function: terpri &optional stream
     This function outputs a newline to STREAM.  The name stands for
     "terminate print."

 -- Function: write-char character &optional stream
     This function outputs CHARACTER to STREAM.  It returns CHARACTER.

 -- Function: prin1-to-string object &optional noescape
     This function returns a string containing the text that `prin1'
     would have printed for the same argument.

          (prin1-to-string 'foo)
               => "foo"
          (prin1-to-string (mark-marker))
               => "#<marker at 2773 in strings.texi>"

     If NOESCAPE is non-`nil', that inhibits use of quoting characters
     in the output.  (This argument is supported in Emacs versions 19
     and later.)

          (prin1-to-string "foo")
               => "\"foo\""
          (prin1-to-string "foo" t)
               => "foo"

     See `format', in *note Formatting Strings::, for other ways to
     obtain the printed representation of a Lisp object as a string.

 -- Macro: with-output-to-string body...
     This macro executes the BODY forms with `standard-output' set up
     to feed output into a string.  Then it returns that string.

     For example, if the current buffer name is `foo',

          (with-output-to-string
            (princ "The buffer is ")
            (princ (buffer-name)))

     returns `"The buffer is foo"'.

File: elisp,  Node: Output Variables,  Prev: Output Functions,  Up: Read and Print

19.6 Variables Affecting Output
===============================

 -- Variable: standard-output
     The value of this variable is the default output stream--the stream
     that print functions use when the STREAM argument is `nil'.  The
     default is `t', meaning display in the echo area.

 -- Variable: print-quoted
     If this is non-`nil', that means to print quoted forms using
     abbreviated reader syntax.  `(quote foo)' prints as `'foo',
     `(function foo)' as `#'foo', and backquoted forms print using
     modern backquote syntax.

 -- Variable: print-escape-newlines
     If this variable is non-`nil', then newline characters in strings
     are printed as `\n' and formfeeds are printed as `\f'.  Normally
     these characters are printed as actual newlines and formfeeds.

     This variable affects the print functions `prin1' and `print' that
     print with quoting.  It does not affect `princ'.  Here is an
     example using `prin1':

          (prin1 "a\nb")
               -| "a
               -| b"
               => "a
          b"

          (let ((print-escape-newlines t))
            (prin1 "a\nb"))
               -| "a\nb"
               => "a
          b"

     In the second expression, the local binding of
     `print-escape-newlines' is in effect during the call to `prin1',
     but not during the printing of the result.

 -- Variable: print-escape-nonascii
     If this variable is non-`nil', then unibyte non-ASCII characters
     in strings are unconditionally printed as backslash sequences by
     the print functions `prin1' and `print' that print with quoting.

     Those functions also use backslash sequences for unibyte non-ASCII
     characters, regardless of the value of this variable, when the
     output stream is a multibyte buffer or a marker pointing into one.

 -- Variable: print-escape-multibyte
     If this variable is non-`nil', then multibyte non-ASCII characters
     in strings are unconditionally printed as backslash sequences by
     the print functions `prin1' and `print' that print with quoting.

     Those functions also use backslash sequences for multibyte
     non-ASCII characters, regardless of the value of this variable,
     when the output stream is a unibyte buffer or a marker pointing
     into one.

 -- Variable: print-length
     The value of this variable is the maximum number of elements to
     print in any list, vector or bool-vector.  If an object being
     printed has more than this many elements, it is abbreviated with
     an ellipsis.

     If the value is `nil' (the default), then there is no limit.

          (setq print-length 2)
               => 2
          (print '(1 2 3 4 5))
               -| (1 2 ...)
               => (1 2 ...)

 -- Variable: print-level
     The value of this variable is the maximum depth of nesting of
     parentheses and brackets when printed.  Any list or vector at a
     depth exceeding this limit is abbreviated with an ellipsis.  A
     value of `nil' (which is the default) means no limit.

 -- User Option: eval-expression-print-length
 -- User Option: eval-expression-print-level
     These are the values for `print-length' and `print-level' used by
     `eval-expression', and thus, indirectly, by many interactive
     evaluation commands (*note Evaluating Emacs-Lisp Expressions:
     (emacs)Lisp Eval.).

   These variables are used for detecting and reporting circular and
shared structure:

 -- Variable: print-circle
     If non-`nil', this variable enables detection of circular and
     shared structure in printing.  *Note Circular Objects::.

 -- Variable: print-gensym
     If non-`nil', this variable enables detection of uninterned symbols
     (*note Creating Symbols::) in printing.  When this is enabled,
     uninterned symbols print with the prefix `#:', which tells the Lisp
     reader to produce an uninterned symbol.

 -- Variable: print-continuous-numbering
     If non-`nil', that means number continuously across print calls.
     This affects the numbers printed for `#N=' labels and `#M#'
     references.

     Don't set this variable with `setq'; you should only bind it
     temporarily to `t' with `let'.  When you do that, you should also
     bind `print-number-table' to `nil'.

 -- Variable: print-number-table
     This variable holds a vector used internally by printing to
     implement the `print-circle' feature.  You should not use it except
     to bind it to `nil' when you bind `print-continuous-numbering'.

 -- Variable: float-output-format
     This variable specifies how to print floating point numbers.  Its
     default value is `nil', meaning use the shortest output that
     represents the number without losing information.

     To control output format more precisely, you can put a string in
     this variable.  The string should hold a `%'-specification to be
     used in the C function `sprintf'.  For further restrictions on what
     you can use, see the variable's documentation string.

File: elisp,  Node: Minibuffers,  Next: Command Loop,  Prev: Read and Print,  Up: Top

20 Minibuffers
**************

A "minibuffer" is a special buffer that Emacs commands use to read
arguments more complicated than the single numeric prefix argument.
These arguments include file names, buffer names, and command names (as
in `M-x').  The minibuffer is displayed on the bottom line of the
frame, in the same place as the echo area (*note The Echo Area::), but
only while it is in use for reading an argument.

* Menu:

* 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.
* Minibuffer History::	      Recording previous minibuffer inputs
				so the user can reuse them.
* Initial Input::             Specifying initial contents for the minibuffer.
* Completion::                How to invoke and customize completion.
* Yes-or-No Queries::         Asking a question with a simple answer.
* Multiple Queries::	      Asking a series of similar questions.
* Reading a Password::	      Reading a password from the terminal.
* Minibuffer Commands::       Commands used as key bindings in minibuffers.
* Minibuffer Contents::       How such commands access the minibuffer text.
* Minibuffer Windows::        Operating on the special minibuffer windows.
* Recursive Mini::            Whether recursive entry to minibuffer is allowed.
* Minibuffer Misc::           Various customization hooks and variables.

File: elisp,  Node: Intro to Minibuffers,  Next: Text from Minibuffer,  Up: Minibuffers

20.1 Introduction to Minibuffers
================================

In most ways, a minibuffer is a normal Emacs buffer.  Most operations
_within_ a buffer, such as editing commands, work normally in a
minibuffer.  However, many operations for managing buffers do not apply
to minibuffers.  The name of a minibuffer always has the form
` *Minibuf-NUMBER*', and it cannot be changed.  Minibuffers are
displayed only in special windows used only for minibuffers; these
windows always appear at the bottom of a frame.  (Sometimes frames have
no minibuffer window, and sometimes a special kind of frame contains
nothing but a minibuffer window; see *note Minibuffers and Frames::.)

   The text in the minibuffer always starts with the "prompt string",
the text that was specified by the program that is using the minibuffer
to tell the user what sort of input to type.  This text is marked
read-only so you won't accidentally delete or change it.  It is also
marked as a field (*note Fields::), so that certain motion functions,
including `beginning-of-line', `forward-word', `forward-sentence', and
`forward-paragraph', stop at the boundary between the prompt and the
actual text.

   The minibuffer's window is normally a single line; it grows
automatically if the contents require more space.  You can explicitly
resize it temporarily with the window sizing commands; it reverts to
its normal size when the minibuffer is exited.  You can resize it
permanently by using the window sizing commands in the frame's other
window, when the minibuffer is not active.  If the frame contains just
a minibuffer, you can change the minibuffer's size by changing the
frame's size.

   Use of the minibuffer reads input events, and that alters the values
of variables such as `this-command' and `last-command' (*note Command
Loop Info::).  Your program should bind them around the code that uses
the minibuffer, if you do not want that to change them.

   Under some circumstances, a command can use a minibuffer even if
there is an active minibuffer; such minibuffers are called a "recursive
minibuffer".  The first minibuffer is named ` *Minibuf-0*'.  Recursive
minibuffers are named by incrementing the number at the end of the
name.  (The names begin with a space so that they won't show up in
normal buffer lists.)  Of several recursive minibuffers, the innermost
(or most recently entered) is the active minibuffer.  We usually call
this "the" minibuffer.  You can permit or forbid recursive minibuffers
by setting the variable `enable-recursive-minibuffers', or by putting
properties of that name on command symbols (*Note Recursive Mini::.)

   Like other buffers, a minibuffer uses a local keymap (*note
Keymaps::) to specify special key bindings.  The function that invokes
the minibuffer also sets up its local map according to the job to be
done.  *Note Text from Minibuffer::, for the non-completion minibuffer
local maps.  *Note Completion Commands::, for the minibuffer local maps
for completion.

   When Emacs is running in batch mode, any request to read from the
minibuffer actually reads a line from the standard input descriptor that
was supplied when Emacs was started.

File: elisp,  Node: Text from Minibuffer,  Next: Object from Minibuffer,  Prev: Intro to Minibuffers,  Up: Minibuffers

20.2 Reading Text Strings with the Minibuffer
=============================================

The most basic primitive for minibuffer input is
`read-from-minibuffer', which can be used to read either a string or a
Lisp object in textual form.  The function `read-regexp' is used for
reading regular expressions (*note Regular Expressions::), which are a
special kind of string.  There are also specialized functions for
reading commands, variables, file names, etc.  (*note Completion::).

   In most cases, you should not call minibuffer input functions in the
middle of a Lisp function.  Instead, do all minibuffer input as part of
reading the arguments for a command, in the `interactive'
specification.  *Note Defining Commands::.

 -- Function: read-from-minibuffer prompt-string &optional
          initial-contents keymap read hist default inherit-input-method
     This function is the most general way to get input from the
     minibuffer.  By default, it accepts arbitrary text and returns it
     as a string; however, if READ is non-`nil', then it uses `read' to
     convert the text into a Lisp object (*note Input Functions::).

     The first thing this function does is to activate a minibuffer and
     display it with PROMPT-STRING as the prompt.  This value must be a
     string.  Then the user can edit text in the minibuffer.

     When the user types a command to exit the minibuffer,
     `read-from-minibuffer' constructs the return value from the text in
     the minibuffer.  Normally it returns a string containing that text.
     However, if READ is non-`nil', `read-from-minibuffer' reads the
     text and returns the resulting Lisp object, unevaluated.  (*Note
     Input Functions::, for information about reading.)

     The argument DEFAULT specifies default values to make available
     through the history commands.  It should be a string, a list of
     strings, or `nil'.  The string or strings become the minibuffer's
     "future history," available to the user with `M-n'.

     If READ is non-`nil', then DEFAULT is also used as the input to
     `read', if the user enters empty input.  If DEFAULT is a list of
     strings, the first string is used as the input.  If DEFAULT is
     `nil', empty input results in an `end-of-file' error.  However, in
     the usual case (where READ is `nil'), `read-from-minibuffer'
     ignores DEFAULT when the user enters empty input and returns an
     empty string, `""'.  In this respect, it differs from all the
     other minibuffer input functions in this chapter.

     If KEYMAP is non-`nil', that keymap is the local keymap to use in
     the minibuffer.  If KEYMAP is omitted or `nil', the value of
     `minibuffer-local-map' is used as the keymap.  Specifying a keymap
     is the most important way to customize the minibuffer for various
     applications such as completion.

     The argument HIST specifies which history list variable to use for
     saving the input and for history commands used in the minibuffer.
     It defaults to `minibuffer-history'.  *Note Minibuffer History::.

     If the variable `minibuffer-allow-text-properties' is non-`nil',
     then the string which is returned includes whatever text
     properties were present in the minibuffer.  Otherwise all the text
     properties are stripped when the value is returned.

     If the argument INHERIT-INPUT-METHOD is non-`nil', then the
     minibuffer inherits the current input method (*note Input
     Methods::) and the setting of `enable-multibyte-characters' (*note
     Text Representations::) from whichever buffer was current before
     entering the minibuffer.

     Use of INITIAL-CONTENTS is mostly deprecated; we recommend using a
     non-`nil' value only in conjunction with specifying a cons cell
     for HIST.  *Note Initial Input::.

 -- Function: read-string prompt &optional initial history default
          inherit-input-method
     This function reads a string from the minibuffer and returns it.
     The arguments PROMPT, INITIAL, HISTORY and INHERIT-INPUT-METHOD
     are used as in `read-from-minibuffer'.  The keymap used is
     `minibuffer-local-map'.

     The optional argument DEFAULT is used as in
     `read-from-minibuffer', except that, if non-`nil', it also
     specifies a default value to return if the user enters null input.
     As in `read-from-minibuffer' it should be a string, a list of
     strings, or `nil' which is equivalent to an empty string.  When
     DEFAULT is a string, that string is the default value.  When it is
     a list of strings, the first string is the default value.  (All
     these strings are available to the user in the "future minibuffer
     history.")

     This function works by calling the `read-from-minibuffer' function:

          (read-string PROMPT INITIAL HISTORY DEFAULT INHERIT)
          ==
          (let ((value
                 (read-from-minibuffer PROMPT INITIAL nil nil
                                       HISTORY DEFAULT INHERIT)))
            (if (and (equal value "") DEFAULT)
                (if (consp DEFAULT) (car DEFAULT) DEFAULT)
              value))

 -- Function: read-regexp prompt &optional default-value
     This function reads a regular expression as a string from the
     minibuffer and returns it.  The argument PROMPT is used as in
     `read-from-minibuffer'.  The keymap used is
     `minibuffer-local-map', and `regexp-history' is used as the
     history list (*note regexp-history: Minibuffer History.).

     The optional argument DEFAULT-VALUE specifies a default value to
     return if the user enters null input; it should be a string, or
     `nil' which is equivalent to an empty string.

     In addition, `read-regexp' collects a few useful candidates for
     input and passes them to `read-from-minibuffer', to make them
     available to the user as the "future minibuffer history list"
     (*note future list: (emacs)Minibuffer History.).  These candidates
     are:

        - The word or symbol at point.

        - The last regexp used in an incremental search.

        - The last string used in an incremental search.

        - The last string or pattern used in query-replace commands.

     This function works by calling the `read-from-minibuffer'
     function, after computing the list of defaults as described above.

 -- Variable: minibuffer-allow-text-properties
     If this variable is `nil', then `read-from-minibuffer' strips all
     text properties from the minibuffer input before returning it.
     This variable also affects `read-string'.  However,
     `read-no-blanks-input' (see below), as well as `read-minibuffer'
     and related functions (*note Reading Lisp Objects With the
     Minibuffer: Object from Minibuffer.), and all functions that do
     minibuffer input with completion, discard text properties
     unconditionally, regardless of the value of this variable.

 -- Variable: minibuffer-local-map
     This is the default local keymap for reading from the minibuffer.
     By default, it makes the following bindings:

    `C-j'
          `exit-minibuffer'

    <RET>
          `exit-minibuffer'

    `C-g'
          `abort-recursive-edit'

    `M-n'
    <DOWN>
          `next-history-element'

    `M-p'
    <UP>
          `previous-history-element'

    `M-s'
          `next-matching-history-element'

    `M-r'
          `previous-matching-history-element'

 -- Function: read-no-blanks-input prompt &optional initial
          inherit-input-method
     This function reads a string from the minibuffer, but does not
     allow whitespace characters as part of the input: instead, those
     characters terminate the input.  The arguments PROMPT, INITIAL, and
     INHERIT-INPUT-METHOD are used as in `read-from-minibuffer'.

     This is a simplified interface to the `read-from-minibuffer'
     function, and passes the value of the `minibuffer-local-ns-map'
     keymap as the KEYMAP argument for that function.  Since the keymap
     `minibuffer-local-ns-map' does not rebind `C-q', it _is_ possible
     to put a space into the string, by quoting it.

     This function discards text properties, regardless of the value of
     `minibuffer-allow-text-properties'.

          (read-no-blanks-input PROMPT INITIAL)
          ==
          (let (minibuffer-allow-text-properties)
            (read-from-minibuffer PROMPT INITIAL minibuffer-local-ns-map))

 -- Variable: minibuffer-local-ns-map
     This built-in variable is the keymap used as the minibuffer local
     keymap in the function `read-no-blanks-input'.  By default, it
     makes the following bindings, in addition to those of
     `minibuffer-local-map':

    <SPC>
          `exit-minibuffer'

    <TAB>
          `exit-minibuffer'

    `?'
          `self-insert-and-exit'

File: elisp,  Node: Object from Minibuffer,  Next: Minibuffer History,  Prev: Text from Minibuffer,  Up: Minibuffers

20.3 Reading Lisp Objects with the Minibuffer
=============================================

This section describes functions for reading Lisp objects with the
minibuffer.

 -- Function: read-minibuffer prompt &optional initial
     This function reads a Lisp object using the minibuffer, and
     returns it without evaluating it.  The arguments PROMPT and
     INITIAL are used as in `read-from-minibuffer'.

     This is a simplified interface to the `read-from-minibuffer'
     function:

          (read-minibuffer PROMPT INITIAL)
          ==
          (let (minibuffer-allow-text-properties)
            (read-from-minibuffer PROMPT INITIAL nil t))

     Here is an example in which we supply the string `"(testing)"' as
     initial input:

          (read-minibuffer
           "Enter an expression: " (format "%s" '(testing)))

          ;; Here is how the minibuffer is displayed:

          ---------- Buffer: Minibuffer ----------
          Enter an expression: (testing)-!-
          ---------- Buffer: Minibuffer ----------

     The user can type <RET> immediately to use the initial input as a
     default, or can edit the input.

 -- Function: eval-minibuffer prompt &optional initial
     This function reads a Lisp expression using the minibuffer,
     evaluates it, then returns the result.  The arguments PROMPT and
     INITIAL are used as in `read-from-minibuffer'.

     This function simply evaluates the result of a call to
     `read-minibuffer':

          (eval-minibuffer PROMPT INITIAL)
          ==
          (eval (read-minibuffer PROMPT INITIAL))

 -- Function: edit-and-eval-command prompt form
     This function reads a Lisp expression in the minibuffer, and then
     evaluates it.  The difference between this command and
     `eval-minibuffer' is that here the initial FORM is not optional
     and it is treated as a Lisp object to be converted to printed
     representation rather than as a string of text.  It is printed with
     `prin1', so if it is a string, double-quote characters (`"')
     appear in the initial text.  *Note Output Functions::.

     The first thing `edit-and-eval-command' does is to activate the
     minibuffer with PROMPT as the prompt.  Then it inserts the printed
     representation of FORM in the minibuffer, and lets the user edit
     it.  When the user exits the minibuffer, the edited text is read
     with `read' and then evaluated.  The resulting value becomes the
     value of `edit-and-eval-command'.

     In the following example, we offer the user an expression with
     initial text which is a valid form already:

          (edit-and-eval-command "Please edit: " '(forward-word 1))

          ;; After evaluation of the preceding expression,
          ;;   the following appears in the minibuffer:

          ---------- Buffer: Minibuffer ----------
          Please edit: (forward-word 1)-!-
          ---------- Buffer: Minibuffer ----------

     Typing <RET> right away would exit the minibuffer and evaluate the
     expression, thus moving point forward one word.
     `edit-and-eval-command' returns `nil' in this example.

File: elisp,  Node: Minibuffer History,  Next: Initial Input,  Prev: Object from Minibuffer,  Up: Minibuffers

20.4 Minibuffer History
=======================

A "minibuffer history list" records previous minibuffer inputs so the
user can reuse them conveniently.  A history list is actually a symbol,
not a list; it is a variable whose value is a list of strings (previous
inputs), most recent first.

   There are many separate history lists, used for different kinds of
inputs.  It's the Lisp programmer's job to specify the right history
list for each use of the minibuffer.

   You specify the history list with the optional HIST argument to
either `read-from-minibuffer' or `completing-read'.  Here are the
possible values for it:

VARIABLE
     Use VARIABLE (a symbol) as the history list.

(VARIABLE . STARTPOS)
     Use VARIABLE (a symbol) as the history list, and assume that the
     initial history position is STARTPOS (a nonnegative integer).

     Specifying 0 for STARTPOS is equivalent to just specifying the
     symbol VARIABLE.  `previous-history-element' will display the most
     recent element of the history list in the minibuffer.  If you
     specify a positive STARTPOS, the minibuffer history functions
     behave as if `(elt VARIABLE (1- STARTPOS))' were the history
     element currently shown in the minibuffer.

     For consistency, you should also specify that element of the
     history as the initial minibuffer contents, using the INITIAL
     argument to the minibuffer input function (*note Initial Input::).

   If you don't specify HIST, then the default history list
`minibuffer-history' is used.  For other standard history lists, see
below.  You can also create your own history list variable; just
initialize it to `nil' before the first use.

   Both `read-from-minibuffer' and `completing-read' add new elements
to the history list automatically, and provide commands to allow the
user to reuse items on the list.  The only thing your program needs to
do to use a history list is to initialize it and to pass its name to
the input functions when you wish.  But it is safe to modify the list
by hand when the minibuffer input functions are not using it.

   Emacs functions that add a new element to a history list can also
delete old elements if the list gets too long.  The variable
`history-length' specifies the maximum length for most history lists.
To specify a different maximum length for a particular history list,
put the length in the `history-length' property of the history list
symbol.  The variable `history-delete-duplicates' specifies whether to
delete duplicates in history.

 -- Function: add-to-history history-var newelt &optional maxelt
          keep-all
     This function adds a new element NEWELT, if it isn't the empty
     string, to the history list stored in the variable HISTORY-VAR,
     and returns the updated history list.  It limits the list length to
     the value of MAXELT (if non-`nil') or `history-length' (described
     below).  The possible values of MAXELT have the same meaning as
     the values of `history-length'.

     Normally, `add-to-history' removes duplicate members from the
     history list if `history-delete-duplicates' is non-`nil'.
     However, if KEEP-ALL is non-`nil', that says not to remove
     duplicates, and to add NEWELT to the list even if it is empty.

 -- Variable: history-add-new-input
     If the value of this variable is `nil', standard functions that
     read from the minibuffer don't add new elements to the history
     list.  This lets Lisp programs explicitly manage input history by
     using `add-to-history'.  By default, `history-add-new-input' is
     set to a non-`nil' value.

 -- User Option: history-length
     The value of this variable specifies the maximum length for all
     history lists that don't specify their own maximum lengths.  If the
     value is `t', that means there no maximum (don't delete old
     elements).  The value of `history-length' property of the history
     list variable's symbol, if set, overrides this variable for that
     particular history list.

 -- User Option: history-delete-duplicates
     If the value of this variable is `t', that means when adding a new
     history element, all previous identical elements are deleted.

   Here are some of the standard minibuffer history list variables:

 -- Variable: minibuffer-history
     The default history list for minibuffer history input.

 -- Variable: query-replace-history
     A history list for arguments to `query-replace' (and similar
     arguments to other commands).

 -- Variable: file-name-history
     A history list for file-name arguments.

 -- Variable: buffer-name-history
     A history list for buffer-name arguments.

 -- Variable: regexp-history
     A history list for regular expression arguments.

 -- Variable: extended-command-history
     A history list for arguments that are names of extended commands.

 -- Variable: shell-command-history
     A history list for arguments that are shell commands.

 -- Variable: read-expression-history
     A history list for arguments that are Lisp expressions to evaluate.

File: elisp,  Node: Initial Input,  Next: Completion,  Prev: Minibuffer History,  Up: Minibuffers

20.5 Initial Input
==================

Several of the functions for minibuffer input have an argument called
INITIAL or INITIAL-CONTENTS.  This is a mostly-deprecated feature for
specifying that the minibuffer should start out with certain text,
instead of empty as usual.

   If INITIAL is a string, the minibuffer starts out containing the
text of the string, with point at the end, when the user starts to edit
the text.  If the user simply types <RET> to exit the minibuffer, it
will use the initial input string to determine the value to return.

   *We discourage use of a non-`nil' value for INITIAL*, because
initial input is an intrusive interface.  History lists and default
values provide a much more convenient method to offer useful default
inputs to the user.

   There is just one situation where you should specify a string for an
INITIAL argument.  This is when you specify a cons cell for the HIST or
HISTORY argument.  *Note Minibuffer History::.

   INITIAL can also be a cons cell of the form `(STRING . POSITION)'.
This means to insert STRING in the minibuffer but put point at POSITION
within the string's text.

   As a historical accident, POSITION was implemented inconsistently in
different functions.  In `completing-read', POSITION's value is
interpreted as origin-zero; that is, a value of 0 means the beginning
of the string, 1 means after the first character, etc.  In
`read-minibuffer', and the other non-completion minibuffer input
functions that support this argument, 1 means the beginning of the
string 2 means after the first character, etc.

   Use of a cons cell as the value for INITIAL arguments is deprecated
in user code.

File: elisp,  Node: Completion,  Next: Yes-or-No Queries,  Prev: Initial Input,  Up: Minibuffers

20.6 Completion
===============

"Completion" is a feature that fills in the rest of a name starting
from an abbreviation for it.  Completion works by comparing the user's
input against a list of valid names and determining how much of the
name is determined uniquely by what the user has typed.  For example,
when you type `C-x b' (`switch-to-buffer') and then type the first few
letters of the name of the buffer to which you wish to switch, and then
type <TAB> (`minibuffer-complete'), Emacs extends the name as far as it
can.

   Standard Emacs commands offer completion for names of symbols, files,
buffers, and processes; with the functions in this section, you can
implement completion for other kinds of names.

   The `try-completion' function is the basic primitive for completion:
it returns the longest determined completion of a given initial string,
with a given set of strings to match against.

   The function `completing-read' provides a higher-level interface for
completion.  A call to `completing-read' specifies how to determine the
list of valid names.  The function then activates the minibuffer with a
local keymap that binds a few keys to commands useful for completion.
Other functions provide convenient simple interfaces for reading
certain kinds of names with completion.

* Menu:

* 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 and
                             shell commands.
* Completion Styles::      Specifying rules for performing completion.
* Programmed Completion::  Writing your own completion-function.

File: elisp,  Node: Basic Completion,  Next: Minibuffer Completion,  Up: Completion

20.6.1 Basic Completion Functions
---------------------------------

The completion functions `try-completion', `all-completions' and
`test-completion' have nothing in themselves to do with minibuffers.
We describe them in this chapter so as to keep them near the
higher-level completion features that do use the minibuffer.

   If you store a completion alist in a variable, you should mark the
variable as "risky" with a non-`nil' `risky-local-variable' property.

 -- Function: try-completion string collection &optional predicate
     This function returns the longest common substring of all possible
     completions of STRING in COLLECTION.  The value of COLLECTION must
     be a list of strings or symbols, an alist, an obarray, a hash
     table, or a function that implements a virtual set of strings (see
     below).

     Completion compares STRING against each of the permissible
     completions specified by COLLECTION; if the beginning of the
     permissible completion equals STRING, it matches.  If no
     permissible completions match, `try-completion' returns `nil'.  If
     only one permissible completion matches, and the match is exact,
     then `try-completion' returns `t'.  Otherwise, the value is the
     longest initial sequence common to all the permissible completions
     that match.

     If COLLECTION is an alist (*note Association Lists::), the
     permissible completions are the elements of the alist that are
     either strings, symbols, or conses whose CAR is a string or symbol.
     Symbols are converted to strings using `symbol-name'.  Other
     elements of the alist are ignored. (Remember that in Emacs Lisp,
     the elements of alists do not _have_ to be conses.)  In
     particular, a list of strings or symbols is allowed, even though
     we usually do not think of such lists as alists.

     If COLLECTION is an obarray (*note Creating Symbols::), the names
     of all symbols in the obarray form the set of permissible
     completions.  The global variable `obarray' holds an obarray
     containing the names of all interned Lisp symbols.

     Note that the only valid way to make a new obarray is to create it
     empty and then add symbols to it one by one using `intern'.  Also,
     you cannot intern a given symbol in more than one obarray.

     If COLLECTION is a hash table, then the keys that are strings are
     the possible completions.  Other keys are ignored.

     You can also use a symbol that is a function as COLLECTION.  Then
     the function is solely responsible for performing completion;
     `try-completion' returns whatever this function returns.  The
     function is called with three arguments: STRING, PREDICATE and
     `nil'.  (The reason for the third argument is so that the same
     function can be used in `all-completions' and do the appropriate
     thing in either case.)  *Note Programmed Completion::.

     If the argument PREDICATE is non-`nil', then it must be a function
     of one argument, unless COLLECTION is a hash table, in which case
     it should be a function of two arguments.  It is used to test each
     possible match, and the match is accepted only if PREDICATE
     returns non-`nil'.  The argument given to PREDICATE is either a
     string or a cons cell (the CAR of which is a string) from the
     alist, or a symbol (_not_ a symbol name) from the obarray.  If
     COLLECTION is a hash table, PREDICATE is called with two
     arguments, the string key and the associated value.

     In addition, to be acceptable, a completion must also match all the
     regular expressions in `completion-regexp-list'.  (Unless
     COLLECTION is a function, in which case that function has to
     handle `completion-regexp-list' itself.)

     In the first of the following examples, the string `foo' is
     matched by three of the alist CARs.  All of the matches begin with
     the characters `fooba', so that is the result.  In the second
     example, there is only one possible match, and it is exact, so the
     value is `t'.

          (try-completion
           "foo"
           '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)))
               => "fooba"

          (try-completion "foo" '(("barfoo" 2) ("foo" 3)))
               => t

     In the following example, numerous symbols begin with the
     characters `forw', and all of them begin with the word `forward'.
     In most of the symbols, this is followed with a `-', but not in
     all, so no more than `forward' can be completed.

          (try-completion "forw" obarray)
               => "forward"

     Finally, in the following example, only two of the three possible
     matches pass the predicate `test' (the string `foobaz' is too
     short).  Both of those begin with the string `foobar'.

          (defun test (s)
            (> (length (car s)) 6))
               => test
          (try-completion
           "foo"
           '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
           'test)
               => "foobar"

 -- Function: all-completions string collection &optional predicate
          nospace
     This function returns a list of all possible completions of
     STRING.  The arguments to this function (aside from NOSPACE) are
     the same as those of `try-completion'.  Also, this function uses
     `completion-regexp-list' in the same way that `try-completion'
     does.  The optional argument NOSPACE only matters if STRING is the
     empty string.  In that case, if NOSPACE is non-`nil', completions
     that start with a space are ignored.

     If COLLECTION is a function, it is called with three arguments:
     STRING, PREDICATE and `t'; then `all-completions' returns whatever
     the function returns.  *Note Programmed Completion::.

     Here is an example, using the function `test' shown in the example
     for `try-completion':

          (defun test (s)
            (> (length (car s)) 6))
               => test

          (all-completions
           "foo"
           '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
           'test)
               => ("foobar1" "foobar2")

 -- Function: test-completion string collection &optional predicate
     This function returns non-`nil' if STRING is a valid completion
     possibility specified by COLLECTION and PREDICATE.  The arguments
     are the same as in `try-completion'.  For instance, if COLLECTION
     is a list of strings, this is true if STRING appears in the list
     and PREDICATE is satisfied.

     This function uses `completion-regexp-list' in the same way that
     `try-completion' does.

     If PREDICATE is non-`nil' and if COLLECTION contains several
     strings that are equal to each other, as determined by
     `compare-strings' according to `completion-ignore-case', then
     PREDICATE should accept either all or none of them.  Otherwise,
     the return value of `test-completion' is essentially unpredictable.

     If COLLECTION is a function, it is called with three arguments,
     the values STRING, PREDICATE and `lambda'; whatever it returns,
     `test-completion' returns in turn.

 -- Variable: completion-ignore-case
     If the value of this variable is non-`nil', Emacs does not
     consider case significant in completion.  Note, however, that this
     variable is overridden by `read-file-name-completion-ignore-case'
     within `read-file-name' (*note Reading File Names::), and by
     `read-buffer-completion-ignore-case' within `read-buffer' (*note
     High-Level Completion::).

 -- Variable: completion-regexp-list
     This is a list of regular expressions.  The completion functions
     only consider a completion acceptable if it matches all regular
     expressions in this list, with `case-fold-search' (*note Searching
     and Case::) bound to the value of `completion-ignore-case'.

 -- Macro: lazy-completion-table var fun
     This macro provides a way to initialize the variable VAR as a
     collection for completion in a lazy way, not computing its actual
     contents until they are first needed.  You use this macro to
     produce a value that you store in VAR.  The actual computation of
     the proper value is done the first time you do completion using
     VAR.  It is done by calling FUN with no arguments.  The value FUN
     returns becomes the permanent value of VAR.

     Here is an example of use:

          (defvar foo (lazy-completion-table foo make-my-alist))

File: elisp,  Node: Minibuffer Completion,  Next: Completion Commands,  Prev: Basic Completion,  Up: Completion

20.6.2 Completion and the Minibuffer
------------------------------------

This section describes the basic interface for reading from the
minibuffer with completion.

 -- Function: completing-read prompt collection &optional predicate
          require-match initial hist default inherit-input-method
     This function reads a string in the minibuffer, assisting the user
     by providing completion.  It activates the minibuffer with prompt
     PROMPT, which must be a string.

     The actual completion is done by passing COLLECTION and PREDICATE
     to the function `try-completion'.  This happens in certain
     commands bound in the local keymaps used for completion.  Some of
     these commands also call `test-completion'.  Thus, if PREDICATE is
     non-`nil', it should be compatible with COLLECTION and
     `completion-ignore-case'.  *Note Definition of test-completion::.

     The value of the optional argument REQUIRE-MATCH determines how
     the user may exit the minibuffer:

        * If `nil', the usual minibuffer exit commands work regardless
          of the input in the minibuffer.

        * If `t', the usual minibuffer exit commands won't exit unless
          the input completes to an element of COLLECTION.

        * If `confirm', the user can exit with any input, but is asked
          for confirmation if the input is not an element of COLLECTION.

        * If `confirm-after-completion', the user can exit with any
          input, but is asked for confirmation if the preceding command
          was a completion command (i.e., one of the commands in
          `minibuffer-confirm-exit-commands') and the resulting input is
          not an element of COLLECTION.  *Note Completion Commands::.

        * Any other value of REQUIRE-MATCH behaves like `t', except
          that the exit commands won't exit if it performs completion.

     However, empty input is always permitted, regardless of the value
     of REQUIRE-MATCH; in that case, `completing-read' returns the
     first element of DEFAULT, if it is a list; `""', if DEFAULT is
     `nil'; or DEFAULT.  The string or strings in DEFAULT are also
     available to the user through the history commands.

     The function `completing-read' uses
     `minibuffer-local-completion-map' as the keymap if REQUIRE-MATCH
     is `nil', and uses `minibuffer-local-must-match-map' if
     REQUIRE-MATCH is non-`nil'.  *Note Completion Commands::.

     The argument HIST specifies which history list variable to use for
     saving the input and for minibuffer history commands.  It defaults
     to `minibuffer-history'.  *Note Minibuffer History::.

     The argument INITIAL is mostly deprecated; we recommend using a
     non-`nil' value only in conjunction with specifying a cons cell
     for HIST.  *Note Initial Input::.  For default input, use DEFAULT
     instead.

     If the argument INHERIT-INPUT-METHOD is non-`nil', then the
     minibuffer inherits the current input method (*note Input
     Methods::) and the setting of `enable-multibyte-characters' (*note
     Text Representations::) from whichever buffer was current before
     entering the minibuffer.

     If the built-in variable `completion-ignore-case' is non-`nil',
     completion ignores case when comparing the input against the
     possible matches.  *Note Basic Completion::.  In this mode of
     operation, PREDICATE must also ignore case, or you will get
     surprising results.

     Here's an example of using `completing-read':

          (completing-read
           "Complete a foo: "
           '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
           nil t "fo")

          ;; After evaluation of the preceding expression,
          ;;   the following appears in the minibuffer:

          ---------- Buffer: Minibuffer ----------
          Complete a foo: fo-!-
          ---------- Buffer: Minibuffer ----------

     If the user then types `<DEL> <DEL> b <RET>', `completing-read'
     returns `barfoo'.

     The `completing-read' function binds variables to pass information
     to the commands that actually do completion.  They are described
     in the following section.

File: elisp,  Node: Completion Commands,  Next: High-Level Completion,  Prev: Minibuffer Completion,  Up: Completion

20.6.3 Minibuffer Commands that Do Completion
---------------------------------------------

This section describes the keymaps, commands and user options used in
the minibuffer to do completion.

 -- Variable: minibuffer-completion-table
     The value of this variable is the collection used for completion in
     the minibuffer.  This is the global variable that contains what
     `completing-read' passes to `try-completion'.  It is used by
     minibuffer completion commands such as `minibuffer-complete-word'.

 -- Variable: minibuffer-completion-predicate
     This variable's value is the predicate that `completing-read'
     passes to `try-completion'.  The variable is also used by the other
     minibuffer completion functions.

 -- Variable: minibuffer-completion-confirm
     This variable determines whether Emacs asks for confirmation before
     exiting the minibuffer; `completing-read' binds this variable, and
     the function `minibuffer-complete-and-exit' checks the value
     before exiting.  If the value is `nil', confirmation is not
     required.  If the value is `confirm', the user may exit with an
     input that is not a valid completion alternative, but Emacs asks
     for confirmation.  If the value is `confirm-after-completion', the
     user may exit with an input that is not a valid completion
     alternative, but Emacs asks for confirmation if the user submitted
     the input right after any of the completion commands in
     `minibuffer-confirm-exit-commands'.

 -- Variable: minibuffer-confirm-exit-commands
     This variable holds a list of commands that cause Emacs to ask for
     confirmation before exiting the minibuffer, if the REQUIRE-MATCH
     argument to `completing-read' is `confirm-after-completion'.  The
     confirmation is requested if the user attempts to exit the
     minibuffer immediately after calling any command in this list.

 -- Command: minibuffer-complete-word
     This function completes the minibuffer contents by at most a single
     word.  Even if the minibuffer contents have only one completion,
     `minibuffer-complete-word' does not add any characters beyond the
     first character that is not a word constituent.  *Note Syntax
     Tables::.

 -- Command: minibuffer-complete
     This function completes the minibuffer contents as far as possible.

 -- Command: minibuffer-complete-and-exit
     This function completes the minibuffer contents, and exits if
     confirmation is not required, i.e., if
     `minibuffer-completion-confirm' is `nil'.  If confirmation _is_
     required, it is given by repeating this command immediately--the
     command is programmed to work without confirmation when run twice
     in succession.

 -- Command: minibuffer-completion-help
     This function creates a list of the possible completions of the
     current minibuffer contents.  It works by calling `all-completions'
     using the value of the variable `minibuffer-completion-table' as
     the COLLECTION argument, and the value of
     `minibuffer-completion-predicate' as the PREDICATE argument.  The
     list of completions is displayed as text in a buffer named
     `*Completions*'.

 -- Function: display-completion-list completions &optional
          common-substring
     This function displays COMPLETIONS to the stream in
     `standard-output', usually a buffer.  (*Note Read and Print::, for
     more information about streams.)  The argument COMPLETIONS is
     normally a list of completions just returned by `all-completions',
     but it does not have to be.  Each element may be a symbol or a
     string, either of which is simply printed.  It can also be a list
     of two strings, which is printed as if the strings were
     concatenated.  The first of the two strings is the actual
     completion, the second string serves as annotation.

     The argument COMMON-SUBSTRING is the prefix that is common to all
     the completions.  With normal Emacs completion, it is usually the
     same as the string that was completed.  `display-completion-list'
     uses this to highlight text in the completion list for better
     visual feedback.  This is not needed in the minibuffer; for
     minibuffer completion, you can pass `nil'.

     This function is called by `minibuffer-completion-help'.  The most
     common way to use it is together with
     `with-output-to-temp-buffer', like this:

          (with-output-to-temp-buffer "*Completions*"
            (display-completion-list
              (all-completions (buffer-string) my-alist)
              (buffer-string)))

 -- User Option: completion-auto-help
     If this variable is non-`nil', the completion commands
     automatically display a list of possible completions whenever
     nothing can be completed because the next character is not
     uniquely determined.

 -- Variable: minibuffer-local-completion-map
     `completing-read' uses this value as the local keymap when an
     exact match of one of the completions is not required.  By
     default, this keymap makes the following bindings:

    `?'
          `minibuffer-completion-help'

    <SPC>
          `minibuffer-complete-word'

    <TAB>
          `minibuffer-complete'

     with other characters bound as in `minibuffer-local-map' (*note
     Definition of minibuffer-local-map::).

 -- Variable: minibuffer-local-must-match-map
     `completing-read' uses this value as the local keymap when an
     exact match of one of the completions is required.  Therefore, no
     keys are bound to `exit-minibuffer', the command that exits the
     minibuffer unconditionally.  By default, this keymap makes the
     following bindings:

    `?'
          `minibuffer-completion-help'

    <SPC>
          `minibuffer-complete-word'

    <TAB>
          `minibuffer-complete'

    `C-j'
          `minibuffer-complete-and-exit'

    <RET>
          `minibuffer-complete-and-exit'

     with other characters bound as in `minibuffer-local-map'.

 -- Variable: minibuffer-local-filename-completion-map
     This is like `minibuffer-local-completion-map' except that it does
     not bind <SPC>.  This keymap is used by the function
     `read-file-name'.

 -- Variable: minibuffer-local-filename-must-match-map
     This is like `minibuffer-local-must-match-map' except that it does
     not bind <SPC>.  This keymap is used by the function
     `read-file-name'.

File: elisp,  Node: High-Level Completion,  Next: Reading File Names,  Prev: Completion Commands,  Up: Completion

20.6.4 High-Level Completion Functions
--------------------------------------

This section describes the higher-level convenient functions for
reading certain sorts of names with completion.

   In most cases, you should not call these functions in the middle of a
Lisp function.  When possible, do all minibuffer input as part of
reading the arguments for a command, in the `interactive'
specification.  *Note Defining Commands::.

 -- Function: read-buffer prompt &optional default require-match
     This function reads the name of a buffer and returns it as a
     string.  The argument DEFAULT is the default name to use, the
     value to return if the user exits with an empty minibuffer.  If
     non-`nil', it should be a string, a list of strings, or a buffer.
     If it is a list, the default value is the first element of this
     list.  It is mentioned in the prompt, but is not inserted in the
     minibuffer as initial input.

     The argument PROMPT should be a string ending with a colon and a
     space.  If DEFAULT is non-`nil', the function inserts it in PROMPT
     before the colon to follow the convention for reading from the
     minibuffer with a default value (*note Programming Tips::).

     The optional argument REQUIRE-MATCH has the same meaning as in
     `completing-read'.  *Note Minibuffer Completion::.

     In the following example, the user enters `minibuffer.t', and then
     types <RET>.  The argument REQUIRE-MATCH is `t', and the only
     buffer name starting with the given input is `minibuffer.texi', so
     that name is the value.

          (read-buffer "Buffer name: " "foo" t)
          ;; After evaluation of the preceding expression,
          ;;   the following prompt appears,
          ;;   with an empty minibuffer:

          ---------- Buffer: Minibuffer ----------
          Buffer name (default foo): -!-
          ---------- Buffer: Minibuffer ----------

          ;; The user types `minibuffer.t <RET>'.
               => "minibuffer.texi"

 -- User Option: read-buffer-function
     This variable specifies how to read buffer names.  For example, if
     you set this variable to `iswitchb-read-buffer', all Emacs commands
     that call `read-buffer' to read a buffer name will actually use the
     `iswitchb' package to read it.

 -- User Option: read-buffer-completion-ignore-case
     If this variable is non-`nil', `read-buffer' ignores case when
     performing completion.

 -- Function: read-command prompt &optional default
     This function reads the name of a command and returns it as a Lisp
     symbol.  The argument PROMPT is used as in `read-from-minibuffer'.
     Recall that a command is anything for which `commandp' returns
     `t', and a command name is a symbol for which `commandp' returns
     `t'.  *Note Interactive Call::.

     The argument DEFAULT specifies what to return if the user enters
     null input.  It can be a symbol, a string or a list of strings.
     If it is a string, `read-command' interns it before returning it.
     If it is a list, `read-command' returns the first element of this
     list.  If DEFAULT is `nil', that means no default has been
     specified; then if the user enters null input, the return value is
     `(intern "")', that is, a symbol whose name is an empty string.

          (read-command "Command name? ")

          ;; After evaluation of the preceding expression,
          ;;   the following prompt appears with an empty minibuffer:

          ---------- Buffer: Minibuffer ----------
          Command name?
          ---------- Buffer: Minibuffer ----------

     If the user types `forward-c <RET>', then this function returns
     `forward-char'.

     The `read-command' function is a simplified interface to
     `completing-read'.  It uses the variable `obarray' so as to
     complete in the set of extant Lisp symbols, and it uses the
     `commandp' predicate so as to accept only command names:

          (read-command PROMPT)
          ==
          (intern (completing-read PROMPT obarray
                                   'commandp t nil))

 -- Function: read-variable prompt &optional default
     This function reads the name of a user variable and returns it as a
     symbol.

     The argument DEFAULT specifies the default value to return if the
     user enters null input.  It can be a symbol, a string, or a list
     of strings.  If it is a string, `read-variable' interns it to make
     the default value.  If it is a list, `read-variable' interns the
     first element.  If DEFAULT is `nil', that means no default has
     been specified; then if the user enters null input, the return
     value is `(intern "")'.

          (read-variable "Variable name? ")

          ;; After evaluation of the preceding expression,
          ;;   the following prompt appears,
          ;;   with an empty minibuffer:

          ---------- Buffer: Minibuffer ----------
          Variable name? -!-
          ---------- Buffer: Minibuffer ----------

     If the user then types `fill-p <RET>', `read-variable' returns
     `fill-prefix'.

     In general, `read-variable' is similar to `read-command', but uses
     the predicate `user-variable-p' instead of `commandp':

          (read-variable PROMPT)
          ==
          (intern
           (completing-read PROMPT obarray
                            'user-variable-p t nil))

 -- Command: read-color &optional prompt convert allow-empty display
     This function reads a string that is a color specification, either
     the color's name or an RGB hex value such as `#RRRGGGBBB'.  It
     prompts with PROMPT (default: `"Color (name or #R+G+B+):"') and
     provides completion for color names, but not for hex RGB values.
     In addition to names of standard colors, completion candidates
     include the foreground and background colors at point.

     Valid RGB values are described in *note Color Names::.

     The function's return value is the color name typed by the user in
     the minibuffer.  However, when called interactively or if the
     optional argument CONVERT is non-`nil', it converts the name into
     the color's RGB value and returns that value as a string.  If an
     invalid color name was specified, this function signals an error,
     except that empty color names are allowed when `allow-empty' is
     non-`nil' and the user enters null input.

     Interactively, or when DISPLAY is non-`nil', the return value is
     also displayed in the echo area.

   See also the functions `read-coding-system' and
`read-non-nil-coding-system', in *note User-Chosen Coding Systems::,
and `read-input-method-name', in *note Input Methods::.

File: elisp,  Node: Reading File Names,  Next: Completion Styles,  Prev: High-Level Completion,  Up: Completion

20.6.5 Reading File Names
-------------------------

The high-level completion functions `read-file-name',
`read-directory-name', and `read-shell-command' are designed to read
file names, directory names, and shell commands respectively.  They
provide special features, including automatic insertion of the default
directory.

 -- Function: read-file-name prompt &optional directory default
          require-match initial predicate
     This function reads a file name in the minibuffer, prompting with
     PROMPT and providing completion.

     The optional argument REQUIRE-MATCH has the same meaning as in
     `completing-read'.  *Note Minibuffer Completion::.

     `read-file-name' uses `minibuffer-local-filename-completion-map'
     as the keymap if REQUIRE-MATCH is `nil', and uses
     `minibuffer-local-filename-must-match-map' if REQUIRE-MATCH is
     non-`nil'.  *Note Completion Commands::.

     The argument DIRECTORY specifies the directory to use for
     completion of relative file names.  It should be an absolute
     directory name.  If `insert-default-directory' is non-`nil',
     DIRECTORY is also inserted in the minibuffer as initial input.  It
     defaults to the current buffer's value of `default-directory'.

     If you specify INITIAL, that is an initial file name to insert in
     the buffer (after DIRECTORY, if that is inserted).  In this case,
     point goes at the beginning of INITIAL.  The default for INITIAL
     is `nil'--don't insert any file name.  To see what INITIAL does,
     try the command `C-x C-v'.  *Please note:* we recommend using
     DEFAULT rather than INITIAL in most cases.

     If DEFAULT is non-`nil', then the function returns DEFAULT if the
     user exits the minibuffer with the same non-empty contents that
     `read-file-name' inserted initially.  The initial minibuffer
     contents are always non-empty if `insert-default-directory' is
     non-`nil', as it is by default.  DEFAULT is not checked for
     validity, regardless of the value of REQUIRE-MATCH.  However, if
     REQUIRE-MATCH is non-`nil', the initial minibuffer contents should
     be a valid file (or directory) name.  Otherwise `read-file-name'
     attempts completion if the user exits without any editing, and
     does not return DEFAULT.  DEFAULT is also available through the
     history commands.

     If DEFAULT is `nil', `read-file-name' tries to find a substitute
     default to use in its place, which it treats in exactly the same
     way as if it had been specified explicitly.  If DEFAULT is `nil',
     but INITIAL is non-`nil', then the default is the absolute file
     name obtained from DIRECTORY and INITIAL.  If both DEFAULT and
     INITIAL are `nil' and the buffer is visiting a file,
     `read-file-name' uses the absolute file name of that file as
     default.  If the buffer is not visiting a file, then there is no
     default.  In that case, if the user types <RET> without any
     editing, `read-file-name' simply returns the pre-inserted contents
     of the minibuffer.

     If the user types <RET> in an empty minibuffer, this function
     returns an empty string, regardless of the value of REQUIRE-MATCH.
     This is, for instance, how the user can make the current buffer
     visit no file using `M-x set-visited-file-name'.

     If PREDICATE is non-`nil', it specifies a function of one argument
     that decides which file names are acceptable completion
     possibilities.  A file name is an acceptable value if PREDICATE
     returns non-`nil' for it.

     `read-file-name' does not automatically expand file names.  You
     must call `expand-file-name' yourself if an absolute file name is
     required.

     Here is an example:

          (read-file-name "The file is ")

          ;; After evaluation of the preceding expression,
          ;;   the following appears in the minibuffer:

          ---------- Buffer: Minibuffer ----------
          The file is /gp/gnu/elisp/-!-
          ---------- Buffer: Minibuffer ----------

     Typing `manual <TAB>' results in the following:

          ---------- Buffer: Minibuffer ----------
          The file is /gp/gnu/elisp/manual.texi-!-
          ---------- Buffer: Minibuffer ----------

     If the user types <RET>, `read-file-name' returns the file name as
     the string `"/gp/gnu/elisp/manual.texi"'.

 -- Variable: read-file-name-function
     If non-`nil', this should be a function that accepts the same
     arguments as `read-file-name'.  When `read-file-name' is called,
     it calls this function with the supplied arguments instead of
     doing its usual work.

 -- User Option: read-file-name-completion-ignore-case
     If this variable is non-`nil', `read-file-name' ignores case when
     performing completion.

 -- Function: read-directory-name prompt &optional directory default
          require-match initial
     This function is like `read-file-name' but allows only directory
     names as completion possibilities.

     If DEFAULT is `nil' and INITIAL is non-`nil',
     `read-directory-name' constructs a substitute default by combining
     DIRECTORY (or the current buffer's default directory if DIRECTORY
     is `nil') and INITIAL.  If both DEFAULT and INITIAL are `nil',
     this function uses DIRECTORY as substitute default, or the current
     buffer's default directory if DIRECTORY is `nil'.

 -- User Option: insert-default-directory
     This variable is used by `read-file-name', and thus, indirectly,
     by most commands reading file names.  (This includes all commands
     that use the code letters `f' or `F' in their interactive form.
     *Note Code Characters for interactive: Interactive Codes.)  Its
     value controls whether `read-file-name' starts by placing the name
     of the default directory in the minibuffer, plus the initial file
     name if any.  If the value of this variable is `nil', then
     `read-file-name' does not place any initial input in the
     minibuffer (unless you specify initial input with the INITIAL
     argument).  In that case, the default directory is still used for
     completion of relative file names, but is not displayed.

     If this variable is `nil' and the initial minibuffer contents are
     empty, the user may have to explicitly fetch the next history
     element to access a default value.  If the variable is non-`nil',
     the initial minibuffer contents are always non-empty and the user
     can always request a default value by immediately typing <RET> in
     an unedited minibuffer.  (See above.)

     For example:

          ;; Here the minibuffer starts out with the default directory.
          (let ((insert-default-directory t))
            (read-file-name "The file is "))

          ---------- Buffer: Minibuffer ----------
          The file is ~lewis/manual/-!-
          ---------- Buffer: Minibuffer ----------

          ;; Here the minibuffer is empty and only the prompt
          ;;   appears on its line.
          (let ((insert-default-directory nil))
            (read-file-name "The file is "))

          ---------- Buffer: Minibuffer ----------
          The file is -!-
          ---------- Buffer: Minibuffer ----------

 -- Function: read-shell-command prompt &optional initial-contents hist
          &rest args
     This function reads a shell command from the minibuffer, prompting
     with PROMPT and providing intelligent completion.  It completes
     the first word of the command using candidates that are appropriate
     for command names, and the rest of the command words as file names.

     This function uses `minibuffer-local-shell-command-map' as the
     keymap for minibuffer input.  The HIST argument specifies the
     history list to use; if is omitted or `nil', it defaults to
     `shell-command-history' (*note shell-command-history: Minibuffer
     History.).  The optional argument INITIAL-CONTENTS specifies the
     initial content of the minibuffer (*note Initial Input::).  The
     rest of ARGS, if present, are used as the DEFAULT and
     INHERIT-INPUT-METHOD arguments in `read-from-minibuffer' (*note
     Text from Minibuffer::).

 -- Variable: minibuffer-local-shell-command-map
     This keymap is used by `read-shell-command' for completing command
     and file names that are part of a shell command.

File: elisp,  Node: Completion Styles,  Next: Programmed Completion,  Prev: Reading File Names,  Up: Completion

20.6.6 Completion Styles
------------------------

A "completion style" is a set of rules for generating completions.  The
user option `completion-styles' stores a list of completion styles,
which are represented by symbols.

 -- User Option: completion-styles
     This is a list of completion style symbols to use for performing
     completion.  Each completion style in this list must be defined in
     `completion-styles-alist'.

 -- Variable: completion-styles-alist
     This variable stores a list of available completion styles.  Each
     element in the list must have the form `(NAME TRY-COMPLETION
     ALL-COMPLETIONS)'.  Here, NAME is the name of the completion style
     (a symbol), which may be used in `completion-styles-alist' to
     refer to this style.

     TRY-COMPLETION is the function that does the completion, and
     ALL-COMPLETIONS is the function that lists the completions.  These
     functions should accept four arguments: STRING, COLLECTION,
     PREDICATE, and POINT.  The STRING, COLLECTION, and PREDICATE
     arguments have the same meanings as in `try-completion' (*note
     Basic Completion::), and the POINT argument is the position of
     point within STRING.  Each function should return a non-`nil'
     value if it performed its job, and `nil' if it did not (e.g., if
     there is no way to complete STRING according to the completion
     style).

     When the user calls a completion command, such as
     `minibuffer-complete' (*note Completion Commands::), Emacs looks
     for the first style listed in `completion-styles' and calls its
     TRY-COMPLETION function.  If this function returns `nil', Emacs
     moves to the next completion style listed in `completion-styles'
     and calls its TRY-COMPLETION function, and so on until one of the
     TRY-COMPLETION functions successfully performs completion and
     returns a non-`nil' value.  A similar procedure is used for
     listing completions, via the ALL-COMPLETIONS functions.

   By default, `completion-styles-alist' contains four pre-defined
completion styles: `basic', a basic completion style;
`partial-completion', which does partial completion (completing each
word in the input separately); `emacs22', which performs completion
according to the rules used in Emacs 22; and `emacs21', which performs
completion according to the rules used in Emacs 21.

File: elisp,  Node: Programmed Completion,  Prev: Completion Styles,  Up: Completion

20.6.7 Programmed Completion
----------------------------

Sometimes it is not possible to create an alist or an obarray
containing all the intended possible completions.  In such a case, you
can supply your own function to compute the completion of a given
string.  This is called "programmed completion".

   To use this feature, pass a symbol with a function definition as the
COLLECTION argument to `completing-read'.  The function
`completing-read' arranges to pass your completion function along to
`try-completion' and `all-completions', which will then let your
function do all the work.

   The completion function should accept three arguments:

   * The string to be completed.

   * The predicate function to filter possible matches, or `nil' if
     none.  Your function should call the predicate for each possible
     match, and ignore the possible match if the predicate returns
     `nil'.

   * A flag specifying the type of operation.

   There are three flag values for three operations:

   * `nil' specifies `try-completion'.  The completion function should
     return the completion of the specified string, or `t' if the
     string is a unique and exact match already, or `nil' if the string
     matches no possibility.

     If the string is an exact match for one possibility, but also
     matches other longer possibilities, the function should return the
     string, not `t'.

   * `t' specifies `all-completions'.  The completion function should
     return a list of all possible completions of the specified string.

   * `lambda' specifies `test-completion'.  The completion function
     should return `t' if the specified string is an exact match for
     some possibility; `nil' otherwise.

   It would be consistent and clean for completion functions to allow
lambda expressions (lists that are functions) as well as function
symbols as COLLECTION, but this is impossible.  Lists as completion
tables already have other meanings, and it would be unreliable to treat
one differently just because it is also a possible function.  So you
must arrange for any function you wish to use for completion to be
encapsulated in a symbol.

   Emacs uses programmed completion when completing file names.  *Note
File Name Completion::.

 -- Function: completion-table-dynamic function
     This function is a convenient way to write a function that can act
     as programmed completion function.  The argument FUNCTION should be
     a function that takes one argument, a string, and returns an alist
     of possible completions of it.  You can think of
     `completion-table-dynamic' as a transducer between that interface
     and the interface for programmed completion functions.

File: elisp,  Node: Yes-or-No Queries,  Next: Multiple Queries,  Prev: Completion,  Up: Minibuffers

20.7 Yes-or-No Queries
======================

This section describes functions used to ask the user a yes-or-no
question.  The function `y-or-n-p' can be answered with a single
character; it is useful for questions where an inadvertent wrong answer
will not have serious consequences.  `yes-or-no-p' is suitable for more
momentous questions, since it requires three or four characters to
answer.

   If either of these functions is called in a command that was invoked
using the mouse--more precisely, if `last-nonmenu-event' (*note Command
Loop Info::) is either `nil' or a list--then it uses a dialog box or
pop-up menu to ask the question.  Otherwise, it uses keyboard input.
You can force use of the mouse or use of keyboard input by binding
`last-nonmenu-event' to a suitable value around the call.

   Strictly speaking, `yes-or-no-p' uses the minibuffer and `y-or-n-p'
does not; but it seems best to describe them together.

 -- Function: y-or-n-p prompt
     This function asks the user a question, expecting input in the echo
     area.  It returns `t' if the user types `y', `nil' if the user
     types `n'.  This function also accepts <SPC> to mean yes and <DEL>
     to mean no.  It accepts `C-]' to mean "quit," like `C-g', because
     the question might look like a minibuffer and for that reason the
     user might try to use `C-]' to get out.  The answer is a single
     character, with no <RET> needed to terminate it.  Upper and lower
     case are equivalent.

     "Asking the question" means printing PROMPT in the echo area,
     followed by the string `(y or n) '.  If the input is not one of
     the expected answers (`y', `n', `<SPC>', `<DEL>', or something
     that quits), the function responds `Please answer y or n.', and
     repeats the request.

     This function does not actually use the minibuffer, since it does
     not allow editing of the answer.  It actually uses the echo area
     (*note The Echo Area::), which uses the same screen space as the
     minibuffer.  The cursor moves to the echo area while the question
     is being asked.

     The answers and their meanings, even `y' and `n', are not
     hardwired.  The keymap `query-replace-map' specifies them.  *Note
     Search and Replace::.

     In the following example, the user first types `q', which is
     invalid.  At the next prompt the user types `y'.

          (y-or-n-p "Do you need a lift? ")

          ;; After evaluation of the preceding expression,
          ;;   the following prompt appears in the echo area:

          ---------- Echo area ----------
          Do you need a lift? (y or n)
          ---------- Echo area ----------

          ;; If the user then types `q', the following appears:

          ---------- Echo area ----------
          Please answer y or n.  Do you need a lift? (y or n)
          ---------- Echo area ----------

          ;; When the user types a valid answer,
          ;;   it is displayed after the question:

          ---------- Echo area ----------
          Do you need a lift? (y or n) y
          ---------- Echo area ----------

     We show successive lines of echo area messages, but only one
     actually appears on the screen at a time.

 -- Function: y-or-n-p-with-timeout prompt seconds default-value
     Like `y-or-n-p', except that if the user fails to answer within
     SECONDS seconds, this function stops waiting and returns
     DEFAULT-VALUE.  It works by setting up a timer; see *note Timers::.
     The argument SECONDS may be an integer or a floating point number.

 -- Function: yes-or-no-p prompt
     This function asks the user a question, expecting input in the
     minibuffer.  It returns `t' if the user enters `yes', `nil' if the
     user types `no'.  The user must type <RET> to finalize the
     response.  Upper and lower case are equivalent.

     `yes-or-no-p' starts by displaying PROMPT in the echo area,
     followed by `(yes or no) '.  The user must type one of the
     expected responses; otherwise, the function responds `Please answer
     yes or no.', waits about two seconds and repeats the request.

     `yes-or-no-p' requires more work from the user than `y-or-n-p' and
     is appropriate for more crucial decisions.

     Here is an example:

          (yes-or-no-p "Do you really want to remove everything? ")

          ;; After evaluation of the preceding expression,
          ;;   the following prompt appears,
          ;;   with an empty minibuffer:

          ---------- Buffer: minibuffer ----------
          Do you really want to remove everything? (yes or no)
          ---------- Buffer: minibuffer ----------

     If the user first types `y <RET>', which is invalid because this
     function demands the entire word `yes', it responds by displaying
     these prompts, with a brief pause between them:

          ---------- Buffer: minibuffer ----------
          Please answer yes or no.
          Do you really want to remove everything? (yes or no)
          ---------- Buffer: minibuffer ----------

File: elisp,  Node: Multiple Queries,  Next: Reading a Password,  Prev: Yes-or-No Queries,  Up: Minibuffers

20.8 Asking Multiple Y-or-N Questions
=====================================

When you have a series of similar questions to ask, such as "Do you
want to save this buffer" for each buffer in turn, you should use
`map-y-or-n-p' to ask the collection of questions, rather than asking
each question individually.  This gives the user certain convenient
facilities such as the ability to answer the whole series at once.

 -- Function: map-y-or-n-p prompter actor list &optional help
          action-alist no-cursor-in-echo-area
     This function asks the user a series of questions, reading a
     single-character answer in the echo area for each one.

     The value of LIST specifies the objects to ask questions about.
     It should be either a list of objects or a generator function.  If
     it is a function, it should expect no arguments, and should return
     either the next object to ask about, or `nil' meaning stop asking
     questions.

     The argument PROMPTER specifies how to ask each question.  If
     PROMPTER is a string, the question text is computed like this:

          (format PROMPTER OBJECT)

     where OBJECT is the next object to ask about (as obtained from
     LIST).

     If not a string, PROMPTER should be a function of one argument
     (the next object to ask about) and should return the question
     text.  If the value is a string, that is the question to ask the
     user.  The function can also return `t' meaning do act on this
     object (and don't ask the user), or `nil' meaning ignore this
     object (and don't ask the user).

     The argument ACTOR says how to act on the answers that the user
     gives.  It should be a function of one argument, and it is called
     with each object that the user says yes for.  Its argument is
     always an object obtained from LIST.

     If the argument HELP is given, it should be a list of this form:

          (SINGULAR PLURAL ACTION)

     where SINGULAR is a string containing a singular noun that
     describes the objects conceptually being acted on, PLURAL is the
     corresponding plural noun, and ACTION is a transitive verb
     describing what ACTOR does.

     If you don't specify HELP, the default is `("object" "objects"
     "act on")'.

     Each time a question is asked, the user may enter `y', `Y', or
     <SPC> to act on that object; `n', `N', or <DEL> to skip that
     object; `!' to act on all following objects; <ESC> or `q' to exit
     (skip all following objects); `.' (period) to act on the current
     object and then exit; or `C-h' to get help.  These are the same
     answers that `query-replace' accepts.  The keymap
     `query-replace-map' defines their meaning for `map-y-or-n-p' as
     well as for `query-replace'; see *note Search and Replace::.

     You can use ACTION-ALIST to specify additional possible answers
     and what they mean.  It is an alist of elements of the form `(CHAR
     FUNCTION HELP)', each of which defines one additional answer.  In
     this element, CHAR is a character (the answer); FUNCTION is a
     function of one argument (an object from LIST); HELP is a string.

     When the user responds with CHAR, `map-y-or-n-p' calls FUNCTION.
     If it returns non-`nil', the object is considered "acted upon,"
     and `map-y-or-n-p' advances to the next object in LIST.  If it
     returns `nil', the prompt is repeated for the same object.

     Normally, `map-y-or-n-p' binds `cursor-in-echo-area' while
     prompting.  But if NO-CURSOR-IN-ECHO-AREA is non-`nil', it does
     not do that.

     If `map-y-or-n-p' is called in a command that was invoked using the
     mouse--more precisely, if `last-nonmenu-event' (*note Command Loop
     Info::) is either `nil' or a list--then it uses a dialog box or
     pop-up menu to ask the question.  In this case, it does not use
     keyboard input or the echo area.  You can force use of the mouse
     or use of keyboard input by binding `last-nonmenu-event' to a
     suitable value around the call.

     The return value of `map-y-or-n-p' is the number of objects acted
     on.

File: elisp,  Node: Reading a Password,  Next: Minibuffer Commands,  Prev: Multiple Queries,  Up: Minibuffers

20.9 Reading a Password
=======================

To read a password to pass to another program, you can use the function
`read-passwd'.

 -- Function: read-passwd prompt &optional confirm default
     This function reads a password, prompting with PROMPT.  It does
     not echo the password as the user types it; instead, it echoes `.'
     for each character in the password.

     The optional argument CONFIRM, if non-`nil', says to read the
     password twice and insist it must be the same both times.  If it
     isn't the same, the user has to type it over and over until the
     last two times match.

     The optional argument DEFAULT specifies the default password to
     return if the user enters empty input.  If DEFAULT is `nil', then
     `read-passwd' returns the null string in that case.

File: elisp,  Node: Minibuffer Commands,  Next: Minibuffer Contents,  Prev: Reading a Password,  Up: Minibuffers

20.10 Minibuffer Commands
=========================

This section describes some commands meant for use in the minibuffer.

 -- Command: exit-minibuffer
     This command exits the active minibuffer.  It is normally bound to
     keys in minibuffer local keymaps.

 -- Command: self-insert-and-exit
     This command exits the active minibuffer after inserting the last
     character typed on the keyboard (found in `last-command-event';
     *note Command Loop Info::).

 -- Command: previous-history-element n
     This command replaces the minibuffer contents with the value of the
     Nth previous (older) history element.

 -- Command: next-history-element n
     This command replaces the minibuffer contents with the value of the
     Nth more recent history element.

 -- Command: previous-matching-history-element pattern n
     This command replaces the minibuffer contents with the value of the
     Nth previous (older) history element that matches PATTERN (a
     regular expression).

 -- Command: next-matching-history-element pattern n
     This command replaces the minibuffer contents with the value of the
     Nth next (newer) history element that matches PATTERN (a regular
     expression).

File: elisp,  Node: Minibuffer Contents,  Next: Minibuffer Windows,  Prev: Minibuffer Commands,  Up: Minibuffers

20.12 Minibuffer Contents
=========================

These functions access the minibuffer prompt and contents.

 -- Function: minibuffer-prompt
     This function returns the prompt string of the currently active
     minibuffer.  If no minibuffer is active, it returns `nil'.

 -- Function: minibuffer-prompt-end
     This function returns the current position of the end of the
     minibuffer prompt, if a minibuffer is current.  Otherwise, it
     returns the minimum valid buffer position.

 -- Function: minibuffer-prompt-width
     This function returns the current display-width of the minibuffer
     prompt, if a minibuffer is current.  Otherwise, it returns zero.

 -- Function: minibuffer-contents
     This function returns the editable contents of the minibuffer
     (that is, everything except the prompt) as a string, if a
     minibuffer is current.  Otherwise, it returns the entire contents
     of the current buffer.

 -- Function: minibuffer-contents-no-properties
     This is like `minibuffer-contents', except that it does not copy
     text properties, just the characters themselves.  *Note Text
     Properties::.

 -- Function: minibuffer-completion-contents
     This is like `minibuffer-contents', except that it returns only
     the contents before point.  That is the part that completion
     commands operate on.  *Note Minibuffer Completion::.

 -- Function: delete-minibuffer-contents
     This function erases the editable contents of the minibuffer (that
     is, everything except the prompt), if a minibuffer is current.
     Otherwise, it erases the entire current buffer.

File: elisp,  Node: Minibuffer Windows,  Next: Recursive Mini,  Prev: Minibuffer Contents,  Up: Minibuffers

20.11 Minibuffer Windows
========================

These functions access and select minibuffer windows and test whether
they are active.

 -- Function: active-minibuffer-window
     This function returns the currently active minibuffer window, or
     `nil' if none is currently active.

 -- Function: minibuffer-window &optional frame
     This function returns the minibuffer window used for frame FRAME.
     If FRAME is `nil', that stands for the current frame.  Note that
     the minibuffer window used by a frame need not be part of that
     frame--a frame that has no minibuffer of its own necessarily uses
     some other frame's minibuffer window.

 -- Function: set-minibuffer-window window
     This function specifies WINDOW as the minibuffer window to use.
     This affects where the minibuffer is displayed if you put text in
     it without invoking the usual minibuffer commands.  It has no
     effect on the usual minibuffer input functions because they all
     start by choosing the minibuffer window according to the current
     frame.

 -- Function: window-minibuffer-p &optional window
     This function returns non-`nil' if WINDOW is a minibuffer window.
     WINDOW defaults to the selected window.

   It is not correct to determine whether a given window is a
minibuffer by comparing it with the result of `(minibuffer-window)',
because there can be more than one minibuffer window if there is more
than one frame.

 -- Function: minibuffer-window-active-p window
     This function returns non-`nil' if WINDOW, assumed to be a
     minibuffer window, is currently active.

File: elisp,  Node: Recursive Mini,  Next: Minibuffer Misc,  Prev: Minibuffer Windows,  Up: Minibuffers

20.13 Recursive Minibuffers
===========================

These functions and variables deal with recursive minibuffers (*note
Recursive Editing::):

 -- Function: minibuffer-depth
     This function returns the current depth of activations of the
     minibuffer, a nonnegative integer.  If no minibuffers are active,
     it returns zero.

 -- User Option: enable-recursive-minibuffers
     If this variable is non-`nil', you can invoke commands (such as
     `find-file') that use minibuffers even while the minibuffer window
     is active.  Such invocation produces a recursive editing level for
     a new minibuffer.  The outer-level minibuffer is invisible while
     you are editing the inner one.

     If this variable is `nil', you cannot invoke minibuffer commands
     when the minibuffer window is active, not even if you switch to
     another window to do it.

   If a command name has a property `enable-recursive-minibuffers' that
is non-`nil', then the command can use the minibuffer to read arguments
even if it is invoked from the minibuffer.  A command can also achieve
this by binding `enable-recursive-minibuffers' to `t' in the
interactive declaration (*note Using Interactive::).  The minibuffer
command `next-matching-history-element' (normally `M-s' in the
minibuffer) does the latter.

File: elisp,  Node: Minibuffer Misc,  Prev: Recursive Mini,  Up: Minibuffers

20.14 Minibuffer Miscellany
===========================

 -- Function: minibufferp &optional buffer-or-name
     This function returns non-`nil' if BUFFER-OR-NAME is a minibuffer.
     If BUFFER-OR-NAME is omitted, it tests the current buffer.

 -- Variable: minibuffer-setup-hook
     This is a normal hook that is run whenever the minibuffer is
     entered.  *Note Hooks::.

 -- Variable: minibuffer-exit-hook
     This is a normal hook that is run whenever the minibuffer is
     exited.  *Note Hooks::.

 -- Variable: minibuffer-help-form
     The current value of this variable is used to rebind `help-form'
     locally inside the minibuffer (*note Help Functions::).

 -- Variable: minibuffer-scroll-window
     If the value of this variable is non-`nil', it should be a window
     object.  When the function `scroll-other-window' is called in the
     minibuffer, it scrolls this window.

 -- Function: minibuffer-selected-window
     This function returns the window which was selected when the
     minibuffer was entered.  If selected window is not a minibuffer
     window, it returns `nil'.

 -- User Option: max-mini-window-height
     This variable specifies the maximum height for resizing minibuffer
     windows.  If a float, it specifies a fraction of the height of the
     frame.  If an integer, it specifies a number of lines.

 -- Function: minibuffer-message string &rest args
     This function displays STRING temporarily at the end of the
     minibuffer text, for two seconds, or until the next input event
     arrives, whichever comes first.  If ARGS is non-`nil', the actual
     message is obtained by passing STRING and ARGS through `format'.
     *Note Formatting Strings::.

File: elisp,  Node: Command Loop,  Next: Keymaps,  Prev: Minibuffers,  Up: Top

21 Command Loop
***************

When you run Emacs, it enters the "editor command loop" almost
immediately.  This loop reads key sequences, executes their definitions,
and displays the results.  In this chapter, we describe how these things
are done, and the subroutines that allow Lisp programs to do them.

* Menu:

* 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.
* Distinguish Interactive::     Making a command distinguish interactive calls.
* Command Loop Info::   Variables set by the command loop for you to examine.
* Adjusting Point::     Adjustment of point after a command.
* Input Events::	What input looks like when you read it.
* Reading Input::       How to read input events from the keyboard or mouse.
* Special Events::      Events processed immediately and individually.
* 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.

File: elisp,  Node: Command Overview,  Next: Defining Commands,  Up: Command Loop

21.1 Command Loop Overview
==========================

The first thing the command loop must do is read a key sequence, which
is a sequence of events that translates into a command.  It does this by
calling the function `read-key-sequence'.  Your Lisp code can also call
this function (*note Key Sequence Input::).  Lisp programs can also do
input at a lower level with `read-event' (*note Reading One Event::) or
discard pending input with `discard-input' (*note Event Input Misc::).

   The key sequence is translated into a command through the currently
active keymaps.  *Note Key Lookup::, for information on how this is
done.  The result should be a keyboard macro or an interactively
callable function.  If the key is `M-x', then it reads the name of
another command, which it then calls.  This is done by the command
`execute-extended-command' (*note Interactive Call::).

   To execute a command requires first reading the arguments for it.
This is done by calling `command-execute' (*note Interactive Call::).
For commands written in Lisp, the `interactive' specification says how
to read the arguments.  This may use the prefix argument (*note Prefix
Command Arguments::) or may read with prompting in the minibuffer
(*note Minibuffers::).  For example, the command `find-file' has an
`interactive' specification which says to read a file name using the
minibuffer.  The command's function body does not use the minibuffer;
if you call this command from Lisp code as a function, you must supply
the file name string as an ordinary Lisp function argument.

   If the command is a string or vector (i.e., a keyboard macro) then
`execute-kbd-macro' is used to execute it.  You can call this function
yourself (*note Keyboard Macros::).

   To terminate the execution of a running command, type `C-g'.  This
character causes "quitting" (*note Quitting::).

 -- Variable: pre-command-hook
     The editor command loop runs this normal hook before each command.
     At that time, `this-command' contains the command that is about to
     run, and `last-command' describes the previous command.  *Note
     Command Loop Info::.

 -- Variable: post-command-hook
     The editor command loop runs this normal hook after each command
     (including commands terminated prematurely by quitting or by
     errors), and also when the command loop is first entered.  At that
     time, `this-command' refers to the command that just ran, and
     `last-command' refers to the command before that.

   Quitting is suppressed while running `pre-command-hook' and
`post-command-hook'.  If an error happens while executing one of these
hooks, it terminates execution of the hook, and clears the hook
variable to `nil' so as to prevent an infinite loop of errors.

   A request coming into the Emacs server (*note Emacs Server:
(emacs)Emacs Server.) runs these two hooks just as a keyboard command
does.

File: elisp,  Node: Defining Commands,  Next: Interactive Call,  Prev: Command Overview,  Up: Command Loop

21.2 Defining Commands
======================

The special form `interactive' turns a Lisp function into a command.
The `interactive' form must be located at top-level in the function
body (usually as the first form in the body), or in the
`interactive-form' property of the function symbol.  When the
`interactive' form is located in the function body, it does nothing
when actually executed.  Its presence serves as a flag, which tells the
Emacs command loop that the function can be called interactively.  The
argument of the `interactive' form controls the reading of arguments
for an interactive call.

* Menu:

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

File: elisp,  Node: Using Interactive,  Next: Interactive Codes,  Up: Defining Commands

21.2.1 Using `interactive'
--------------------------

This section describes how to write the `interactive' form that makes a
Lisp function an interactively-callable command, and how to examine a
command's `interactive' form.

 -- Special Form: interactive arg-descriptor
     This special form declares that a function is a command, and that
     it may therefore be called interactively (via `M-x' or by entering
     a key sequence bound to it).  The argument ARG-DESCRIPTOR declares
     how to compute the arguments to the command when the command is
     called interactively.

     A command may be called from Lisp programs like any other
     function, but then the caller supplies the arguments and
     ARG-DESCRIPTOR has no effect.

     The `interactive' form must be located at top-level in the
     function body, or in the function symbol's `interactive-form'
     property (*note Symbol Plists::).  It has its effect because the
     command loop looks for it before calling the function (*note
     Interactive Call::).  Once the function is called, all its body
     forms are executed; at this time, if the `interactive' form occurs
     within the body, the form simply returns `nil' without even
     evaluating its argument.

     By convention, you should put the `interactive' form in the
     function body, as the first top-level form.  If there is an
     `interactive' form in both the `interactive-form' symbol property
     and the function body, the former takes precedence.  The
     `interactive-form' symbol property can be used to add an
     interactive form to an existing function, or change how its
     arguments are processed interactively, without redefining the
     function.

   There are three possibilities for the argument ARG-DESCRIPTOR:

   * It may be omitted or `nil'; then the command is called with no
     arguments.  This leads quickly to an error if the command requires
     one or more arguments.

   * It may be a string; its contents are a sequence of elements
     separated by newlines, one for each parameter(1).  Each element
     consists of a code character (*note Interactive Codes::)
     optionally followed by a prompt (which some code characters use
     and some ignore).  Here is an example:

          (interactive "P\nbFrobnicate buffer: ")

     The code letter `P' sets the command's first argument to the raw
     command prefix (*note Prefix Command Arguments::).  `bFrobnicate
     buffer: ' prompts the user with `Frobnicate buffer: ' to enter the
     name of an existing buffer, which becomes the second and final
     argument.

     The prompt string can use `%' to include previous argument values
     (starting with the first argument) in the prompt.  This is done
     using `format' (*note Formatting Strings::).  For example, here is
     how you could read the name of an existing buffer followed by a
     new name to give to that buffer:

          (interactive "bBuffer to rename: \nsRename buffer %s to: ")

     If `*' appears at the beginning of the string, then an error is
     signaled if the buffer is read-only.

     If `@' appears at the beginning of the string, and if the key
     sequence used to invoke the command includes any mouse events, then
     the window associated with the first of those events is selected
     before the command is run.

     If `^' appears at the beginning of the string, and if the command
     was invoked through "shift-translation", set the mark and activate
     the region temporarily, or extend an already active region, before
     the command is run.  If the command was invoked without
     shift-translation, and the region is temporarily active,
     deactivate the region before the command is run.
     Shift-translation is controlled on the user level by
     `shift-select-mode'; see *note Shift Selection: (emacs)Shift
     Selection.

     You can use `*', `@', and `^' together; the order does not matter.
     Actual reading of arguments is controlled by the rest of the
     prompt string (starting with the first character that is not `*',
     `@', or `^').

   * It may be a Lisp expression that is not a string; then it should
     be a form that is evaluated to get a list of arguments to pass to
     the command.  Usually this form will call various functions to
     read input from the user, most often through the minibuffer (*note
     Minibuffers::) or directly from the keyboard (*note Reading
     Input::).

     Providing point or the mark as an argument value is also common,
     but if you do this _and_ read input (whether using the minibuffer
     or not), be sure to get the integer values of point or the mark
     after reading.  The current buffer may be receiving subprocess
     output; if subprocess output arrives while the command is waiting
     for input, it could relocate point and the mark.

     Here's an example of what _not_ to do:

          (interactive
           (list (region-beginning) (region-end)
                 (read-string "Foo: " nil 'my-history)))

     Here's how to avoid the problem, by examining point and the mark
     after reading the keyboard input:

          (interactive
           (let ((string (read-string "Foo: " nil 'my-history)))
             (list (region-beginning) (region-end) string)))

     *Warning:* the argument values should not include any data types
     that can't be printed and then read.  Some facilities save
     `command-history' in a file to be read in the subsequent sessions;
     if a command's arguments contain a data type that prints using
     `#<...>' syntax, those facilities won't work.

     There are, however, a few exceptions: it is ok to use a limited
     set of expressions such as `(point)', `(mark)',
     `(region-beginning)', and `(region-end)', because Emacs recognizes
     them specially and puts the expression (rather than its value)
     into the command history.  To see whether the expression you wrote
     is one of these exceptions, run the command, then examine `(car
     command-history)'.

 -- Function: interactive-form function
     This function returns the `interactive' form of FUNCTION.  If
     FUNCTION is an interactively callable function (*note Interactive
     Call::), the value is the command's `interactive' form
     `(interactive SPEC)', which specifies how to compute its
     arguments.  Otherwise, the value is `nil'.  If FUNCTION is a
     symbol, its function definition is used.

   ---------- Footnotes ----------

   (1) Some elements actually supply two parameters.

File: elisp,  Node: Interactive Codes,  Next: Interactive Examples,  Prev: Using Interactive,  Up: Defining Commands

21.2.2 Code Characters for `interactive'
----------------------------------------

The code character descriptions below contain a number of key words,
defined here as follows:

Completion
     Provide completion.  <TAB>, <SPC>, and <RET> perform name
     completion because the argument is read using `completing-read'
     (*note Completion::).  `?' displays a list of possible completions.

Existing
     Require the name of an existing object.  An invalid name is not
     accepted; the commands to exit the minibuffer do not exit if the
     current input is not valid.

Default
     A default value of some sort is used if the user enters no text in
     the minibuffer.  The default depends on the code character.

No I/O
     This code letter computes an argument without reading any input.
     Therefore, it does not use a prompt string, and any prompt string
     you supply is ignored.

     Even though the code letter doesn't use a prompt string, you must
     follow it with a newline if it is not the last code character in
     the string.

Prompt
     A prompt immediately follows the code character.  The prompt ends
     either with the end of the string or with a newline.

Special
     This code character is meaningful only at the beginning of the
     interactive string, and it does not look for a prompt or a newline.
     It is a single, isolated character.

   Here are the code character descriptions for use with `interactive':

`*'
     Signal an error if the current buffer is read-only.  Special.

`@'
     Select the window mentioned in the first mouse event in the key
     sequence that invoked this command.  Special.

`^'
     If the command was invoked through shift-translation, set the mark
     and activate the region temporarily, or extend an already active
     region, before the command is run.  If the command was invoked
     without shift-translation, and the region is temporarily active,
     deactivate the region before the command is run.  Special.

`a'
     A function name (i.e., a symbol satisfying `fboundp').  Existing,
     Completion, Prompt.

`b'
     The name of an existing buffer.  By default, uses the name of the
     current buffer (*note Buffers::).  Existing, Completion, Default,
     Prompt.

`B'
     A buffer name.  The buffer need not exist.  By default, uses the
     name of a recently used buffer other than the current buffer.
     Completion, Default, Prompt.

`c'
     A character.  The cursor does not move into the echo area.  Prompt.

`C'
     A command name (i.e., a symbol satisfying `commandp').  Existing,
     Completion, Prompt.

`d'
     The position of point, as an integer (*note Point::).  No I/O.

`D'
     A directory name.  The default is the current default directory of
     the current buffer, `default-directory' (*note File Name
     Expansion::).  Existing, Completion, Default, Prompt.

`e'
     The first or next mouse event in the key sequence that invoked the
     command.  More precisely, `e' gets events that are lists, so you
     can look at the data in the lists.  *Note Input Events::.  No I/O.

     You can use `e' more than once in a single command's interactive
     specification.  If the key sequence that invoked the command has N
     events that are lists, the Nth `e' provides the Nth such event.
     Events that are not lists, such as function keys and ASCII
     characters, do not count where `e' is concerned.

`f'
     A file name of an existing file (*note File Names::).  The default
     directory is `default-directory'.  Existing, Completion, Default,
     Prompt.

`F'
     A file name.  The file need not exist.  Completion, Default,
     Prompt.

`G'
     A file name.  The file need not exist.  If the user enters just a
     directory name, then the value is just that directory name, with no
     file name within the directory added.  Completion, Default, Prompt.

`i'
     An irrelevant argument.  This code always supplies `nil' as the
     argument's value.  No I/O.

`k'
     A key sequence (*note Key Sequences::).  This keeps reading events
     until a command (or undefined command) is found in the current key
     maps.  The key sequence argument is represented as a string or
     vector.  The cursor does not move into the echo area.  Prompt.

     If `k' reads a key sequence that ends with a down-event, it also
     reads and discards the following up-event.  You can get access to
     that up-event with the `U' code character.

     This kind of input is used by commands such as `describe-key' and
     `global-set-key'.

`K'
     A key sequence, whose definition you intend to change.  This works
     like `k', except that it suppresses, for the last input event in
     the key sequence, the conversions that are normally used (when
     necessary) to convert an undefined key into a defined one.

`m'
     The position of the mark, as an integer.  No I/O.

`M'
     Arbitrary text, read in the minibuffer using the current buffer's
     input method, and returned as a string (*note Input Methods:
     (emacs)Input Methods.).  Prompt.

`n'
     A number, read with the minibuffer.  If the input is not a number,
     the user has to try again.  `n' never uses the prefix argument.
     Prompt.

`N'
     The numeric prefix argument; but if there is no prefix argument,
     read a number as with `n'.  The value is always a number.  *Note
     Prefix Command Arguments::.  Prompt.

`p'
     The numeric prefix argument.  (Note that this `p' is lower case.)
     No I/O.

`P'
     The raw prefix argument.  (Note that this `P' is upper case.)  No
     I/O.

`r'
     Point and the mark, as two numeric arguments, smallest first.
     This is the only code letter that specifies two successive
     arguments rather than one.  No I/O.

`s'
     Arbitrary text, read in the minibuffer and returned as a string
     (*note Text from Minibuffer::).  Terminate the input with either
     `C-j' or <RET>.  (`C-q' may be used to include either of these
     characters in the input.)  Prompt.

`S'
     An interned symbol whose name is read in the minibuffer.  Any
     whitespace character terminates the input.  (Use `C-q' to include
     whitespace in the string.)  Other characters that normally
     terminate a symbol (e.g., parentheses and brackets) do not do so
     here.  Prompt.

`U'
     A key sequence or `nil'.  Can be used after a `k' or `K' argument
     to get the up-event that was discarded (if any) after `k' or `K'
     read a down-event.  If no up-event has been discarded, `U'
     provides `nil' as the argument.  No I/O.

`v'
     A variable declared to be a user option (i.e., satisfying the
     predicate `user-variable-p').  This reads the variable using
     `read-variable'.  *Note Definition of read-variable::.  Existing,
     Completion, Prompt.

`x'
     A Lisp object, specified with its read syntax, terminated with a
     `C-j' or <RET>.  The object is not evaluated.  *Note Object from
     Minibuffer::.  Prompt.

`X'
     A Lisp form's value.  `X' reads as `x' does, then evaluates the
     form so that its value becomes the argument for the command.
     Prompt.

`z'
     A coding system name (a symbol).  If the user enters null input,
     the argument value is `nil'.  *Note Coding Systems::.  Completion,
     Existing, Prompt.

`Z'
     A coding system name (a symbol)--but only if this command has a
     prefix argument.  With no prefix argument, `Z' provides `nil' as
     the argument value.  Completion, Existing, Prompt.

File: elisp,  Node: Interactive Examples,  Prev: Interactive Codes,  Up: Defining Commands

21.2.3 Examples of Using `interactive'
--------------------------------------

Here are some examples of `interactive':

     (defun foo1 ()              ; `foo1' takes no arguments,
         (interactive)           ;   just moves forward two words.
         (forward-word 2))
          => foo1

     (defun foo2 (n)             ; `foo2' takes one argument,
         (interactive "^p")      ;   which is the numeric prefix.
                                 ; under `shift-select-mode',
                                 ;   will activate or extend region.
         (forward-word (* 2 n)))
          => foo2

     (defun foo3 (n)             ; `foo3' takes one argument,
         (interactive "nCount:") ;   which is read with the Minibuffer.
         (forward-word (* 2 n)))
          => foo3

     (defun three-b (b1 b2 b3)
       "Select three existing buffers.
     Put them into three windows, selecting the last one."
         (interactive "bBuffer1:\nbBuffer2:\nbBuffer3:")
         (delete-other-windows)
         (split-window (selected-window) 8)
         (switch-to-buffer b1)
         (other-window 1)
         (split-window (selected-window) 8)
         (switch-to-buffer b2)
         (other-window 1)
         (switch-to-buffer b3))
          => three-b
     (three-b "*scratch*" "declarations.texi" "*mail*")
          => nil

File: elisp,  Node: Interactive Call,  Next: Distinguish Interactive,  Prev: Defining Commands,  Up: Command Loop

21.3 Interactive Call
=====================

After the command loop has translated a key sequence into a command, it
invokes that command using the function `command-execute'.  If the
command is a function, `command-execute' calls `call-interactively',
which reads the arguments and calls the command.  You can also call
these functions yourself.

 -- Function: commandp object &optional for-call-interactively
     Returns `t' if OBJECT is suitable for calling interactively; that
     is, if OBJECT is a command.  Otherwise, returns `nil'.

     Interactively-callable objects include strings and vectors (which
     are treated as keyboard macros), lambda expressions that contain a
     top-level `interactive' form (*note Using Interactive::),
     byte-code function objects made from such lambda expressions,
     autoload objects that are declared as interactive (non-`nil' fourth
     argument to `autoload'), and some primitive functions.

     A symbol satisfies `commandp' if it has a non-`nil'
     `interactive-form' property, or if its function definition
     satisfies `commandp'.  Keys and keymaps are not commands.  Rather,
     they are used to look up commands (*note Keymaps::).

     If FOR-CALL-INTERACTIVELY is non-`nil', then `commandp' returns
     `t' only for objects that `call-interactively' could call--thus,
     not for keyboard macros.

     See `documentation' in *note Accessing Documentation::, for a
     realistic example of using `commandp'.

 -- Function: call-interactively command &optional record-flag keys
     This function calls the interactively callable function COMMAND,
     reading arguments according to its interactive calling
     specifications.  It returns whatever COMMAND returns.  An error is
     signaled if COMMAND is not a function or if it cannot be called
     interactively (i.e., is not a command).  Note that keyboard macros
     (strings and vectors) are not accepted, even though they are
     considered commands, because they are not functions.  If COMMAND
     is a symbol, then `call-interactively' uses its function
     definition.

     If RECORD-FLAG is non-`nil', then this command and its arguments
     are unconditionally added to the list `command-history'.
     Otherwise, the command is added only if it uses the minibuffer to
     read an argument.  *Note Command History::.

     The argument KEYS, if given, should be a vector which specifies
     the sequence of events to supply if the command inquires which
     events were used to invoke it.  If KEYS is omitted or `nil', the
     default is the return value of `this-command-keys-vector'.  *Note
     Definition of this-command-keys-vector::.

 -- Function: command-execute command &optional record-flag keys special
     This function executes COMMAND.  The argument COMMAND must satisfy
     the `commandp' predicate; i.e., it must be an interactively
     callable function or a keyboard macro.

     A string or vector as COMMAND is executed with
     `execute-kbd-macro'.  A function is passed to
     `call-interactively', along with the optional RECORD-FLAG and KEYS.

     A symbol is handled by using its function definition in its place.
     A symbol with an `autoload' definition counts as a command if it
     was declared to stand for an interactively callable function.
     Such a definition is handled by loading the specified library and
     then rechecking the definition of the symbol.

     The argument SPECIAL, if given, means to ignore the prefix
     argument and not clear it.  This is used for executing special
     events (*note Special Events::).

 -- Command: execute-extended-command prefix-argument
     This function reads a command name from the minibuffer using
     `completing-read' (*note Completion::).  Then it uses
     `command-execute' to call the specified command.  Whatever that
     command returns becomes the value of `execute-extended-command'.

     If the command asks for a prefix argument, it receives the value
     PREFIX-ARGUMENT.  If `execute-extended-command' is called
     interactively, the current raw prefix argument is used for
     PREFIX-ARGUMENT, and thus passed on to whatever command is run.

     `execute-extended-command' is the normal definition of `M-x', so
     it uses the string `M-x ' as a prompt.  (It would be better to
     take the prompt from the events used to invoke
     `execute-extended-command', but that is painful to implement.)  A
     description of the value of the prefix argument, if any, also
     becomes part of the prompt.

          (execute-extended-command 3)
          ---------- Buffer: Minibuffer ----------
          3 M-x forward-word RET
          ---------- Buffer: Minibuffer ----------
               => t

File: elisp,  Node: Distinguish Interactive,  Next: Command Loop Info,  Prev: Interactive Call,  Up: Command Loop

21.4 Distinguish Interactive Calls
==================================

Sometimes a command should display additional visual feedback (such as
an informative message in the echo area) for interactive calls only.
There are three ways to do this.  The recommended way to test whether
the function was called using `call-interactively' is to give it an
optional argument `print-message' and use the `interactive' spec to
make it non-`nil' in interactive calls.  Here's an example:

     (defun foo (&optional print-message)
       (interactive "p")
       (when print-message
         (message "foo")))

We use `"p"' because the numeric prefix argument is never `nil'.
Defined in this way, the function does display the message when called
from a keyboard macro.

   The above method with the additional argument is usually best,
because it allows callers to say "treat this call as interactive."  But
you can also do the job in a simpler way by testing
`called-interactively-p'.

 -- Function: called-interactively-p
     This function returns `t' when the calling function was called
     using `call-interactively'.

     If the containing function was called by Lisp evaluation (or with
     `apply' or `funcall'), then it was not called interactively.

   Here's an example of using `called-interactively-p':

     (defun foo ()
       (interactive)
       (when (called-interactively-p)
         (message "foo"))
       'haha)
          => foo

     ;; Type `M-x foo'.
          -| foo

     (foo)
          => haha

   Here is another example that contrasts direct and indirect calls to
`called-interactively-p'.

     (defun bar ()
       (interactive)
       (setq foobar (list (foo) (called-interactively-p))))
          => bar

     ;; Type `M-x bar'.
     ;; This does not display a message.

     foobar
          => (nil t)

   If you want to treat commands run in keyboard macros just like calls
from Lisp programs, test `interactive-p' instead of
`called-interactively-p'.

 -- Function: interactive-p
     This function returns `t' if the containing function (the one
     whose code includes the call to `interactive-p') was called in
     direct response to user input.  This means that it was called with
     the function `call-interactively', and that a keyboard macro is
     not running, and that Emacs is not running in batch mode.

File: elisp,  Node: Command Loop Info,  Next: Adjusting Point,  Prev: Distinguish Interactive,  Up: Command Loop

21.5 Information from the Command Loop
======================================

The editor command loop sets several Lisp variables to keep status
records for itself and for commands that are run.  With the exception of
`this-command' and `last-command' it's generally a bad idea to change
any of these variables in a Lisp program.

 -- Variable: last-command
     This variable records the name of the previous command executed by
     the command loop (the one before the current command).  Normally
     the value is a symbol with a function definition, but this is not
     guaranteed.

     The value is copied from `this-command' when a command returns to
     the command loop, except when the command has specified a prefix
     argument for the following command.

     This variable is always local to the current terminal and cannot be
     buffer-local.  *Note Multiple Terminals::.

 -- Variable: real-last-command
     This variable is set up by Emacs just like `last-command', but
     never altered by Lisp programs.

 -- Variable: last-repeatable-command
     This variable stores the most recently executed command that was
     not part of an input event.  This is the command `repeat' will try
     to repeat, *Note Repeating: (emacs)Repeating.

 -- Variable: this-command
     This variable records the name of the command now being executed by
     the editor command loop.  Like `last-command', it is normally a
     symbol with a function definition.

     The command loop sets this variable just before running a command,
     and copies its value into `last-command' when the command finishes
     (unless the command specified a prefix argument for the following
     command).

     Some commands set this variable during their execution, as a flag
     for whatever command runs next.  In particular, the functions for
     killing text set `this-command' to `kill-region' so that any kill
     commands immediately following will know to append the killed text
     to the previous kill.

   If you do not want a particular command to be recognized as the
previous command in the case where it got an error, you must code that
command to prevent this.  One way is to set `this-command' to `t' at the
beginning of the command, and set `this-command' back to its proper
value at the end, like this:

     (defun foo (args...)
       (interactive ...)
       (let ((old-this-command this-command))
         (setq this-command t)
         ...do the work...
         (setq this-command old-this-command)))

We do not bind `this-command' with `let' because that would restore the
old value in case of error--a feature of `let' which in this case does
precisely what we want to avoid.

 -- Variable: this-original-command
     This has the same value as `this-command' except when command
     remapping occurs (*note Remapping Commands::).  In that case,
     `this-command' gives the command actually run (the result of
     remapping), and `this-original-command' gives the command that was
     specified to run but remapped into another command.

 -- Function: this-command-keys
     This function returns a string or vector containing the key
     sequence that invoked the present command, plus any previous
     commands that generated the prefix argument for this command.  Any
     events read by the command using `read-event' without a timeout
     get tacked on to the end.

     However, if the command has called `read-key-sequence', it returns
     the last read key sequence.  *Note Key Sequence Input::.  The
     value is a string if all events in the sequence were characters
     that fit in a string.  *Note Input Events::.

          (this-command-keys)
          ;; Now use `C-u C-x C-e' to evaluate that.
               => "^U^X^E"

 -- Function: this-command-keys-vector
     Like `this-command-keys', except that it always returns the events
     in a vector, so you don't need to deal with the complexities of
     storing input events in a string (*note Strings of Events::).

 -- Function: clear-this-command-keys &optional keep-record
     This function empties out the table of events for
     `this-command-keys' to return.  Unless KEEP-RECORD is non-`nil',
     it also empties the records that the function `recent-keys' (*note
     Recording Input::) will subsequently return.  This is useful after
     reading a password, to prevent the password from echoing
     inadvertently as part of the next command in certain cases.

 -- Variable: last-nonmenu-event
     This variable holds the last input event read as part of a key
     sequence, not counting events resulting from mouse menus.

     One use of this variable is for telling `x-popup-menu' where to pop
     up a menu.  It is also used internally by `y-or-n-p' (*note
     Yes-or-No Queries::).

 -- Variable: last-command-event
 -- Variable: last-command-char
     This variable is set to the last input event that was read by the
     command loop as part of a command.  The principal use of this
     variable is in `self-insert-command', which uses it to decide which
     character to insert.

          last-command-event
          ;; Now use `C-u C-x C-e' to evaluate that.
               => 5

     The value is 5 because that is the ASCII code for `C-e'.

     The alias `last-command-char' is obsolete.

 -- Variable: last-event-frame
     This variable records which frame the last input event was
     directed to.  Usually this is the frame that was selected when the
     event was generated, but if that frame has redirected input focus
     to another frame, the value is the frame to which the event was
     redirected.  *Note Input Focus::.

     If the last event came from a keyboard macro, the value is `macro'.

File: elisp,  Node: Adjusting Point,  Next: Input Events,  Prev: Command Loop Info,  Up: Command Loop

21.6 Adjusting Point After Commands
===================================

It is not easy to display a value of point in the middle of a sequence
of text that has the `display', `composition' or `intangible' property,
or is invisible.  Therefore, after a command finishes and returns to
the command loop, if point is within such a sequence, the command loop
normally moves point to the edge of the sequence.

   A command can inhibit this feature by setting the variable
`disable-point-adjustment':

 -- Variable: disable-point-adjustment
     If this variable is non-`nil' when a command returns to the
     command loop, then the command loop does not check for those text
     properties, and does not move point out of sequences that have
     them.

     The command loop sets this variable to `nil' before each command,
     so if a command sets it, the effect applies only to that command.

 -- Variable: global-disable-point-adjustment
     If you set this variable to a non-`nil' value, the feature of
     moving point out of these sequences is completely turned off.

File: elisp,  Node: Input Events,  Next: Reading Input,  Prev: Adjusting Point,  Up: Command Loop

21.7 Input Events
=================

The Emacs command loop reads a sequence of "input events" that
represent keyboard or mouse activity.  The events for keyboard activity
are characters or symbols; mouse events are always lists.  This section
describes the representation and meaning of input events in detail.

 -- Function: eventp object
     This function returns non-`nil' if OBJECT is an input event or
     event type.

     Note that any symbol might be used as an event or an event type.
     `eventp' cannot distinguish whether a symbol is intended by Lisp
     code to be used as an event.  Instead, it distinguishes whether the
     symbol has actually been used in an event that has been read as
     input in the current Emacs session.  If a symbol has not yet been
     so used, `eventp' returns `nil'.

* Menu:

* Keyboard Events::		Ordinary characters--keys with symbols on them.
* Function Keys::		Function keys--keys with names, not symbols.
* Mouse Events::                Overview of mouse events.
* Click Events::		Pushing and releasing a mouse button.
* Drag Events::			Moving the mouse before releasing the button.
* Button-Down Events::		A button was pushed and not yet released.
* Repeat Events::               Double and triple click (or drag, or down).
* Motion Events::		Just moving the mouse, not pushing a button.
* Focus Events::		Moving the mouse between frames.
* Misc Events::                 Other events the system can generate.
* Event Examples::		Examples of the lists for mouse events.
* Classifying Events::		Finding the modifier keys in an event symbol.
				Event types.
* Accessing Mouse::		Functions to extract info from mouse events.
* Accessing Scroll::		Functions to get info from scroll bar events.
* Strings of Events::           Special considerations for putting
				  keyboard character events in a string.

File: elisp,  Node: Keyboard Events,  Next: Function Keys,  Up: Input Events

21.7.1 Keyboard Events
----------------------

There are two kinds of input you can get from the keyboard: ordinary
keys, and function keys.  Ordinary keys correspond to characters; the
events they generate are represented in Lisp as characters.  The event
type of a character event is the character itself (an integer); see
*note Classifying Events::.

   An input character event consists of a "basic code" between 0 and
524287, plus any or all of these "modifier bits":

meta
     The 2**27 bit in the character code indicates a character typed
     with the meta key held down.

control
     The 2**26 bit in the character code indicates a non-ASCII control
     character.

     ASCII control characters such as `C-a' have special basic codes of
     their own, so Emacs needs no special bit to indicate them.  Thus,
     the code for `C-a' is just 1.

     But if you type a control combination not in ASCII, such as `%'
     with the control key, the numeric value you get is the code for
     `%' plus 2**26 (assuming the terminal supports non-ASCII control
     characters).

shift
     The 2**25 bit in the character code indicates an ASCII control
     character typed with the shift key held down.

     For letters, the basic code itself indicates upper versus lower
     case; for digits and punctuation, the shift key selects an
     entirely different character with a different basic code.  In
     order to keep within the ASCII character set whenever possible,
     Emacs avoids using the 2**25 bit for those characters.

     However, ASCII provides no way to distinguish `C-A' from `C-a', so
     Emacs uses the 2**25 bit in `C-A' and not in `C-a'.

hyper
     The 2**24 bit in the character code indicates a character typed
     with the hyper key held down.

super
     The 2**23 bit in the character code indicates a character typed
     with the super key held down.

alt
     The 2**22 bit in the character code indicates a character typed
     with the alt key held down.  (On some terminals, the key labeled
     <ALT> is actually the meta key.)

   It is best to avoid mentioning specific bit numbers in your program.
To test the modifier bits of a character, use the function
`event-modifiers' (*note Classifying Events::).  When making key
bindings, you can use the read syntax for characters with modifier bits
(`\C-', `\M-', and so on).  For making key bindings with `define-key',
you can use lists such as `(control hyper ?x)' to specify the
characters (*note Changing Key Bindings::).  The function
`event-convert-list' converts such a list into an event type (*note
Classifying Events::).

File: elisp,  Node: Function Keys,  Next: Mouse Events,  Prev: Keyboard Events,  Up: Input Events

21.7.2 Function Keys
--------------------

Most keyboards also have "function keys"--keys that have names or
symbols that are not characters.  Function keys are represented in Emacs
Lisp as symbols; the symbol's name is the function key's label, in lower
case.  For example, pressing a key labeled <F1> places the symbol `f1'
in the input stream.

   The event type of a function key event is the event symbol itself.
*Note Classifying Events::.

   Here are a few special cases in the symbol-naming convention for
function keys:

`backspace', `tab', `newline', `return', `delete'
     These keys correspond to common ASCII control characters that have
     special keys on most keyboards.

     In ASCII, `C-i' and <TAB> are the same character.  If the terminal
     can distinguish between them, Emacs conveys the distinction to
     Lisp programs by representing the former as the integer 9, and the
     latter as the symbol `tab'.

     Most of the time, it's not useful to distinguish the two.  So
     normally `local-function-key-map' (*note Translation Keymaps::) is
     set up to map `tab' into 9.  Thus, a key binding for character
     code 9 (the character `C-i') also applies to `tab'.  Likewise for
     the other symbols in this group.  The function `read-char'
     likewise converts these events into characters.

     In ASCII, <BS> is really `C-h'.  But `backspace' converts into the
     character code 127 (<DEL>), not into code 8 (<BS>).  This is what
     most users prefer.

`left', `up', `right', `down'
     Cursor arrow keys

`kp-add', `kp-decimal', `kp-divide', ...
     Keypad keys (to the right of the regular keyboard).

`kp-0', `kp-1', ...
     Keypad keys with digits.

`kp-f1', `kp-f2', `kp-f3', `kp-f4'
     Keypad PF keys.

`kp-home', `kp-left', `kp-up', `kp-right', `kp-down'
     Keypad arrow keys.  Emacs normally translates these into the
     corresponding non-keypad keys `home', `left', ...

`kp-prior', `kp-next', `kp-end', `kp-begin', `kp-insert', `kp-delete'
     Additional keypad duplicates of keys ordinarily found elsewhere.
     Emacs normally translates these into the like-named non-keypad
     keys.

   You can use the modifier keys <ALT>, <CTRL>, <HYPER>, <META>,
<SHIFT>, and <SUPER> with function keys.  The way to represent them is
with prefixes in the symbol name:

`A-'
     The alt modifier.

`C-'
     The control modifier.

`H-'
     The hyper modifier.

`M-'
     The meta modifier.

`S-'
     The shift modifier.

`s-'
     The super modifier.

   Thus, the symbol for the key <F3> with <META> held down is `M-f3'.
When you use more than one prefix, we recommend you write them in
alphabetical order; but the order does not matter in arguments to the
key-binding lookup and modification functions.

File: elisp,  Node: Mouse Events,  Next: Click Events,  Prev: Function Keys,  Up: Input Events

21.7.3 Mouse Events
-------------------

Emacs supports four kinds of mouse events: click events, drag events,
button-down events, and motion events.  All mouse events are represented
as lists.  The CAR of the list is the event type; this says which mouse
button was involved, and which modifier keys were used with it.  The
event type can also distinguish double or triple button presses (*note
Repeat Events::).  The rest of the list elements give position and time
information.

   For key lookup, only the event type matters: two events of the same
type necessarily run the same command.  The command can access the full
values of these events using the `e' interactive code.  *Note
Interactive Codes::.

   A key sequence that starts with a mouse event is read using the
keymaps of the buffer in the window that the mouse was in, not the
current buffer.  This does not imply that clicking in a window selects
that window or its buffer--that is entirely under the control of the
command binding of the key sequence.

File: elisp,  Node: Click Events,  Next: Drag Events,  Prev: Mouse Events,  Up: Input Events

21.7.4 Click Events
-------------------

When the user presses a mouse button and releases it at the same
location, that generates a "click" event.  All mouse click event share
the same format:

     (EVENT-TYPE POSITION CLICK-COUNT)

EVENT-TYPE
     This is a symbol that indicates which mouse button was used.  It is
     one of the symbols `mouse-1', `mouse-2', ..., where the buttons
     are numbered left to right.

     You can also use prefixes `A-', `C-', `H-', `M-', `S-' and `s-'
     for modifiers alt, control, hyper, meta, shift and super, just as
     you would with function keys.

     This symbol also serves as the event type of the event.  Key
     bindings describe events by their types; thus, if there is a key
     binding for `mouse-1', that binding would apply to all events whose
     EVENT-TYPE is `mouse-1'.

POSITION
     This is the position where the mouse click occurred.  The actual
     format of POSITION depends on what part of a window was clicked on.

     For mouse click events in the text area, mode line, header line,
     or in the marginal areas, POSITION has this form:

          (WINDOW POS-OR-AREA (X . Y) TIMESTAMP
           OBJECT TEXT-POS (COL . ROW)
           IMAGE (DX . DY) (WIDTH . HEIGHT))

    WINDOW
          This is the window in which the click occurred.

    POS-OR-AREA
          This is the buffer position of the character clicked on in
          the text area, or if clicked outside the text area, it is the
          window area in which the click occurred.  It is one of the
          symbols `mode-line', `header-line', `vertical-line',
          `left-margin', `right-margin', `left-fringe', or
          `right-fringe'.

          In one special case, POS-OR-AREA is a list containing a
          symbol (one of the symbols listed above) instead of just the
          symbol.  This happens after the imaginary prefix keys for the
          event are inserted into the input stream.  *Note Key Sequence
          Input::.

    X, Y
          These are the pixel coordinates of the click, relative to the
          top left corner of WINDOW, which is `(0 . 0)'.  For the mode
          or header line, Y does not have meaningful data.  For the
          vertical line, X does not have meaningful data.

    TIMESTAMP
          This is the time at which the event occurred, in milliseconds.

    OBJECT
          This is the object on which the click occurred.  It is either
          `nil' if there is no string property, or it has the form
          (STRING . STRING-POS) when there is a string-type text
          property at the click position.

         STRING
               This is the string on which the click occurred,
               including any properties.

         STRING-POS
               This is the position in the string on which the click
               occurred, relevant if properties at the click need to be
               looked up.

    TEXT-POS
          For clicks on a marginal area or on a fringe, this is the
          buffer position of the first visible character in the
          corresponding line in the window.  For other events, it is
          the current buffer position in the window.

    COL, ROW
          These are the actual coordinates of the glyph under the X, Y
          position, possibly padded with default character width glyphs
          if X is beyond the last glyph on the line.

    IMAGE
          This is the image object on which the click occurred.  It is
          either `nil' if there is no image at the position clicked on,
          or it is an image object as returned by `find-image' if click
          was in an image.

    DX, DY
          These are the pixel coordinates of the click, relative to the
          top left corner of OBJECT, which is `(0 . 0)'.  If OBJECT is
          `nil', the coordinates are relative to the top left corner of
          the character glyph clicked on.

    WIDTH, HEIGHT
          These are the pixel width and height of OBJECT or, if this is
          `nil', those of the character glyph clicked on.


     For mouse clicks on a scroll-bar, POSITION has this form:

          (WINDOW AREA (PORTION . WHOLE) TIMESTAMP PART)

    WINDOW
          This is the window whose scroll-bar was clicked on.

    AREA
          This is the scroll bar where the click occurred.  It is one
          of the symbols `vertical-scroll-bar' or
          `horizontal-scroll-bar'.

    PORTION
          This is the distance of the click from the top or left end of
          the scroll bar.

    WHOLE
          This is the length of the entire scroll bar.

    TIMESTAMP
          This is the time at which the event occurred, in milliseconds.

    PART
          This is the part of the scroll-bar which was clicked on.  It
          is one of the symbols `above-handle', `handle',
          `below-handle', `up', `down', `top', `bottom', and
          `end-scroll'.

CLICK-COUNT
     This is the number of rapid repeated presses so far of the same
     mouse button.  *Note Repeat Events::.

File: elisp,  Node: Drag Events,  Next: Button-Down Events,  Prev: Click Events,  Up: Input Events

21.7.5 Drag Events
------------------

With Emacs, you can have a drag event without even changing your
clothes.  A "drag event" happens every time the user presses a mouse
button and then moves the mouse to a different character position before
releasing the button.  Like all mouse events, drag events are
represented in Lisp as lists.  The lists record both the starting mouse
position and the final position, like this:

     (EVENT-TYPE
      (WINDOW1 START-POSITION)
      (WINDOW2 END-POSITION))

   For a drag event, the name of the symbol EVENT-TYPE contains the
prefix `drag-'.  For example, dragging the mouse with button 2 held
down generates a `drag-mouse-2' event.  The second and third elements
of the event give the starting and ending position of the drag.  They
have the same form as POSITION in a click event (*note Click Events::)
that is not on the scroll bar part of the window.  You can access the
second element of any mouse event in the same way, with no need to
distinguish drag events from others.

   The `drag-' prefix follows the modifier key prefixes such as `C-'
and `M-'.

   If `read-key-sequence' receives a drag event that has no key
binding, and the corresponding click event does have a binding, it
changes the drag event into a click event at the drag's starting
position.  This means that you don't have to distinguish between click
and drag events unless you want to.

File: elisp,  Node: Button-Down Events,  Next: Repeat Events,  Prev: Drag Events,  Up: Input Events

21.7.6 Button-Down Events
-------------------------

Click and drag events happen when the user releases a mouse button.
They cannot happen earlier, because there is no way to distinguish a
click from a drag until the button is released.

   If you want to take action as soon as a button is pressed, you need
to handle "button-down" events.(1)  These occur as soon as a button is
pressed.  They are represented by lists that look exactly like click
events (*note Click Events::), except that the EVENT-TYPE symbol name
contains the prefix `down-'.  The `down-' prefix follows modifier key
prefixes such as `C-' and `M-'.

   The function `read-key-sequence' ignores any button-down events that
don't have command bindings; therefore, the Emacs command loop ignores
them too.  This means that you need not worry about defining
button-down events unless you want them to do something.  The usual
reason to define a button-down event is so that you can track mouse
motion (by reading motion events) until the button is released.  *Note
Motion Events::.

   ---------- Footnotes ----------

   (1) Button-down is the conservative antithesis of drag.

File: elisp,  Node: Repeat Events,  Next: Motion Events,  Prev: Button-Down Events,  Up: Input Events

21.7.7 Repeat Events
--------------------

If you press the same mouse button more than once in quick succession
without moving the mouse, Emacs generates special "repeat" mouse events
for the second and subsequent presses.

   The most common repeat events are "double-click" events.  Emacs
generates a double-click event when you click a button twice; the event
happens when you release the button (as is normal for all click events).

   The event type of a double-click event contains the prefix
`double-'.  Thus, a double click on the second mouse button with <meta>
held down comes to the Lisp program as `M-double-mouse-2'.  If a
double-click event has no binding, the binding of the corresponding
ordinary click event is used to execute it.  Thus, you need not pay
attention to the double click feature unless you really want to.

   When the user performs a double click, Emacs generates first an
ordinary click event, and then a double-click event.  Therefore, you
must design the command binding of the double click event to assume
that the single-click command has already run.  It must produce the
desired results of a double click, starting from the results of a
single click.

   This is convenient, if the meaning of a double click somehow "builds
on" the meaning of a single click--which is recommended user interface
design practice for double clicks.

   If you click a button, then press it down again and start moving the
mouse with the button held down, then you get a "double-drag" event
when you ultimately release the button.  Its event type contains
`double-drag' instead of just `drag'.  If a double-drag event has no
binding, Emacs looks for an alternate binding as if the event were an
ordinary drag.

   Before the double-click or double-drag event, Emacs generates a
"double-down" event when the user presses the button down for the
second time.  Its event type contains `double-down' instead of just
`down'.  If a double-down event has no binding, Emacs looks for an
alternate binding as if the event were an ordinary button-down event.
If it finds no binding that way either, the double-down event is
ignored.

   To summarize, when you click a button and then press it again right
away, Emacs generates a down event and a click event for the first
click, a double-down event when you press the button again, and finally
either a double-click or a double-drag event.

   If you click a button twice and then press it again, all in quick
succession, Emacs generates a "triple-down" event, followed by either a
"triple-click" or a "triple-drag".  The event types of these events
contain `triple' instead of `double'.  If any triple event has no
binding, Emacs uses the binding that it would use for the corresponding
double event.

   If you click a button three or more times and then press it again,
the events for the presses beyond the third are all triple events.
Emacs does not have separate event types for quadruple, quintuple, etc.
events.  However, you can look at the event list to find out precisely
how many times the button was pressed.

 -- Function: event-click-count event
     This function returns the number of consecutive button presses
     that led up to EVENT.  If EVENT is a double-down, double-click or
     double-drag event, the value is 2.  If EVENT is a triple event,
     the value is 3 or greater.  If EVENT is an ordinary mouse event
     (not a repeat event), the value is 1.

 -- User Option: double-click-fuzz
     To generate repeat events, successive mouse button presses must be
     at approximately the same screen position.  The value of
     `double-click-fuzz' specifies the maximum number of pixels the
     mouse may be moved (horizontally or vertically) between two
     successive clicks to make a double-click.

     This variable is also the threshold for motion of the mouse to
     count as a drag.

 -- User Option: double-click-time
     To generate repeat events, the number of milliseconds between
     successive button presses must be less than the value of
     `double-click-time'.  Setting `double-click-time' to `nil'
     disables multi-click detection entirely.  Setting it to `t'
     removes the time limit; Emacs then detects multi-clicks by
     position only.

File: elisp,  Node: Motion Events,  Next: Focus Events,  Prev: Repeat Events,  Up: Input Events

21.7.8 Motion Events
--------------------

Emacs sometimes generates "mouse motion" events to describe motion of
the mouse without any button activity.  Mouse motion events are
represented by lists that look like this:

     (mouse-movement (POSITION))

   The second element of the list describes the current position of the
mouse, just as in a click event (*note Click Events::).

   The special form `track-mouse' enables generation of motion events
within its body.  Outside of `track-mouse' forms, Emacs does not
generate events for mere motion of the mouse, and these events do not
appear.  *Note Mouse Tracking::.

File: elisp,  Node: Focus Events,  Next: Misc Events,  Prev: Motion Events,  Up: Input Events

21.7.9 Focus Events
-------------------

Window systems provide general ways for the user to control which window
gets keyboard input.  This choice of window is called the "focus".
When the user does something to switch between Emacs frames, that
generates a "focus event".  The normal definition of a focus event, in
the global keymap, is to select a new frame within Emacs, as the user
would expect.  *Note Input Focus::.

   Focus events are represented in Lisp as lists that look like this:

     (switch-frame NEW-FRAME)

where NEW-FRAME is the frame switched to.

   Some X window managers are set up so that just moving the mouse into
a window is enough to set the focus there.  Usually, there is no need
for a Lisp program to know about the focus change until some other kind
of input arrives.  Emacs generates a focus event only when the user
actually types a keyboard key or presses a mouse button in the new
frame; just moving the mouse between frames does not generate a focus
event.

   A focus event in the middle of a key sequence would garble the
sequence.  So Emacs never generates a focus event in the middle of a key
sequence.  If the user changes focus in the middle of a key
sequence--that is, after a prefix key--then Emacs reorders the events
so that the focus event comes either before or after the multi-event key
sequence, and not within it.

File: elisp,  Node: Misc Events,  Next: Event Examples,  Prev: Focus Events,  Up: Input Events

21.7.10 Miscellaneous System Events
-----------------------------------

A few other event types represent occurrences within the system.

`(delete-frame (FRAME))'
     This kind of event indicates that the user gave the window manager
     a command to delete a particular window, which happens to be an
     Emacs frame.

     The standard definition of the `delete-frame' event is to delete
     FRAME.

`(iconify-frame (FRAME))'
     This kind of event indicates that the user iconified FRAME using
     the window manager.  Its standard definition is `ignore'; since the
     frame has already been iconified, Emacs has no work to do.  The
     purpose of this event type is so that you can keep track of such
     events if you want to.

`(make-frame-visible (FRAME))'
     This kind of event indicates that the user deiconified FRAME using
     the window manager.  Its standard definition is `ignore'; since the
     frame has already been made visible, Emacs has no work to do.

`(wheel-up POSITION)'

`(wheel-down POSITION)'
     These kinds of event are generated by moving a mouse wheel.  Their
     usual meaning is a kind of scroll or zoom.

     The element POSITION is a list describing the position of the
     event, in the same format as used in a mouse-click event.

     This kind of event is generated only on some kinds of systems. On
     some systems, `mouse-4' and `mouse-5' are used instead.  For
     portable code, use the variables `mouse-wheel-up-event' and
     `mouse-wheel-down-event' defined in `mwheel.el' to determine what
     event types to expect for the mouse wheel.

`(drag-n-drop POSITION FILES)'
     This kind of event is generated when a group of files is selected
     in an application outside of Emacs, and then dragged and dropped
     onto an Emacs frame.

     The element POSITION is a list describing the position of the
     event, in the same format as used in a mouse-click event, and
     FILES is the list of file names that were dragged and dropped.
     The usual way to handle this event is by visiting these files.

     This kind of event is generated, at present, only on some kinds of
     systems.

`help-echo'
     This kind of event is generated when a mouse pointer moves onto a
     portion of buffer text which has a `help-echo' text property.  The
     generated event has this form:

          (help-echo FRAME HELP WINDOW OBJECT POS)

     The precise meaning of the event parameters and the way these
     parameters are used to display the help-echo text are described in
     *note Text help-echo::.

`sigusr1'
`sigusr2'
     These events are generated when the Emacs process receives the
     signals `SIGUSR1' and `SIGUSR2'.  They contain no additional data
     because signals do not carry additional information.

     To catch a user signal, bind the corresponding event to an
     interactive command in the `special-event-map' (*note Active
     Keymaps::).  The command is called with no arguments, and the
     specific signal event is available in `last-input-event'.  For
     example:

          (defun sigusr-handler ()
            (interactive)
            (message "Caught signal %S" last-input-event))

          (define-key special-event-map [sigusr1] 'sigusr-handler)

     To test the signal handler, you can make Emacs send a signal to
     itself:

          (signal-process (emacs-pid) 'sigusr1)

   If one of these events arrives in the middle of a key sequence--that
is, after a prefix key--then Emacs reorders the events so that this
event comes either before or after the multi-event key sequence, not
within it.

File: elisp,  Node: Event Examples,  Next: Classifying Events,  Prev: Misc Events,  Up: Input Events

21.7.11 Event Examples
----------------------

If the user presses and releases the left mouse button over the same
location, that generates a sequence of events like this:

     (down-mouse-1 (#<window 18 on NEWS> 2613 (0 . 38) -864320))
     (mouse-1      (#<window 18 on NEWS> 2613 (0 . 38) -864180))

   While holding the control key down, the user might hold down the
second mouse button, and drag the mouse from one line to the next.
That produces two events, as shown here:

     (C-down-mouse-2 (#<window 18 on NEWS> 3440 (0 . 27) -731219))
     (C-drag-mouse-2 (#<window 18 on NEWS> 3440 (0 . 27) -731219)
                     (#<window 18 on NEWS> 3510 (0 . 28) -729648))

   While holding down the meta and shift keys, the user might press the
second mouse button on the window's mode line, and then drag the mouse
into another window.  That produces a pair of events like these:

     (M-S-down-mouse-2 (#<window 18 on NEWS> mode-line (33 . 31) -457844))
     (M-S-drag-mouse-2 (#<window 18 on NEWS> mode-line (33 . 31) -457844)
                       (#<window 20 on carlton-sanskrit.tex> 161 (33 . 3)
                        -453816))

   To handle a SIGUSR1 signal, define an interactive function, and bind
it to the `signal usr1' event sequence:

     (defun usr1-handler ()
       (interactive)
       (message "Got USR1 signal"))
     (global-set-key [signal usr1] 'usr1-handler)

File: elisp,  Node: Classifying Events,  Next: Accessing Mouse,  Prev: Event Examples,  Up: Input Events

21.7.12 Classifying Events
--------------------------

Every event has an "event type", which classifies the event for key
binding purposes.  For a keyboard event, the event type equals the
event value; thus, the event type for a character is the character, and
the event type for a function key symbol is the symbol itself.  For
events that are lists, the event type is the symbol in the CAR of the
list.  Thus, the event type is always a symbol or a character.

   Two events of the same type are equivalent where key bindings are
concerned; thus, they always run the same command.  That does not
necessarily mean they do the same things, however, as some commands look
at the whole event to decide what to do.  For example, some commands use
the location of a mouse event to decide where in the buffer to act.

   Sometimes broader classifications of events are useful.  For example,
you might want to ask whether an event involved the <META> key,
regardless of which other key or mouse button was used.

   The functions `event-modifiers' and `event-basic-type' are provided
to get such information conveniently.

 -- Function: event-modifiers event
     This function returns a list of the modifiers that EVENT has.  The
     modifiers are symbols; they include `shift', `control', `meta',
     `alt', `hyper' and `super'.  In addition, the modifiers list of a
     mouse event symbol always contains one of `click', `drag', and
     `down'.  For double or triple events, it also contains `double' or
     `triple'.

     The argument EVENT may be an entire event object, or just an event
     type.  If EVENT is a symbol that has never been used in an event
     that has been read as input in the current Emacs session, then
     `event-modifiers' can return `nil', even when EVENT actually has
     modifiers.

     Here are some examples:

          (event-modifiers ?a)
               => nil
          (event-modifiers ?A)
               => (shift)
          (event-modifiers ?\C-a)
               => (control)
          (event-modifiers ?\C-%)
               => (control)
          (event-modifiers ?\C-\S-a)
               => (control shift)
          (event-modifiers 'f5)
               => nil
          (event-modifiers 's-f5)
               => (super)
          (event-modifiers 'M-S-f5)
               => (meta shift)
          (event-modifiers 'mouse-1)
               => (click)
          (event-modifiers 'down-mouse-1)
               => (down)

     The modifiers list for a click event explicitly contains `click',
     but the event symbol name itself does not contain `click'.

 -- Function: event-basic-type event
     This function returns the key or mouse button that EVENT
     describes, with all modifiers removed.  The EVENT argument is as
     in `event-modifiers'.  For example:

          (event-basic-type ?a)
               => 97
          (event-basic-type ?A)
               => 97
          (event-basic-type ?\C-a)
               => 97
          (event-basic-type ?\C-\S-a)
               => 97
          (event-basic-type 'f5)
               => f5
          (event-basic-type 's-f5)
               => f5
          (event-basic-type 'M-S-f5)
               => f5
          (event-basic-type 'down-mouse-1)
               => mouse-1

 -- Function: mouse-movement-p object
     This function returns non-`nil' if OBJECT is a mouse movement
     event.

 -- Function: event-convert-list list
     This function converts a list of modifier names and a basic event
     type to an event type which specifies all of them.  The basic
     event type must be the last element of the list.  For example,

          (event-convert-list '(control ?a))
               => 1
          (event-convert-list '(control meta ?a))
               => -134217727
          (event-convert-list '(control super f1))
               => C-s-f1

File: elisp,  Node: Accessing Mouse,  Next: Accessing Scroll,  Prev: Classifying Events,  Up: Input Events

21.7.13 Accessing Mouse Events
------------------------------

This section describes convenient functions for accessing the data in a
mouse button or motion event.

   These two functions return the starting or ending position of a
mouse-button event, as a list of this form:

     (WINDOW POS-OR-AREA (X . Y) TIMESTAMP
      OBJECT TEXT-POS (COL . ROW)
      IMAGE (DX . DY) (WIDTH . HEIGHT))

 -- Function: event-start event
     This returns the starting position of EVENT.

     If EVENT is a click or button-down event, this returns the
     location of the event.  If EVENT is a drag event, this returns the
     drag's starting position.

 -- Function: event-end event
     This returns the ending position of EVENT.

     If EVENT is a drag event, this returns the position where the user
     released the mouse button.  If EVENT is a click or button-down
     event, the value is actually the starting position, which is the
     only position such events have.

   These functions take a position list as described above, and return
various parts of it.

 -- Function: posn-window position
     Return the window that POSITION is in.

 -- Function: posn-area position
     Return the window area recorded in POSITION.  It returns `nil'
     when the event occurred in the text area of the window; otherwise,
     it is a symbol identifying the area in which the event occurred.

 -- Function: posn-point position
     Return the buffer position in POSITION.  When the event occurred
     in the text area of the window, in a marginal area, or on a fringe,
     this is an integer specifying a buffer position.  Otherwise, the
     value is undefined.

 -- Function: posn-x-y position
     Return the pixel-based x and y coordinates in POSITION, as a cons
     cell `(X . Y)'.  These coordinates are relative to the window
     given by `posn-window'.

     This example shows how to convert these window-relative coordinates
     into frame-relative coordinates:

          (defun frame-relative-coordinates (position)
            "Return frame-relative coordinates from POSITION."
            (let* ((x-y (posn-x-y position))
                   (window (posn-window position))
                   (edges (window-inside-pixel-edges window)))
              (cons (+ (car x-y) (car edges))
                    (+ (cdr x-y) (cadr edges)))))

 -- Function: posn-col-row position
     Return the row and column (in units of the frame's default
     character height and width) of POSITION, as a cons cell `(COL .
     ROW)'.  These are computed from the X and Y values actually found
     in POSITION.

 -- Function: posn-actual-col-row position
     Return the actual row and column in POSITION, as a cons cell `(COL
     . ROW)'.  The values are the actual row number in the window, and
     the actual character number in that row.  It returns `nil' if
     POSITION does not include actual positions values.  You can use
     `posn-col-row' to get approximate values.

 -- Function: posn-string position
     Return the string object in POSITION, either `nil', or a cons cell
     `(STRING . STRING-POS)'.

 -- Function: posn-image position
     Return the image object in POSITION, either `nil', or an image
     `(image ...)'.

 -- Function: posn-object position
     Return the image or string object in POSITION, either `nil', an
     image `(image ...)', or a cons cell `(STRING . STRING-POS)'.

 -- Function: posn-object-x-y position
     Return the pixel-based x and y coordinates relative to the upper
     left corner of the object in POSITION as a cons cell `(DX . DY)'.
     If the POSITION is a buffer position, return the relative position
     in the character at that position.

 -- Function: posn-object-width-height position
     Return the pixel width and height of the object in POSITION as a
     cons cell `(WIDTH . HEIGHT)'.  If the POSITION is a buffer
     position, return the size of the character at that position.

 -- Function: posn-timestamp position
     Return the timestamp in POSITION.  This is the time at which the
     event occurred, in milliseconds.

   These functions compute a position list given particular buffer
position or screen position.  You can access the data in this position
list with the functions described above.

 -- Function: posn-at-point &optional pos window
     This function returns a position list for position POS in WINDOW.
     POS defaults to point in WINDOW; WINDOW defaults to the selected
     window.

     `posn-at-point' returns `nil' if POS is not visible in WINDOW.

 -- Function: posn-at-x-y x y &optional frame-or-window whole
     This function returns position information corresponding to pixel
     coordinates X and Y in a specified frame or window,
     FRAME-OR-WINDOW, which defaults to the selected window.  The
     coordinates X and Y are relative to the frame or window used.  If
     WHOLE is `nil', the coordinates are relative to the window text
     area, otherwise they are relative to the entire window area
     including scroll bars, margins and fringes.

File: elisp,  Node: Accessing Scroll,  Next: Strings of Events,  Prev: Accessing Mouse,  Up: Input Events

21.7.14 Accessing Scroll Bar Events
-----------------------------------

These functions are useful for decoding scroll bar events.

 -- Function: scroll-bar-event-ratio event
     This function returns the fractional vertical position of a scroll
     bar event within the scroll bar.  The value is a cons cell
     `(PORTION . WHOLE)' containing two integers whose ratio is the
     fractional position.

 -- Function: scroll-bar-scale ratio total
     This function multiplies (in effect) RATIO by TOTAL, rounding the
     result to an integer.  The argument RATIO is not a number, but
     rather a pair `(NUM . DENOM)'--typically a value returned by
     `scroll-bar-event-ratio'.

     This function is handy for scaling a position on a scroll bar into
     a buffer position.  Here's how to do that:

          (+ (point-min)
             (scroll-bar-scale
                (posn-x-y (event-start event))
                (- (point-max) (point-min))))

     Recall that scroll bar events have two integers forming a ratio,
     in place of a pair of x and y coordinates.

File: elisp,  Node: Strings of Events,  Prev: Accessing Scroll,  Up: Input Events

21.7.15 Putting Keyboard Events in Strings
------------------------------------------

In most of the places where strings are used, we conceptualize the
string as containing text characters--the same kind of characters found
in buffers or files.  Occasionally Lisp programs use strings that
conceptually contain keyboard characters; for example, they may be key
sequences or keyboard macro definitions.  However, storing keyboard
characters in a string is a complex matter, for reasons of historical
compatibility, and it is not always possible.

   We recommend that new programs avoid dealing with these complexities
by not storing keyboard events in strings.  Here is how to do that:

   * Use vectors instead of strings for key sequences, when you plan to
     use them for anything other than as arguments to `lookup-key' and
     `define-key'.  For example, you can use `read-key-sequence-vector'
     instead of `read-key-sequence', and `this-command-keys-vector'
     instead of `this-command-keys'.

   * Use vectors to write key sequence constants containing meta
     characters, even when passing them directly to `define-key'.

   * When you have to look at the contents of a key sequence that might
     be a string, use `listify-key-sequence' (*note Event Input Misc::)
     first, to convert it to a list.

   The complexities stem from the modifier bits that keyboard input
characters can include.  Aside from the Meta modifier, none of these
modifier bits can be included in a string, and the Meta modifier is
allowed only in special cases.

   The earliest GNU Emacs versions represented meta characters as codes
in the range of 128 to 255.  At that time, the basic character codes
ranged from 0 to 127, so all keyboard character codes did fit in a
string.  Many Lisp programs used `\M-' in string constants to stand for
meta characters, especially in arguments to `define-key' and similar
functions, and key sequences and sequences of events were always
represented as strings.

   When we added support for larger basic character codes beyond 127,
and additional modifier bits, we had to change the representation of
meta characters.  Now the flag that represents the Meta modifier in a
character is 2**27 and such numbers cannot be included in a string.

   To support programs with `\M-' in string constants, there are
special rules for including certain meta characters in a string.  Here
are the rules for interpreting a string as a sequence of input
characters:

   * If the keyboard character value is in the range of 0 to 127, it
     can go in the string unchanged.

   * The meta variants of those characters, with codes in the range of
     2**27 to 2**27+127, can also go in the string, but you must change
     their numeric values.  You must set the 2**7 bit instead of the
     2**27 bit, resulting in a value between 128 and 255.  Only a
     unibyte string can include these codes.

   * Non-ASCII characters above 256 can be included in a multibyte
     string.

   * Other keyboard character events cannot fit in a string.  This
     includes keyboard events in the range of 128 to 255.

   Functions such as `read-key-sequence' that construct strings of
keyboard input characters follow these rules: they construct vectors
instead of strings, when the events won't fit in a string.

   When you use the read syntax `\M-' in a string, it produces a code
in the range of 128 to 255--the same code that you get if you modify
the corresponding keyboard event to put it in the string.  Thus, meta
events in strings work consistently regardless of how they get into the
strings.

   However, most programs would do well to avoid these issues by
following the recommendations at the beginning of this section.

File: elisp,  Node: Reading Input,  Next: Special Events,  Prev: Input Events,  Up: Command Loop

21.8 Reading Input
==================

The editor command loop reads key sequences using the function
`read-key-sequence', which uses `read-event'.  These and other
functions for event input are also available for use in Lisp programs.
See also `momentary-string-display' in *note Temporary Displays::, and
`sit-for' in *note Waiting::.  *Note Terminal Input::, for functions
and variables for controlling terminal input modes and debugging
terminal input.

   For higher-level input facilities, see *note Minibuffers::.

* Menu:

* Key Sequence Input::		How to read one key sequence.
* Reading One Event::		How to read just one event.
* Event Mod::                   How Emacs modifies events as they are read.
* Invoking the Input Method::   How reading an event uses the input method.
* Quoted Character Input::	Asking the user to specify a character.
* Event Input Misc::    	How to reread or throw away input events.

File: elisp,  Node: Key Sequence Input,  Next: Reading One Event,  Up: Reading Input

21.8.1 Key Sequence Input
-------------------------

The command loop reads input a key sequence at a time, by calling
`read-key-sequence'.  Lisp programs can also call this function; for
example, `describe-key' uses it to read the key to describe.

 -- Function: read-key-sequence prompt &optional continue-echo
          dont-downcase-last switch-frame-ok command-loop
     This function reads a key sequence and returns it as a string or
     vector.  It keeps reading events until it has accumulated a
     complete key sequence; that is, enough to specify a non-prefix
     command using the currently active keymaps.  (Remember that a key
     sequence that starts with a mouse event is read using the keymaps
     of the buffer in the window that the mouse was in, not the current
     buffer.)

     If the events are all characters and all can fit in a string, then
     `read-key-sequence' returns a string (*note Strings of Events::).
     Otherwise, it returns a vector, since a vector can hold all kinds
     of events--characters, symbols, and lists.  The elements of the
     string or vector are the events in the key sequence.

     Reading a key sequence includes translating the events in various
     ways.  *Note Translation Keymaps::.

     The argument PROMPT is either a string to be displayed in the echo
     area as a prompt, or `nil', meaning not to display a prompt.  The
     argument CONTINUE-ECHO, if non-`nil', means to echo this key as a
     continuation of the previous key.

     Normally any upper case event is converted to lower case if the
     original event is undefined and the lower case equivalent is
     defined.  The argument DONT-DOWNCASE-LAST, if non-`nil', means do
     not convert the last event to lower case.  This is appropriate for
     reading a key sequence to be defined.

     The argument SWITCH-FRAME-OK, if non-`nil', means that this
     function should process a `switch-frame' event if the user
     switches frames before typing anything.  If the user switches
     frames in the middle of a key sequence, or at the start of the
     sequence but SWITCH-FRAME-OK is `nil', then the event will be put
     off until after the current key sequence.

     The argument COMMAND-LOOP, if non-`nil', means that this key
     sequence is being read by something that will read commands one
     after another.  It should be `nil' if the caller will read just
     one key sequence.

     In the following example, Emacs displays the prompt `?' in the
     echo area, and then the user types `C-x C-f'.

          (read-key-sequence "?")

          ---------- Echo Area ----------
          ?C-x C-f
          ---------- Echo Area ----------

               => "^X^F"

     The function `read-key-sequence' suppresses quitting: `C-g' typed
     while reading with this function works like any other character,
     and does not set `quit-flag'.  *Note Quitting::.

 -- Function: read-key-sequence-vector prompt &optional continue-echo
          dont-downcase-last switch-frame-ok command-loop
     This is like `read-key-sequence' except that it always returns the
     key sequence as a vector, never as a string.  *Note Strings of
     Events::.

   If an input character is upper-case (or has the shift modifier) and
has no key binding, but its lower-case equivalent has one, then
`read-key-sequence' converts the character to lower case.  Note that
`lookup-key' does not perform case conversion in this way.

   When reading input results in such a "shift-translation", Emacs sets
the variable `this-command-keys-shift-translated' to a non-`nil' value.
Lisp programs can examine this variable if they need to modify their
behavior when invoked by shift-translated keys.  For example, the
function `handle-shift-selection' examines the value of this variable
to determine how to activate or deactivate the region (*note
handle-shift-selection: The Mark.).

   The function `read-key-sequence' also transforms some mouse events.
It converts unbound drag events into click events, and discards unbound
button-down events entirely.  It also reshuffles focus events and
miscellaneous window events so that they never appear in a key sequence
with any other events.

   When mouse events occur in special parts of a window, such as a mode
line or a scroll bar, the event type shows nothing special--it is the
same symbol that would normally represent that combination of mouse
button and modifier keys.  The information about the window part is kept
elsewhere in the event--in the coordinates.  But `read-key-sequence'
translates this information into imaginary "prefix keys," all of which
are symbols: `header-line', `horizontal-scroll-bar', `menu-bar',
`mode-line', `vertical-line', and `vertical-scroll-bar'.  You can define
meanings for mouse clicks in special window parts by defining key
sequences using these imaginary prefix keys.

   For example, if you call `read-key-sequence' and then click the
mouse on the window's mode line, you get two events, like this:

     (read-key-sequence "Click on the mode line: ")
          => [mode-line
              (mouse-1
               (#<window 6 on NEWS> mode-line
                (40 . 63) 5959987))]

 -- Variable: num-input-keys
     This variable's value is the number of key sequences processed so
     far in this Emacs session.  This includes key sequences read from
     the terminal and key sequences read from keyboard macros being
     executed.

File: elisp,  Node: Reading One Event,  Next: Event Mod,  Prev: Key Sequence Input,  Up: Reading Input

21.8.2 Reading One Event
------------------------

The lowest level functions for command input are those that read a
single event.

   None of the three functions below suppresses quitting.

 -- Function: read-event &optional prompt inherit-input-method seconds
     This function reads and returns the next event of command input,
     waiting if necessary until an event is available.  Events can come
     directly from the user or from a keyboard macro.

     If the optional argument PROMPT is non-`nil', it should be a
     string to display in the echo area as a prompt.  Otherwise,
     `read-event' does not display any message to indicate it is waiting
     for input; instead, it prompts by echoing: it displays
     descriptions of the events that led to or were read by the current
     command.  *Note The Echo Area::.

     If INHERIT-INPUT-METHOD is non-`nil', then the current input
     method (if any) is employed to make it possible to enter a
     non-ASCII character.  Otherwise, input method handling is disabled
     for reading this event.

     If `cursor-in-echo-area' is non-`nil', then `read-event' moves the
     cursor temporarily to the echo area, to the end of any message
     displayed there.  Otherwise `read-event' does not move the cursor.

     If SECONDS is non-`nil', it should be a number specifying the
     maximum time to wait for input, in seconds.  If no input arrives
     within that time, `read-event' stops waiting and returns `nil'.  A
     floating-point value for SECONDS means to wait for a fractional
     number of seconds.  Some systems support only a whole number of
     seconds; on these systems, SECONDS is rounded down.  If SECONDS is
     `nil', `read-event' waits as long as necessary for input to arrive.

     If SECONDS is `nil', Emacs is considered idle while waiting for
     user input to arrive.  Idle timers--those created with
     `run-with-idle-timer' (*note Idle Timers::)--can run during this
     period.  However, if SECONDS is non-`nil', the state of idleness
     remains unchanged.  If Emacs is non-idle when `read-event' is
     called, it remains non-idle throughout the operation of
     `read-event'; if Emacs is idle (which can happen if the call
     happens inside an idle timer), it remains idle.

     If `read-event' gets an event that is defined as a help character,
     then in some cases `read-event' processes the event directly
     without returning.  *Note Help Functions::.  Certain other events,
     called "special events", are also processed directly within
     `read-event' (*note Special Events::).

     Here is what happens if you call `read-event' and then press the
     right-arrow function key:

          (read-event)
               => right

 -- Function: read-char &optional prompt inherit-input-method seconds
     This function reads and returns a character of command input.  If
     the user generates an event which is not a character (i.e. a mouse
     click or function key event), `read-char' signals an error.  The
     arguments work as in `read-event'.

     In the first example, the user types the character `1' (ASCII code
     49).  The second example shows a keyboard macro definition that
     calls `read-char' from the minibuffer using `eval-expression'.
     `read-char' reads the keyboard macro's very next character, which
     is `1'.  Then `eval-expression' displays its return value in the
     echo area.

          (read-char)
               => 49

          ;; We assume here you use `M-:' to evaluate this.
          (symbol-function 'foo)
               => "^[:(read-char)^M1"
          (execute-kbd-macro 'foo)
               -| 49
               => nil

 -- Function: read-char-exclusive &optional prompt inherit-input-method
          seconds
     This function reads and returns a character of command input.  If
     the user generates an event which is not a character,
     `read-char-exclusive' ignores it and reads another event, until it
     gets a character.  The arguments work as in `read-event'.

 -- Variable: num-nonmacro-input-events
     This variable holds the total number of input events received so
     far from the terminal--not counting those generated by keyboard
     macros.

File: elisp,  Node: Event Mod,  Next: Invoking the Input Method,  Prev: Reading One Event,  Up: Reading Input

21.8.3 Modifying and Translating Input Events
---------------------------------------------

Emacs modifies every event it reads according to
`extra-keyboard-modifiers', then translates it through
`keyboard-translate-table' (if applicable), before returning it from
`read-event'.

 -- Variable: extra-keyboard-modifiers
     This variable lets Lisp programs "press" the modifier keys on the
     keyboard.  The value is a character.  Only the modifiers of the
     character matter.  Each time the user types a keyboard key, it is
     altered as if those modifier keys were held down.  For instance, if
     you bind `extra-keyboard-modifiers' to `?\C-\M-a', then all
     keyboard input characters typed during the scope of the binding
     will have the control and meta modifiers applied to them.  The
     character `?\C-@', equivalent to the integer 0, does not count as
     a control character for this purpose, but as a character with no
     modifiers.  Thus, setting `extra-keyboard-modifiers' to zero
     cancels any modification.

     When using a window system, the program can "press" any of the
     modifier keys in this way.  Otherwise, only the <CTL> and <META>
     keys can be virtually pressed.

     Note that this variable applies only to events that really come
     from the keyboard, and has no effect on mouse events or any other
     events.

 -- Variable: keyboard-translate-table
     This terminal-local variable is the translate table for keyboard
     characters.  It lets you reshuffle the keys on the keyboard without
     changing any command bindings.  Its value is normally a
     char-table, or else `nil'.  (It can also be a string or vector,
     but this is considered obsolete.)

     If `keyboard-translate-table' is a char-table (*note
     Char-Tables::), then each character read from the keyboard is
     looked up in this char-table.  If the value found there is
     non-`nil', then it is used instead of the actual input character.

     Note that this translation is the first thing that happens to a
     character after it is read from the terminal.  Record-keeping
     features such as `recent-keys' and dribble files record the
     characters after translation.

     Note also that this translation is done before the characters are
     supplied to input methods (*note Input Methods::).  Use
     `translation-table-for-input' (*note Translation of Characters::),
     if you want to translate characters after input methods operate.

 -- Function: keyboard-translate from to
     This function modifies `keyboard-translate-table' to translate
     character code FROM into character code TO.  It creates the
     keyboard translate table if necessary.

   Here's an example of using the `keyboard-translate-table' to make
`C-x', `C-c' and `C-v' perform the cut, copy and paste operations:

     (keyboard-translate ?\C-x 'control-x)
     (keyboard-translate ?\C-c 'control-c)
     (keyboard-translate ?\C-v 'control-v)
     (global-set-key [control-x] 'kill-region)
     (global-set-key [control-c] 'kill-ring-save)
     (global-set-key [control-v] 'yank)

On a graphical terminal that supports extended ASCII input, you can
still get the standard Emacs meanings of one of those characters by
typing it with the shift key.  That makes it a different character as
far as keyboard translation is concerned, but it has the same usual
meaning.

   *Note Translation Keymaps::, for mechanisms that translate event
sequences at the level of `read-key-sequence'.

File: elisp,  Node: Invoking the Input Method,  Next: Quoted Character Input,  Prev: Event Mod,  Up: Reading Input

21.8.4 Invoking the Input Method
--------------------------------

The event-reading functions invoke the current input method, if any
(*note Input Methods::).  If the value of `input-method-function' is
non-`nil', it should be a function; when `read-event' reads a printing
character (including <SPC>) with no modifier bits, it calls that
function, passing the character as an argument.

 -- Variable: input-method-function
     If this is non-`nil', its value specifies the current input method
     function.

     *Warning:* don't bind this variable with `let'.  It is often
     buffer-local, and if you bind it around reading input (which is
     exactly when you _would_ bind it), switching buffers
     asynchronously while Emacs is waiting will cause the value to be
     restored in the wrong buffer.

   The input method function should return a list of events which should
be used as input.  (If the list is `nil', that means there is no input,
so `read-event' waits for another event.)  These events are processed
before the events in `unread-command-events' (*note Event Input
Misc::).  Events returned by the input method function are not passed
to the input method function again, even if they are printing
characters with no modifier bits.

   If the input method function calls `read-event' or
`read-key-sequence', it should bind `input-method-function' to `nil'
first, to prevent recursion.

   The input method function is not called when reading the second and
subsequent events of a key sequence.  Thus, these characters are not
subject to input method processing.  The input method function should
test the values of `overriding-local-map' and
`overriding-terminal-local-map'; if either of these variables is
non-`nil', the input method should put its argument into a list and
return that list with no further processing.

File: elisp,  Node: Quoted Character Input,  Next: Event Input Misc,  Prev: Invoking the Input Method,  Up: Reading Input

21.8.5 Quoted Character Input
-----------------------------

You can use the function `read-quoted-char' to ask the user to specify
a character, and allow the user to specify a control or meta character
conveniently, either literally or as an octal character code.  The
command `quoted-insert' uses this function.

 -- Function: read-quoted-char &optional prompt
     This function is like `read-char', except that if the first
     character read is an octal digit (0-7), it reads any number of
     octal digits (but stopping if a non-octal digit is found), and
     returns the character represented by that numeric character code.
     If the character that terminates the sequence of octal digits is
     <RET>, it is discarded.  Any other terminating character is used
     as input after this function returns.

     Quitting is suppressed when the first character is read, so that
     the user can enter a `C-g'.  *Note Quitting::.

     If PROMPT is supplied, it specifies a string for prompting the
     user.  The prompt string is always displayed in the echo area,
     followed by a single `-'.

     In the following example, the user types in the octal number 177
     (which is 127 in decimal).

          (read-quoted-char "What character")

          ---------- Echo Area ----------
          What character 1 7 7-
          ---------- Echo Area ----------

               => 127

File: elisp,  Node: Event Input Misc,  Prev: Quoted Character Input,  Up: Reading Input

21.8.6 Miscellaneous Event Input Features
-----------------------------------------

This section describes how to "peek ahead" at events without using them
up, how to check for pending input, and how to discard pending input.
See also the function `read-passwd' (*note Reading a Password::).

 -- Variable: unread-command-events
     This variable holds a list of events waiting to be read as command
     input.  The events are used in the order they appear in the list,
     and removed one by one as they are used.

     The variable is needed because in some cases a function reads an
     event and then decides not to use it.  Storing the event in this
     variable causes it to be processed normally, by the command loop
     or by the functions to read command input.

     For example, the function that implements numeric prefix arguments
     reads any number of digits.  When it finds a non-digit event, it
     must unread the event so that it can be read normally by the
     command loop.  Likewise, incremental search uses this feature to
     unread events with no special meaning in a search, because these
     events should exit the search and then execute normally.

     The reliable and easy way to extract events from a key sequence so
     as to put them in `unread-command-events' is to use
     `listify-key-sequence' (*note Strings of Events::).

     Normally you add events to the front of this list, so that the
     events most recently unread will be reread first.

     Events read from this list are not normally added to the current
     command's key sequence (as returned by e.g. `this-command-keys'),
     as the events will already have been added once as they were read
     for the first time.  An element of the form `(`t' . EVENT)' forces
     EVENT to be added to the current command's key sequence.

 -- Function: listify-key-sequence key
     This function converts the string or vector KEY to a list of
     individual events, which you can put in `unread-command-events'.

 -- Variable: unread-command-char
     This variable holds a character to be read as command input.  A
     value of -1 means "empty."

     This variable is mostly obsolete now that you can use
     `unread-command-events' instead; it exists only to support programs
     written for Emacs versions 18 and earlier.

 -- Function: input-pending-p
     This function determines whether any command input is currently
     available to be read.  It returns immediately, with value `t' if
     there is available input, `nil' otherwise.  On rare occasions it
     may return `t' when no input is available.

 -- Variable: last-input-event
 -- Variable: last-input-char
     This variable records the last terminal input event read, whether
     as part of a command or explicitly by a Lisp program.

     In the example below, the Lisp program reads the character `1',
     ASCII code 49.  It becomes the value of `last-input-event', while
     `C-e' (we assume `C-x C-e' command is used to evaluate this
     expression) remains the value of `last-command-event'.

          (progn (print (read-char))
                 (print last-command-event)
                 last-input-event)
               -| 49
               -| 5
               => 49

     The alias `last-input-char' is obsolete.

 -- Macro: while-no-input body...
     This construct runs the BODY forms and returns the value of the
     last one--but only if no input arrives.  If any input arrives
     during the execution of the BODY forms, it aborts them (working
     much like a quit).  The `while-no-input' form returns `nil' if
     aborted by a real quit, and returns `t' if aborted by arrival of
     other input.

     If a part of BODY binds `inhibit-quit' to non-`nil', arrival of
     input during those parts won't cause an abort until the end of
     that part.

     If you want to be able to distinguish all possible values computed
     by BODY from both kinds of abort conditions, write the code like
     this:

          (while-no-input
            (list
              (progn . BODY)))

 -- Function: discard-input
     This function discards the contents of the terminal input buffer
     and cancels any keyboard macro that might be in the process of
     definition.  It returns `nil'.

     In the following example, the user may type a number of characters
     right after starting the evaluation of the form.  After the
     `sleep-for' finishes sleeping, `discard-input' discards any
     characters typed during the sleep.

          (progn (sleep-for 2)
                 (discard-input))
               => nil

File: elisp,  Node: Special Events,  Next: Waiting,  Prev: Reading Input,  Up: Command Loop

21.9 Special Events
===================

Special events are handled at a very low level--as soon as they are
read.  The `read-event' function processes these events itself, and
never returns them.  Instead, it keeps waiting for the first event that
is not special and returns that one.

   Events that are handled in this way do not echo, they are never
grouped into key sequences, and they never appear in the value of
`last-command-event' or `(this-command-keys)'.  They do not discard a
numeric argument, they cannot be unread with `unread-command-events',
they may not appear in a keyboard macro, and they are not recorded in a
keyboard macro while you are defining one.

   These events do, however, appear in `last-input-event' immediately
after they are read, and this is the way for the event's definition to
find the actual event.

   The events types `iconify-frame', `make-frame-visible',
`delete-frame', `drag-n-drop', and user signals like `sigusr1' are
normally handled in this way.  The keymap which defines how to handle
special events--and which events are special--is in the variable
`special-event-map' (*note Active Keymaps::).

File: elisp,  Node: Waiting,  Next: Quitting,  Prev: Special Events,  Up: Command Loop

21.10 Waiting for Elapsed Time or Input
=======================================

The wait functions are designed to wait for a certain amount of time to
pass or until there is input.  For example, you may wish to pause in
the middle of a computation to allow the user time to view the display.
`sit-for' pauses and updates the screen, and returns immediately if
input comes in, while `sleep-for' pauses without updating the screen.

 -- Function: sit-for seconds &optional nodisp
     This function performs redisplay (provided there is no pending
     input from the user), then waits SECONDS seconds, or until input is
     available.  The usual purpose of `sit-for' is to give the user
     time to read text that you display.  The value is `t' if `sit-for'
     waited the full time with no input arriving (*note Event Input
     Misc::).  Otherwise, the value is `nil'.

     The argument SECONDS need not be an integer.  If it is a floating
     point number, `sit-for' waits for a fractional number of seconds.
     Some systems support only a whole number of seconds; on these
     systems, SECONDS is rounded down.

     The expression `(sit-for 0)' is equivalent to `(redisplay)', i.e.
     it requests a redisplay, without any delay, if there is no pending
     input.  *Note Forcing Redisplay::.

     If NODISP is non-`nil', then `sit-for' does not redisplay, but it
     still returns as soon as input is available (or when the timeout
     elapses).

     In batch mode (*note Batch Mode::), `sit-for' cannot be
     interrupted, even by input from the standard input descriptor.  It
     is thus equivalent to `sleep-for', which is described below.

     It is also possible to call `sit-for' with three arguments, as
     `(sit-for SECONDS MILLISEC NODISP)', but that is considered
     obsolete.

 -- Function: sleep-for seconds &optional millisec
     This function simply pauses for SECONDS seconds without updating
     the display.  It pays no attention to available input.  It returns
     `nil'.

     The argument SECONDS need not be an integer.  If it is a floating
     point number, `sleep-for' waits for a fractional number of seconds.
     Some systems support only a whole number of seconds; on these
     systems, SECONDS is rounded down.

     The optional argument MILLISEC specifies an additional waiting
     period measured in milliseconds.  This adds to the period
     specified by SECONDS.  If the system doesn't support waiting
     fractions of a second, you get an error if you specify nonzero
     MILLISEC.

     Use `sleep-for' when you wish to guarantee a delay.

   *Note Time of Day::, for functions to get the current time.

File: elisp,  Node: Quitting,  Next: Prefix Command Arguments,  Prev: Waiting,  Up: Command Loop

21.11 Quitting
==============

Typing `C-g' while a Lisp function is running causes Emacs to "quit"
whatever it is doing.  This means that control returns to the innermost
active command loop.

   Typing `C-g' while the command loop is waiting for keyboard input
does not cause a quit; it acts as an ordinary input character.  In the
simplest case, you cannot tell the difference, because `C-g' normally
runs the command `keyboard-quit', whose effect is to quit.  However,
when `C-g' follows a prefix key, they combine to form an undefined key.
The effect is to cancel the prefix key as well as any prefix argument.

   In the minibuffer, `C-g' has a different definition: it aborts out
of the minibuffer.  This means, in effect, that it exits the minibuffer
and then quits.  (Simply quitting would return to the command loop
_within_ the minibuffer.)  The reason why `C-g' does not quit directly
when the command reader is reading input is so that its meaning can be
redefined in the minibuffer in this way.  `C-g' following a prefix key
is not redefined in the minibuffer, and it has its normal effect of
canceling the prefix key and prefix argument.  This too would not be
possible if `C-g' always quit directly.

   When `C-g' does directly quit, it does so by setting the variable
`quit-flag' to `t'.  Emacs checks this variable at appropriate times
and quits if it is not `nil'.  Setting `quit-flag' non-`nil' in any way
thus causes a quit.

   At the level of C code, quitting cannot happen just anywhere; only
at the special places that check `quit-flag'.  The reason for this is
that quitting at other places might leave an inconsistency in Emacs's
internal state.  Because quitting is delayed until a safe place,
quitting cannot make Emacs crash.

   Certain functions such as `read-key-sequence' or `read-quoted-char'
prevent quitting entirely even though they wait for input.  Instead of
quitting, `C-g' serves as the requested input.  In the case of
`read-key-sequence', this serves to bring about the special behavior of
`C-g' in the command loop.  In the case of `read-quoted-char', this is
so that `C-q' can be used to quote a `C-g'.

   You can prevent quitting for a portion of a Lisp function by binding
the variable `inhibit-quit' to a non-`nil' value.  Then, although `C-g'
still sets `quit-flag' to `t' as usual, the usual result of this--a
quit--is prevented.  Eventually, `inhibit-quit' will become `nil'
again, such as when its binding is unwound at the end of a `let' form.
At that time, if `quit-flag' is still non-`nil', the requested quit
happens immediately.  This behavior is ideal when you wish to make sure
that quitting does not happen within a "critical section" of the
program.

   In some functions (such as `read-quoted-char'), `C-g' is handled in
a special way that does not involve quitting.  This is done by reading
the input with `inhibit-quit' bound to `t', and setting `quit-flag' to
`nil' before `inhibit-quit' becomes `nil' again.  This excerpt from the
definition of `read-quoted-char' shows how this is done; it also shows
that normal quitting is permitted after the first character of input.

     (defun read-quoted-char (&optional prompt)
       "...DOCUMENTATION..."
       (let ((message-log-max nil) done (first t) (code 0) char)
         (while (not done)
           (let ((inhibit-quit first)
                 ...)
     	(and prompt (message "%s-" prompt))
     	(setq char (read-event))
     	(if inhibit-quit (setq quit-flag nil)))
           ...set the variable `code'...)
         code))

 -- Variable: quit-flag
     If this variable is non-`nil', then Emacs quits immediately, unless
     `inhibit-quit' is non-`nil'.  Typing `C-g' ordinarily sets
     `quit-flag' non-`nil', regardless of `inhibit-quit'.

 -- Variable: inhibit-quit
     This variable determines whether Emacs should quit when `quit-flag'
     is set to a value other than `nil'.  If `inhibit-quit' is
     non-`nil', then `quit-flag' has no special effect.

 -- Macro: with-local-quit body...
     This macro executes BODY forms in sequence, but allows quitting, at
     least locally, within BODY even if `inhibit-quit' was non-`nil'
     outside this construct.  It returns the value of the last form in
     BODY, unless exited by quitting, in which case it returns `nil'.

     If `inhibit-quit' is `nil' on entry to `with-local-quit', it only
     executes the BODY, and setting `quit-flag' causes a normal quit.
     However, if `inhibit-quit' is non-`nil' so that ordinary quitting
     is delayed, a non-`nil' `quit-flag' triggers a special kind of
     local quit.  This ends the execution of BODY and exits the
     `with-local-quit' body with `quit-flag' still non-`nil', so that
     another (ordinary) quit will happen as soon as that is allowed.
     If `quit-flag' is already non-`nil' at the beginning of BODY, the
     local quit happens immediately and the body doesn't execute at all.

     This macro is mainly useful in functions that can be called from
     timers, process filters, process sentinels, `pre-command-hook',
     `post-command-hook', and other places where `inhibit-quit' is
     normally bound to `t'.

 -- Command: keyboard-quit
     This function signals the `quit' condition with `(signal 'quit
     nil)'.  This is the same thing that quitting does.  (See `signal'
     in *note Errors::.)

   You can specify a character other than `C-g' to use for quitting.
See the function `set-input-mode' in *note Terminal Input::.

File: elisp,  Node: Prefix Command Arguments,  Next: Recursive Editing,  Prev: Quitting,  Up: Command Loop

21.12 Prefix Command Arguments
==============================

Most Emacs commands can use a "prefix argument", a number specified
before the command itself.  (Don't confuse prefix arguments with prefix
keys.)  The prefix argument is at all times represented by a value,
which may be `nil', meaning there is currently no prefix argument.
Each command may use the prefix argument or ignore it.

   There are two representations of the prefix argument: "raw" and
"numeric".  The editor command loop uses the raw representation
internally, and so do the Lisp variables that store the information, but
commands can request either representation.

   Here are the possible values of a raw prefix argument:

   * `nil', meaning there is no prefix argument.  Its numeric value is
     1, but numerous commands make a distinction between `nil' and the
     integer 1.

   * An integer, which stands for itself.

   * A list of one element, which is an integer.  This form of prefix
     argument results from one or a succession of `C-u''s with no
     digits.  The numeric value is the integer in the list, but some
     commands make a distinction between such a list and an integer
     alone.

   * The symbol `-'.  This indicates that `M--' or `C-u -' was typed,
     without following digits.  The equivalent numeric value is -1, but
     some commands make a distinction between the integer -1 and the
     symbol `-'.

   We illustrate these possibilities by calling the following function
with various prefixes:

     (defun display-prefix (arg)
       "Display the value of the raw prefix arg."
       (interactive "P")
       (message "%s" arg))

Here are the results of calling `display-prefix' with various raw
prefix arguments:

             M-x display-prefix  -| nil

     C-u     M-x display-prefix  -| (4)

     C-u C-u M-x display-prefix  -| (16)

     C-u 3   M-x display-prefix  -| 3

     M-3     M-x display-prefix  -| 3      ; (Same as `C-u 3'.)

     C-u -   M-x display-prefix  -| -

     M--     M-x display-prefix  -| -      ; (Same as `C-u -'.)

     C-u - 7 M-x display-prefix  -| -7

     M-- 7   M-x display-prefix  -| -7     ; (Same as `C-u -7'.)

   Emacs uses two variables to store the prefix argument: `prefix-arg'
and `current-prefix-arg'.  Commands such as `universal-argument' that
set up prefix arguments for other commands store them in `prefix-arg'.
In contrast, `current-prefix-arg' conveys the prefix argument to the
current command, so setting it has no effect on the prefix arguments
for future commands.

   Normally, commands specify which representation to use for the prefix
argument, either numeric or raw, in the `interactive' specification.
(*Note Using Interactive::.)  Alternatively, functions may look at the
value of the prefix argument directly in the variable
`current-prefix-arg', but this is less clean.

 -- Function: prefix-numeric-value arg
     This function returns the numeric meaning of a valid raw prefix
     argument value, ARG.  The argument may be a symbol, a number, or a
     list.  If it is `nil', the value 1 is returned; if it is `-', the
     value -1 is returned; if it is a number, that number is returned;
     if it is a list, the CAR of that list (which should be a number) is
     returned.

 -- Variable: current-prefix-arg
     This variable holds the raw prefix argument for the _current_
     command.  Commands may examine it directly, but the usual method
     for accessing it is with `(interactive "P")'.

 -- Variable: prefix-arg
     The value of this variable is the raw prefix argument for the
     _next_ editing command.  Commands such as `universal-argument'
     that specify prefix arguments for the following command work by
     setting this variable.

 -- Variable: last-prefix-arg
     The raw prefix argument value used by the previous command.

   The following commands exist to set up prefix arguments for the
following command.  Do not call them for any other reason.

 -- Command: universal-argument
     This command reads input and specifies a prefix argument for the
     following command.  Don't call this command yourself unless you
     know what you are doing.

 -- Command: digit-argument arg
     This command adds to the prefix argument for the following
     command.  The argument ARG is the raw prefix argument as it was
     before this command; it is used to compute the updated prefix
     argument.  Don't call this command yourself unless you know what
     you are doing.

 -- Command: negative-argument arg
     This command adds to the numeric argument for the next command.
     The argument ARG is the raw prefix argument as it was before this
     command; its value is negated to form the new prefix argument.
     Don't call this command yourself unless you know what you are
     doing.

File: elisp,  Node: Recursive Editing,  Next: Disabling Commands,  Prev: Prefix Command Arguments,  Up: Command Loop

21.13 Recursive Editing
=======================

The Emacs command loop is entered automatically when Emacs starts up.
This top-level invocation of the command loop never exits; it keeps
running as long as Emacs does.  Lisp programs can also invoke the
command loop.  Since this makes more than one activation of the command
loop, we call it "recursive editing".  A recursive editing level has
the effect of suspending whatever command invoked it and permitting the
user to do arbitrary editing before resuming that command.

   The commands available during recursive editing are the same ones
available in the top-level editing loop and defined in the keymaps.
Only a few special commands exit the recursive editing level; the others
return to the recursive editing level when they finish.  (The special
commands for exiting are always available, but they do nothing when
recursive editing is not in progress.)

   All command loops, including recursive ones, set up all-purpose error
handlers so that an error in a command run from the command loop will
not exit the loop.

   Minibuffer input is a special kind of recursive editing.  It has a
few special wrinkles, such as enabling display of the minibuffer and the
minibuffer window, but fewer than you might suppose.  Certain keys
behave differently in the minibuffer, but that is only because of the
minibuffer's local map; if you switch windows, you get the usual Emacs
commands.

   To invoke a recursive editing level, call the function
`recursive-edit'.  This function contains the command loop; it also
contains a call to `catch' with tag `exit', which makes it possible to
exit the recursive editing level by throwing to `exit' (*note Catch and
Throw::).  If you throw a value other than `t', then `recursive-edit'
returns normally to the function that called it.  The command `C-M-c'
(`exit-recursive-edit') does this.  Throwing a `t' value causes
`recursive-edit' to quit, so that control returns to the command loop
one level up.  This is called "aborting", and is done by `C-]'
(`abort-recursive-edit').

   Most applications should not use recursive editing, except as part of
using the minibuffer.  Usually it is more convenient for the user if you
change the major mode of the current buffer temporarily to a special
major mode, which should have a command to go back to the previous mode.
(The `e' command in Rmail uses this technique.)  Or, if you wish to
give the user different text to edit "recursively," create and select a
new buffer in a special mode.  In this mode, define a command to
complete the processing and go back to the previous buffer.  (The `m'
command in Rmail does this.)

   Recursive edits are useful in debugging.  You can insert a call to
`debug' into a function definition as a sort of breakpoint, so that you
can look around when the function gets there.  `debug' invokes a
recursive edit but also provides the other features of the debugger.

   Recursive editing levels are also used when you type `C-r' in
`query-replace' or use `C-x q' (`kbd-macro-query').

 -- Function: recursive-edit
     This function invokes the editor command loop.  It is called
     automatically by the initialization of Emacs, to let the user begin
     editing.  When called from a Lisp program, it enters a recursive
     editing level.

     If the current buffer is not the same as the selected window's
     buffer, `recursive-edit' saves and restores the current buffer.
     Otherwise, if you switch buffers, the buffer you switched to is
     current after `recursive-edit' returns.

     In the following example, the function `simple-rec' first advances
     point one word, then enters a recursive edit, printing out a
     message in the echo area.  The user can then do any editing
     desired, and then type `C-M-c' to exit and continue executing
     `simple-rec'.

          (defun simple-rec ()
            (forward-word 1)
            (message "Recursive edit in progress")
            (recursive-edit)
            (forward-word 1))
               => simple-rec
          (simple-rec)
               => nil

 -- Command: exit-recursive-edit
     This function exits from the innermost recursive edit (including
     minibuffer input).  Its definition is effectively `(throw 'exit
     nil)'.

 -- Command: abort-recursive-edit
     This function aborts the command that requested the innermost
     recursive edit (including minibuffer input), by signaling `quit'
     after exiting the recursive edit.  Its definition is effectively
     `(throw 'exit t)'.  *Note Quitting::.

 -- Command: top-level
     This function exits all recursive editing levels; it does not
     return a value, as it jumps completely out of any computation
     directly back to the main command loop.

 -- Function: recursion-depth
     This function returns the current depth of recursive edits.  When
     no recursive edit is active, it returns 0.

File: elisp,  Node: Disabling Commands,  Next: Command History,  Prev: Recursive Editing,  Up: Command Loop

21.14 Disabling Commands
========================

"Disabling a command" marks the command as requiring user confirmation
before it can be executed.  Disabling is used for commands which might
be confusing to beginning users, to prevent them from using the
commands by accident.

   The low-level mechanism for disabling a command is to put a
non-`nil' `disabled' property on the Lisp symbol for the command.
These properties are normally set up by the user's init file (*note
Init File::) with Lisp expressions such as this:

     (put 'upcase-region 'disabled t)

For a few commands, these properties are present by default (you can
remove them in your init file if you wish).

   If the value of the `disabled' property is a string, the message
saying the command is disabled includes that string.  For example:

     (put 'delete-region 'disabled
          "Text deleted this way cannot be yanked back!\n")

   *Note Disabling: (emacs)Disabling, for the details on what happens
when a disabled command is invoked interactively.  Disabling a command
has no effect on calling it as a function from Lisp programs.

 -- Command: enable-command command
     Allow COMMAND (a symbol) to be executed without special
     confirmation from now on, and alter the user's init file (*note
     Init File::) so that this will apply to future sessions.

 -- Command: disable-command command
     Require special confirmation to execute COMMAND from now on, and
     alter the user's init file so that this will apply to future
     sessions.

 -- Variable: disabled-command-function
     The value of this variable should be a function.  When the user
     invokes a disabled command interactively, this function is called
     instead of the disabled command.  It can use `this-command-keys'
     to determine what the user typed to run the command, and thus find
     the command itself.

     The value may also be `nil'.  Then all commands work normally,
     even disabled ones.

     By default, the value is a function that asks the user whether to
     proceed.

File: elisp,  Node: Command History,  Next: Keyboard Macros,  Prev: Disabling Commands,  Up: Command Loop

21.15 Command History
=====================

The command loop keeps a history of the complex commands that have been
executed, to make it convenient to repeat these commands.  A "complex
command" is one for which the interactive argument reading uses the
minibuffer.  This includes any `M-x' command, any `M-:' command, and
any command whose `interactive' specification reads an argument from
the minibuffer.  Explicit use of the minibuffer during the execution of
the command itself does not cause the command to be considered complex.

 -- Variable: command-history
     This variable's value is a list of recent complex commands, each
     represented as a form to evaluate.  It continues to accumulate all
     complex commands for the duration of the editing session, but when
     it reaches the maximum size (*note Minibuffer Hist