www.delorie.com/gnu/docs/elisp-manual-21/elisp_toc.html

search

	Buy the book!

GNU Emacs Lisp Reference Manual

Table of Contents

1. Introduction

1.1 Caveats
1.2 Lisp History
1.3 Conventions

1.3.1 Some Terms
1.3.2 nil and t
1.3.3 Evaluation Notation
1.3.4 Printing Notation
1.3.5 Error Messages
1.3.6 Buffer Text Notation
1.3.7 Format of Descriptions

1.3.7.1 A Sample Function Description
1.3.7.2 A Sample Variable Description

1.4 Version Information
1.5 Acknowledgements

2. Lisp Data Types

2.1 Printed Representation and Read Syntax
2.2 Comments
2.3 Programming Types

2.3.1 Integer Type
2.3.2 Floating Point Type
2.3.3 Character Type
2.3.4 Symbol Type
2.3.5 Sequence Types
2.3.6 Cons Cell and List Types

2.3.6.1 Dotted Pair Notation
2.3.6.2 Association List Type

2.3.7 Array Type
2.3.8 String Type

2.3.8.1 Syntax for Strings
2.3.8.2 Non-ASCII Characters in Strings
2.3.8.3 Nonprinting Characters in Strings
2.3.8.4 Text Properties in Strings

2.3.9 Vector Type
2.3.10 Char-Table Type
2.3.11 Bool-Vector Type
2.3.12 Hash Table Type
2.3.13 Function Type
2.3.14 Macro Type
2.3.15 Primitive Function Type
2.3.16 Byte-Code Function Type
2.3.17 Autoload Type

2.4 Editing Types

2.4.1 Buffer Type
2.4.2 Marker Type
2.4.3 Window Type
2.4.4 Frame Type
2.4.5 Window Configuration Type
2.4.6 Frame Configuration Type
2.4.7 Process Type
2.4.8 Stream Type
2.4.9 Keymap Type
2.4.10 Overlay Type

2.5 Read Syntax for Circular Objects
2.6 Type Predicates
2.7 Equality Predicates

3. Numbers

3.1 Integer Basics
3.2 Floating Point Basics
3.3 Type Predicates for Numbers
3.4 Comparison of Numbers
3.5 Numeric Conversions
3.6 Arithmetic Operations
3.7 Rounding Operations
3.8 Bitwise Operations on Integers
3.9 Standard Mathematical Functions
3.10 Random Numbers

4. Strings and Characters

4.1 String and Character Basics
4.2 The Predicates for Strings
4.3 Creating Strings
4.4 Modifying Strings
4.5 Comparison of Characters and Strings
4.6 Conversion of Characters and Strings
4.7 Formatting Strings
4.8 Case Conversion in Lisp
4.9 The Case Table

5. Lists

5.1 Lists and Cons Cells
5.2 Lists as Linked Pairs of Boxes
5.3 Predicates on Lists
5.4 Accessing Elements of Lists
5.5 Building Cons Cells and Lists
5.6 Modifying Existing List Structure

5.6.1 Altering List Elements with setcar
5.6.2 Altering the CDR of a List
5.6.3 Functions that Rearrange Lists

5.7 Using Lists as Sets
5.8 Association Lists

6. Sequences, Arrays, and Vectors

6.1 Sequences
6.2 Arrays
6.3 Functions that Operate on Arrays
6.4 Vectors
6.5 Functions for Vectors
6.6 Char-Tables
6.7 Bool-vectors

7. Hash Tables

7.1 Creating Hash Tables
7.2 Hash Table Access
7.3 Defining Hash Comparisons
7.4 Other Hash Table Functions

8. Symbols

8.1 Symbol Components
8.2 Defining Symbols
8.3 Creating and Interning Symbols
8.4 Property Lists

8.4.1 Property Lists and Association Lists
8.4.2 Property List Functions for Symbols
8.4.3 Property Lists Outside Symbols

9. Evaluation

9.1 Introduction to Evaluation
9.2 Kinds of Forms

9.2.1 Self-Evaluating Forms
9.2.2 Symbol Forms
9.2.3 Classification of List Forms
9.2.4 Symbol Function Indirection
9.2.5 Evaluation of Function Forms
9.2.6 Lisp Macro Evaluation
9.2.7 Special Forms
9.2.8 Autoloading

