GNU Emacs Lisp Reference Manual

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

Published by the Free Software Foundation 59 Temple Place, Suite 330 Boston, MA 02111-1307 USA

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being “Copying”, 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 freedom to copy and modify this GNU Manual, like GNU software. Copies published by the Free Software Foundation raise funds for GNU development.”

Next: Introduction, Previous: (dir), Up: (dir)

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

Introduction: Introduction and conventions used.
Standards: Coding conventions for Emacs Lisp.
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 X 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.
Calendar: Customizing the calendar and diary.
System Interface: Getting the user id, system type, environment variables, and other such things.

Appendices

Antinews: Info for users downgrading to Emacs 20.
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.
New Symbols: New functions and variables in Emacs 21.

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

Conventions

Some Terms: Explanation of terms we use in this manual.
nil and t: How the symbols nil and t are used.
Evaluation Notation: The format we use for examples of evaluation.
Printing Notation: The format we use for examples that print output.
Error Messages: The format we use for examples of errors.
Buffer Text Notation: The format we use for buffer contents in examples.
Format of Descriptions: Notation for describing functions, variables, etc.

Tips and Conventions

Format of Descriptions

Lisp Data Types

Programming Types

Integer Type: Numbers without fractional parts.
Floating Point Type: Numbers with fractional parts and with a large range.
Character Type: The representation of letters, numbers and control characters.
Sequence Type: Both lists and arrays are classified as sequences.
Cons Cell Type: Cons cells, and lists (which are made from cons cells).
Array Type: Arrays include strings and vectors.
String Type: An (efficient) array of characters.
Vector Type: One-dimensional arrays.
Symbol Type: A multi-use object that refers to a function, variable, property list, or itself.
Function Type: A piece of executable code you can call from elsewhere.
Macro Type: A method of expanding an expression into another expression, more fundamental but less pretty.
Primitive Function Type: A function written in C, callable from Lisp.
Byte-Code Type: A function written in Lisp, then compiled.
Autoload Type: A type used for automatically loading seldom-used functions.

List Type

Editing Types

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.
Arithmetic Operations: How to add, subtract, multiply and divide.
Bitwise Operations: Logical and, or, not, shifting.
Numeric Conversions: Converting float to integer and vice versa.
Math Functions: Trig, exponential and logarithmic functions.
Random Numbers: Obtaining random integers, predictable or not.

Strings and Characters

Lists

Cons Cells: How lists are made out of cons cells.
Lists as Boxes: Graphical notation to explain lists.
List-related Predicates: Is this object a list? Comparing two lists.
List Elements: Extracting the pieces of a list.
Building Lists: Creating list structure.
Modifying Lists: Storing new pieces into an existing list.
Sets And Lists: A list can represent a finite mathematical set.
Association Lists: A list can represent a finite relation or mapping.

Modifying Existing List Structure

Sequences, Arrays, and Vectors

Symbols

Evaluation

Kinds of Forms

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

Control Structures

Nonlocal Exits

Errors

Variables

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

Scoping Rules for Variable Bindings

Buffer-Local Variables

Functions

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

Lambda Expressions

Macros

Byte Compilation

Advising Functions

Simple Advice: A simple example to explain the basics of advice.
Defining Advice: Detailed description of defadvice.
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.
Subr Arguments: Accessing arguments when advising a primitive.
Combined Definition: How advice is implemented.

Debugging Lisp Programs

The Lisp Debugger

Debugging Invalid Lisp Syntax

Reading and Printing Lisp Objects

Minibuffers

Completion

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

Command Loop

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

Defining Commands

Keymaps

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

Major and Minor Modes

Major Modes

Minor Modes

Mode Line Format

Documentation

Files

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

Visiting Files

Information about Files

File Names

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

Backups and Auto-Saving

Backup Files

Buffers

Buffer Basics: What is a buffer?
Buffer Names: Accessing and changing buffer names.
Buffer File Name: The buffer file name indicates which file is visited.
Buffer Modification: A buffer is modified if it needs to be saved.
Modification Time: Determining whether the visited file was changed ``behind 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.
Current Buffer: Designating a buffer as current so primitives will access its contents.

Windows

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

Frames

Creating Frames: Creating additional frames.
Multiple Displays: Creating frames on other X displays.
Frame Parameters: Controlling frame size, position, font, etc.
Frame Titles: Automatic updating of frame titles.
Deleting Frames: Frames last until explicitly deleted.
Finding All Frames: How to examine all existing frames.
Frames and Windows: A frame contains windows; display of text always works through windows.
Minibuffers and Frames: How a frame finds the minibuffer to use.
Input Focus: Specifying the selected frame.
Visibility of Frames: Frames may be visible or invisible, or icons.
Raising and Lowering: Raising a frame makes it hide other X windows; lowering it puts it underneath the others.
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 Shapes: Specifying the shape of the mouse pointer.
Window System Selections: Transferring text to and from other windows.
Color Names: Getting the definitions of color names.
Resources: Getting resource values from the server.
Display Feature Testing: Determining the features of a terminal.

Positions

Motion

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.
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.
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.
Auto Filling: How auto-fill mode is implemented to break lines.
Filling: Functions for explicit filling.
Margins: How to specify margins for filling commands.
Sorting: Functions for sorting parts of the buffer.
Indentation: Functions to insert or adjust indentation.
Columns: Computing horizontal positions, and using them.
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.
Change Hooks: Supplying functions to be run when text is changed.

The Kill Ring

Indentation

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.
Saving Properties: Saving text properties in files, and reading them back.
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: Unibyte and multibyte representations
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 Sets: The space of possible characters codes is divided into various character sets.
Chars and Bytes: More information about multibyte encodings.
Splitting Characters: Converting a character to its byte sequence.
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.

Searching and Matching

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

Regular Expressions

Syntax Tables

Syntax Descriptors

Abbrevs And Abbrev Expansion

Processes

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

Receiving Output from Processes

Operating System Interface

Starting Up Emacs

Getting out of Emacs

Emacs Display

Refresh Screen: Clearing the screen and redrawing everything on it.
Truncation: Folding or wrapping long text lines.
The Echo Area: Where messages are displayed.
Selective Display: Hiding part of the buffer text.
Overlay Arrow: Display of an arrow to indicate position.
Temporary Displays: Displays that go away automatically.
Waiting: Forcing display update and waiting for user.
Blinking: How Emacs shows the matching open parenthesis.
Usual Display: How control characters are displayed.
Beeping: Audible signal to the user.
Window Systems: Which window system is being used.

GNU Emacs Internals

Object Internals