9.3 Quoting
9.4 Eval

10. Control Structures

10.1 Sequencing
10.2 Conditionals
10.3 Constructs for Combining Conditions
10.4 Iteration
10.5 Nonlocal Exits

10.5.1 Explicit Nonlocal Exits: catch and throw
10.5.2 Examples of catch and throw
10.5.3 Errors

10.5.3.1 How to Signal an Error
10.5.3.2 How Emacs Processes Errors
10.5.3.3 Writing Code to Handle Errors
10.5.3.4 Error Symbols and Condition Names

10.5.4 Cleaning Up from Nonlocal Exits

11. Variables

11.1 Global Variables
11.2 Variables that Never Change
11.3 Local Variables
11.4 When a Variable is "Void"
11.5 Defining Global Variables
11.6 Tips for Defining Variables Robustly
11.7 Accessing Variable Values
11.8 How to Alter a Variable Value
11.9 Scoping Rules for Variable Bindings

11.9.1 Scope
11.9.2 Extent
11.9.3 Implementation of Dynamic Scoping
11.9.4 Proper Use of Dynamic Scoping

11.10 Buffer-Local Variables

11.10.1 Introduction to Buffer-Local Variables
11.10.2 Creating and Deleting Buffer-Local Bindings
11.10.3 The Default Value of a Buffer-Local Variable

11.11 Frame-Local Variables
11.12 Possible Future Local Variables
11.13 File Local Variables

12. Functions

12.1 What Is a Function?
12.2 Lambda Expressions

12.2.1 Components of a Lambda Expression
12.2.2 A Simple Lambda-Expression Example
12.2.3 Other Features of Argument Lists
12.2.4 Documentation Strings of Functions

12.3 Naming a Function
12.4 Defining Functions
12.5 Calling Functions
12.6 Mapping Functions
12.7 Anonymous Functions
12.8 Accessing Function Cell Contents
12.9 Inline Functions
12.10 Other Topics Related to Functions

13. Macros

13.1 A Simple Example of a Macro
13.2 Expansion of a Macro Call
13.3 Macros and Byte Compilation
13.4 Defining Macros
13.5 Backquote
13.6 Common Problems Using Macros

13.6.1 Wrong Time
13.6.2 Evaluating Macro Arguments Repeatedly
13.6.3 Local Variables in Macro Expansions
13.6.4 Evaluating Macro Arguments in Expansion
13.6.5 How Many Times is the Macro Expanded?

14. Writing Customization Definitions

14.1 Common Item Keywords
14.2 Defining Custom Groups
14.3 Defining Customization Variables
14.4 Customization Types

14.4.1 Simple Types
14.4.2 Composite Types
14.4.3 Splicing into Lists
14.4.4 Type Keywords

15. Loading

15.1 How Programs Do Loading
15.2 Library Search
15.3 Loading Non-ASCII Characters
15.4 Autoload
15.5 Repeated Loading
15.6 Features
15.7 Unloading
15.8 Hooks for Loading

16. Byte Compilation

16.1 Performance of Byte-Compiled Code
16.2 The Compilation Functions
16.3 Documentation Strings and Compilation
16.4 Dynamic Loading of Individual Functions
16.5 Evaluation During Compilation
16.6 Byte-Code Function Objects
16.7 Disassembled Byte-Code

17. Advising Emacs Lisp Functions

17.1 A Simple Advice Example
17.2 Defining Advice
17.3 Around-Advice
17.4 Computed Advice
17.5 Activation of Advice
17.6 Enabling and Disabling Advice
17.7 Preactivation
17.8 Argument Access in Advice
17.9 Definition of Subr Argument Lists
17.10 The Combined Definition

18. Debugging Lisp Programs

18.1 The Lisp Debugger

18.1.1 Entering the Debugger on an Error
18.1.2 Debugging Infinite Loops
18.1.3 Entering the Debugger on a Function Call
18.1.4 Explicit Entry to the Debugger
18.1.5 Using the Debugger
18.1.6 Debugger Commands
18.1.7 Invoking the Debugger
18.1.8 Internals of the Debugger

18.2 Edebug

18.2.1 Using Edebug
18.2.2 Instrumenting for Edebug
18.2.3 Edebug Execution Modes
18.2.4 Jumping
18.2.5 Miscellaneous Edebug Commands
18.2.6 Breakpoints

18.2.6.1 Global Break Condition
18.2.6.2 Source Breakpoints

18.2.7 Trapping Errors
18.2.8 Edebug Views
18.2.9 Evaluation
18.2.10 Evaluation List Buffer
18.2.11 Printing in Edebug
18.2.12 Trace Buffer
18.2.13 Coverage Testing
18.2.14 The Outside Context

18.2.14.1 Checking Whether to Stop
18.2.14.2 Edebug Display Update
18.2.14.3 Edebug Recursive Edit

18.2.15 Instrumenting Macro Calls

18.2.15.1 Specification List
18.2.15.2 Backtracking in Specifications
18.2.15.3 Specification Examples

18.2.16 Edebug Options

18.3 Debugging Invalid Lisp Syntax

18.3.1 Excess Open Parentheses
18.3.2 Excess Close Parentheses

18.4 Debugging Problems in Compilation

19. Reading and Printing Lisp Objects

19.1 Introduction to Reading and Printing
19.2 Input Streams
19.3 Input Functions
19.4 Output Streams
19.5 Output Functions
19.6 Variables Affecting Output

20. Minibuffers

20.1 Introduction to Minibuffers
20.2 Reading Text Strings with the Minibuffer
20.3 Reading Lisp Objects with the Minibuffer
20.4 Minibuffer History
20.5 Completion

20.5.1 Basic Completion Functions
20.5.2 Completion and the Minibuffer
20.5.3 Minibuffer Commands that Do Completion
20.5.4 High-Level Completion Functions
20.5.5 Reading File Names
20.5.6 Programmed Completion

20.6 Yes-or-No Queries
20.7 Asking Multiple Y-or-N Questions
20.8 Reading a Password
20.9 Minibuffer Miscellany

21. Command Loop

21.1 Command Loop Overview
21.2 Defining Commands

21.2.1 Using interactive
21.2.2 Code Characters for interactive
21.2.3 Examples of Using interactive

21.3 Interactive Call
21.4 Information from the Command Loop
21.5 Adjusting Point After Commands
21.6 Input Events

21.6.1 Keyboard Events
21.6.2 Function Keys
21.6.3 Mouse Events
21.6.4 Click Events
21.6.5 Drag Events
21.6.6 Button-Down Events
21.6.7 Repeat Events
21.6.8 Motion Events
21.6.9 Focus Events
21.6.10 Miscellaneous Window System Events
21.6.11 Event Examples
21.6.12 Classifying Events
21.6.13 Accessing Events
21.6.14 Putting Keyboard Events in Strings

21.7 Reading Input

21.7.1 Key Sequence Input
21.7.2 Reading One Event
21.7.3 Invoking the Input Method
21.7.4 Quoted Character Input
21.7.5 Miscellaneous Event Input Features

21.8 Special Events
21.9 Waiting for Elapsed Time or Input
21.10 Quitting
21.11 Prefix Command Arguments
21.12 Recursive Editing
21.13 Disabling Commands
21.14 Command History
21.15 Keyboard Macros

22. Keymaps

22.1 Keymap Terminology
22.2 Format of Keymaps
22.3 Creating Keymaps
22.4 Inheritance and Keymaps
22.5 Prefix Keys
22.6 Active Keymaps
22.7 Key Lookup
22.8 Functions for Key Lookup
22.9 Changing Key Bindings
22.10 Commands for Binding Keys
22.11 Scanning Keymaps
22.12 Menu Keymaps

22.12.1 Defining Menus

22.12.1.1 Simple Menu Items
22.12.1.2 Extended Menu Items
22.12.1.3 Menu Separators
22.12.1.4 Alias Menu Items

22.12.2 Menus and the Mouse
22.12.3 Menus and the Keyboard
22.12.4 Menu Example
22.12.5 The Menu Bar
22.12.6 Tool bars
22.12.7 Modifying Menus

23. Major and Minor Modes

23.1 Major Modes

23.1.1 Major Mode Conventions
23.1.2 Major Mode Examples
23.1.3 How Emacs Chooses a Major Mode
23.1.4 Getting Help about a Major Mode
23.1.5 Defining Derived Modes

23.2 Minor Modes

23.2.1 Conventions for Writing Minor Modes
23.2.2 Keymaps and Minor Modes
23.2.3 Defining Minor Modes

23.3 Mode Line Format

23.3.1 The Data Structure of the Mode Line
23.3.2 Variables Used in the Mode Line
23.3.3 %-Constructs in the Mode Line
23.3.4 Properties in the Mode Line
23.3.5 Window Header Lines

23.4 Imenu
23.5 Font Lock Mode

23.5.1 Font Lock Basics
23.5.2 Search-based Fontification
23.5.3 Other Font Lock Variables
23.5.4 Levels of Font Lock
23.5.5 Faces for Font Lock
23.5.6 Syntactic Font Lock

23.6 Hooks

24. Documentation

24.1 Documentation Basics
24.2 Access to Documentation Strings
24.3 Substituting Key Bindings in Documentation
24.4 Describing Characters for Help Messages
24.5 Help Functions

25. Files

25.1 Visiting Files

25.1.1 Functions for Visiting Files
25.1.2 Subroutines of Visiting

25.2 Saving Buffers
25.3 Reading from Files
25.4 Writing to Files
25.5 File Locks
25.6 Information about Files

25.6.1 Testing Accessibility
25.6.2 Distinguishing Kinds of Files
25.6.3 Truenames
25.6.4 Other Information about Files

25.7 Changing File Names and Attributes
25.8 File Names

25.8.1 File Name Components
25.8.2 Directory Names
25.8.3 Absolute and Relative File Names
25.8.4 Functions that Expand Filenames
25.8.5 Generating Unique File Names
25.8.6 File Name Completion
25.8.7 Standard File Names

25.9 Contents of Directories
25.10 Creating and Deleting Directories
25.11 Making Certain File Names "Magic"
25.12 File Format Conversion

26. Backups and Auto-Saving

26.1 Backup Files

26.1.1 Making Backup Files
26.1.2 Backup by Renaming or by Copying?
26.1.3 Making and Deleting Numbered Backup Files
26.1.4 Naming Backup Files

26.2 Auto-Saving
26.3 Reverting

27. Buffers

27.1 Buffer Basics
27.2 The Current Buffer
27.3 Buffer Names
27.4 Buffer File Name
27.5 Buffer Modification
27.6 Comparison of Modification Time
27.7 Read-Only Buffers
27.8 The Buffer List
27.9 Creating Buffers
27.10 Killing Buffers
27.11 Indirect Buffers
27.12 The Buffer Gap

28. Windows

28.1 Basic Concepts of Emacs Windows
28.2 Splitting Windows
28.3 Deleting Windows
28.4 Selecting Windows
28.5 Cyclic Ordering of Windows
28.6 Buffers and Windows
28.7 Displaying Buffers in Windows
28.8 Choosing a Window for Display
28.9 Windows and Point
28.10 The Window Start Position
28.11 Textual Scrolling
28.12 Vertical Fractional Scrolling
28.13 Horizontal Scrolling
28.14 The Size of a Window
28.15 Changing the Size of a Window
28.16 Coordinates and Windows
28.17 Window Configurations
28.18 Hooks for Window Scrolling and Changes

29. Frames

29.1 Creating Frames
29.2 Multiple Displays
29.3 Frame Parameters

29.3.1 Access to Frame Parameters
29.3.2 Initial Frame Parameters
29.3.3 Window Frame Parameters
29.3.4 Frame Size And Position

29.4 Frame Titles
29.5 Deleting Frames
29.6 Finding All Frames
29.7 Frames and Windows
29.8 Minibuffers and Frames
29.9 Input Focus
29.10 Visibility of Frames
29.11 Raising and Lowering Frames
29.12 Frame Configurations
29.13 Mouse Tracking
29.14 Mouse Position
29.15 Pop-Up Menus
29.16 Dialog Boxes
29.17 Pointer Shapes
29.18 Window System Selections
29.19 Color Names
29.20 Text Terminal Colors
29.21 X Resources
29.22 Display Feature Testing

30. Positions

30.1 Point
30.2 Motion

30.2.1 Motion by Characters
30.2.2 Motion by Words
30.2.3 Motion to an End of the Buffer
30.2.4 Motion by Text Lines
30.2.5 Motion by Screen Lines
30.2.6 Moving over Balanced Expressions
30.2.7 Skipping Characters

30.3 Excursions
30.4 Narrowing

31. Markers

31.1 Overview of Markers
31.2 Predicates on Markers
31.3 Functions that Create Markers
31.4 Information from Markers
31.5 Marker Insertion Types
31.6 Moving Marker Positions
31.7 The Mark
31.8 The Region

32. Text

32.1 Examining Text Near Point
32.2 Examining Buffer Contents
32.3 Comparing Text
32.4 Inserting Text
32.5 User-Level Insertion Commands
32.6 Deleting Text
32.7 User-Level Deletion Commands
32.8 The Kill Ring

32.8.1 Kill Ring Concepts
32.8.2 Functions for Killing
32.8.3 Functions for Yanking
32.8.4 Low-Level Kill Ring
32.8.5 Internals of the Kill Ring

32.9 Undo
32.10 Maintaining Undo Lists
32.11 Filling
32.12 Margins for Filling
32.13 Adaptive Fill Mode
32.14 Auto Filling
32.15 Sorting Text
32.16 Counting Columns
32.17 Indentation

32.17.1 Indentation Primitives
32.17.2 Indentation Controlled by Major Mode
32.17.3 Indenting an Entire Region
32.17.4 Indentation Relative to Previous Lines
32.17.5 Adjustable "Tab Stops"
32.17.6 Indentation-Based Motion Commands

32.18 Case Changes
32.19 Text Properties

32.19.1 Examining Text Properties
32.19.2 Changing Text Properties
32.19.3 Text Property Search Functions
32.19.4 Properties with Special Meanings
32.19.5 Formatted Text Properties
32.19.6 Stickiness of Text Properties
32.19.7 Saving Text Properties in Files
32.19.8 Lazy Computation of Text Properties
32.19.9 Defining Clickable Text
32.19.10 Defining and Using Fields
32.19.11 Why Text Properties are not Intervals

32.20 Substituting for a Character Code
32.21 Registers
32.22 Transposition of Text
32.23 Base 64 Encoding
32.24 MD5 Checksum
32.25 Change Hooks

33. Non-ASCII Characters

33.1 Text Representations
33.2 Converting Text Representations
33.3 Selecting a Representation
33.4 Character Codes
33.5 Character Sets
33.6 Characters and Bytes
33.7 Splitting Characters
33.8 Scanning for Character Sets
33.9 Translation of Characters
33.10 Coding Systems

33.10.1 Basic Concepts of Coding Systems
33.10.2 Encoding and I/O
33.10.3 Coding Systems in Lisp
33.10.4 User-Chosen Coding Systems
33.10.5 Default Coding Systems
33.10.6 Specifying a Coding System for One Operation
33.10.7 Explicit Encoding and Decoding
33.10.8 Terminal I/O Encoding
33.10.9 MS-DOS File Types

33.11 Input Methods
33.12 Locales

34. Searching and Matching

34.1 Searching for Strings
34.2 Regular Expressions

34.2.1 Syntax of Regular Expressions

34.2.1.1 Special Characters in Regular Expressions
34.2.1.2 Character Classes
34.2.1.3 Backslash Constructs in Regular Expressions

34.2.2 Complex Regexp Example
34.2.3 Regular Expression Functions

34.3 Regular Expression Searching
34.4 POSIX Regular Expression Searching
34.5 Search and Replace
34.6 The Match Data

34.6.1 Replacing the Text that Matched
34.6.2 Simple Match Data Access
34.6.3 Accessing the Entire Match Data
34.6.4 Saving and Restoring the Match Data

34.7 Searching and Case
34.8 Standard Regular Expressions Used in Editing

35. Syntax Tables

35.1 Syntax Table Concepts
35.2 Syntax Descriptors

35.2.1 Table of Syntax Classes
35.2.2 Syntax Flags

35.3 Syntax Table Functions
35.4 Syntax Properties
35.5 Motion and Syntax
35.6 Parsing Balanced Expressions
35.7 Some Standard Syntax Tables
35.8 Syntax Table Internals
35.9 Categories

36. Abbrevs and Abbrev Expansion

36.1 Setting Up Abbrev Mode
36.2 Abbrev Tables
36.3 Defining Abbrevs
36.4 Saving Abbrevs in Files
36.5 Looking Up and Expanding Abbreviations
36.6 Standard Abbrev Tables

37. Processes

37.1 Functions that Create Subprocesses
37.2 Shell Arguments
37.3 Creating a Synchronous Process
37.4 Creating an Asynchronous Process
37.5 Deleting Processes
37.6 Process Information
37.7 Sending Input to Processes
37.8 Sending Signals to Processes
37.9 Receiving Output from Processes

37.9.1 Process Buffers
37.9.2 Process Filter Functions
37.9.3 Accepting Output from Processes

37.10 Sentinels: Detecting Process Status Changes
37.11 Transaction Queues
37.12 Network Connections

38. Emacs Display

38.1 Refreshing the Screen
38.2 Forcing Redisplay
38.3 Truncation
38.4 The Echo Area
38.5 Invisible Text
38.6 Selective Display
38.7 The Overlay Arrow
38.8 Temporary Displays
38.9 Overlays

38.9.1 Overlay Properties
38.9.2 Managing Overlays
38.9.3 Searching for Overlays

38.10 Width
38.11 Faces

38.11.1 Standard Faces
38.11.2 Defining Faces
38.11.3 Face Attributes
38.11.4 Face Attribute Functions
38.11.5 Merging Faces for Display
38.11.6 Font Selection
38.11.7 Functions for Working with Faces
38.11.8 Automatic Face Assignment
38.11.9 Looking Up Fonts
38.11.10 Fontsets

38.12 The display Property

38.12.1 Specified Spaces
38.12.2 Other Display Specifications
38.12.3 Displaying in the Margins
38.12.4 Conditional Display Specifications

38.13 Images

38.13.1 Image Descriptors
38.13.2 XBM Images
38.13.3 XPM Images
38.13.4 GIF Images
38.13.5 Postscript Images
38.13.6 Other Image Types
38.13.7 Defining Images
38.13.8 Showing Images
38.13.9 Image Cache

38.14 Blinking Parentheses
38.15 Inverse Video
38.16 Usual Display Conventions
38.17 Display Tables

38.17.1 Display Table Format
38.17.2 Active Display Table
38.17.3 Glyphs

38.18 Beeping
38.19 Window Systems

39. Customizing the Calendar and Diary

39.1 Customizing the Calendar
39.2 Customizing the Holidays
39.3 Date Display Format
39.4 Time Display Format
39.5 Daylight Savings Time
39.6 Customizing the Diary
39.7 Hebrew- and Islamic-Date Diary Entries
39.8 Fancy Diary Display
39.9 Sexp Entries and the Fancy Diary Display
39.10 Customizing Appointment Reminders

40. Operating System Interface

40.1 Starting Up Emacs

40.1.1 Summary: Sequence of Actions at Startup
40.1.2 The Init File, `.emacs'
40.1.3 Terminal-Specific Initialization
40.1.4 Command-Line Arguments

40.2 Getting Out of Emacs

40.2.1 Killing Emacs
40.2.2 Suspending Emacs

40.3 Operating System Environment
40.4 User Identification
40.5 Time of Day
40.6 Time Conversion
40.7 Timers for Delayed Execution
40.8 Terminal Input

40.8.1 Input Modes
40.8.2 Translating Input Events
40.8.3 Recording Input

40.9 Terminal Output
40.10 Sound Output
40.11 System-Specific X11 Keysyms
40.12 Flow Control
40.13 Batch Mode

A. Emacs 20 Antinews

A.1 Old Lisp Features in Emacs 20
A.2 Old Lisp Features in Emacs 20.3

B. GNU Free Documentation License

ADDENDUM: How to use this License for your documents

C. GNU General Public License

Preamble
How to Apply These Terms to Your New Programs

D. Tips and Conventions

D.1 Emacs Lisp Coding Conventions
D.2 Tips for Making Compiled Code Fast
D.3 Tips for Documentation Strings
D.4 Tips on Writing Comments
D.5 Conventional Headers for Emacs Libraries

E. GNU Emacs Internals

E.1 Building Emacs
E.2 Pure Storage
E.3 Garbage Collection
E.4 Memory Usage
E.5 Writing Emacs Primitives
E.6 Object Internals

E.6.1 Buffer Internals
E.6.2 Window Internals
E.6.3 Process Internals

F. Standard Errors
G. Buffer-Local Variables
H. Standard Keymaps
I. Standard Hooks
Index
New Symbols Since the Previous Edition