GNU Emacs Lisp Reference Manual

GNU Emacs Lisp Reference Manual
For Emacs Version 22.1
Revision 2.9, April 2007
by Bil Lewis, Dan LaLiberte, Richard Stallman
and the GNU Manual Group
This is edition 2.9 of the GNU Emacs Lisp Reference Manual,
corresponding to Emacs version 22.1.
Copyright
c
 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, 2001, 2002, 2003,
2004, 2005, 2006, 2007 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.2 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 freedom to copy and modify
this GNU Manual, like GNU software. Copies published by the Free Software
Foundation raise funds for GNU development.”
Published by the Free Software Foundation
51 Franklin St, Fifth Floor
Boston, MA 02110-1301
USA
ISBN 1-882114-74-4
Cover art by Etienne Suvasa.
i
Short Contents
1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
2 Lisp Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
3 Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

4 Strings and Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
5 Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
6 Sequences, Arrays, and Vectors . . . . . . . . . . . . . . . . . . . . . . . . . 87
7 Hash Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
8 Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
9 Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
10 Control Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
11 Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
12 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
13 Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
14 Writing Customization Definitions . . . . . . . . . . . . . . . . . . . . . . 185
15 Loading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
16 Byte Compilation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
17 Advising Emacs Lisp Functions . . . . . . . . . . . . . . . . . . . . . . . . 226
18 Debugging Lisp Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
19 Reading and Printing Lisp Objects . . . . . . . . . . . . . . . . . . . . . 268
20 Minibuffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
21 Command Loop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
22 Keymaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
23 Major and Minor Modes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
24 Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425
25 Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434
26 Backups and Auto-Saving . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471
27 Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481
28 Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497
29 Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529
30 Positions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 559
31 Markers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 572
32 Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 581
33 Non-ASCII Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 640

34 Searching and Matching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 661
35 Syntax Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 684
ii
36 Abbrevs and Abbrev Expansion. . . . . . . . . . . . . . . . . . . . . . . . 699
37 Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 705
38 Emacs Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 739
39 Operating System Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . 812
A Emacs 21 Antinews . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 838
B GNU Free Documentation License . . . . . . . . . . . . . . . . . . . . . . 843
C GNU General Public License . . . . . . . . . . . . . . . . . . . . . . . . . . 850
D Tips and Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 856
E GNU Emacs Internals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 870
F Standard Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 891
G Buffer-Local Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 895
H Standard Keymaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 899
I Standard Hooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 903
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 908
iii
Table of Contents
1 Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.1 Caveats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.2 Lisp History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.3 Conventions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.3.1 Some Terms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.3.2 nil and t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.3.3 Evaluation Notation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.3.4 Printing Notation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.3.5 Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.3.6 Buffer Text Notation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.3.7 Format of Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

1.3.7.1 A Sample Function Description . . . . . . . . . . . . . . . . . . . . . . . 4
1.3.7.2 A Sample Variable Description. . . . . . . . . . . . . . . . . . . . . . . . 6
1.4 Version Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.5 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2 Lisp Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.1 Printed Representation and Read Syntax . . . . . . . . . . . . . . . . . . . . . . . 8
2.2 Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.3 Programming Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.3.1 Integer Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.3.2 Floating Point Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.3.3 Character Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.3.3.1 Basic Char Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.3.3.2 General Escape Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.3.3.3 Control-Character Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.3.3.4 Meta-Character Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.3.3.5 Other Character Modifier Bits . . . . . . . . . . . . . . . . . . . . . . . 13
2.3.4 Symbol Type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
2.3.5 Sequence Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
2.3.6 Cons Cell and List Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
2.3.6.1 Drawing Lists as Box Diagrams . . . . . . . . . . . . . . . . . . . . . . 15
2.3.6.2 Dotted Pair Notation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
2.3.6.3 Association List Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
2.3.7 Array Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
2.3.8 String Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
2.3.8.1 Syntax for Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
2.3.8.2 Non-ASCII Characters in Strings . . . . . . . . . . . . . . . . . . . . . 19
2.3.8.3 Nonprinting Characters in Strings . . . . . . . . . . . . . . . . . . . 19
2.3.8.4 Text Properties in Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
2.3.9 Vector Type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
2.3.10 Char-Table Type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

2.3.11 Bool-Vector Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
iv
2.3.12 Hash Table Type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
2.3.13 Function Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
2.3.14 Macro Type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
2.3.15 Primitive Function Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
2.3.16 Byte-Code Function Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
2.3.17 Autoload Type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
2.4 Editing Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
2.4.1 Buffer Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
2.4.2 Marker Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
2.4.3 Window Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
2.4.4 Frame Type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
2.4.5 Window Configuration Type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
2.4.6 Frame Configuration Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
2.4.7 Process Type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
2.4.8 Stream Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
2.4.9 Keymap Type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
2.4.10 Overlay Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
2.5 Read Syntax for Circular Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
2.6 Type Predicates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
2.7 Equality Predicates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
3 Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
3.1 Integer Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
3.2 Floating Point Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
3.3 Type Predicates for Numbers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
3.4 Comparison of Numbers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
3.5 Numeric Conversions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
3.6 Arithmetic Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
3.7 Rounding Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

3.8 Bitwise Operations on Integers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
3.9 Standard Mathematical Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
3.10 Random Numbers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
4 Strings and Characters. . . . . . . . . . . . . . . . . . . . . . . . 47
4.1 String and Character Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
4.2 The Predicates for Strings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
4.3 Creating Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
4.4 Modifying Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
4.5 Comparison of Characters and Strings . . . . . . . . . . . . . . . . . . . . . . . . . 52
4.6 Conversion of Characters and Strings . . . . . . . . . . . . . . . . . . . . . . . . . . 54
4.7 Formatting Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
4.8 Case Conversion in Lisp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
4.9 The Case Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
v
5 Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
5.1 Lists and Cons Cells . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
5.2 Predicates on Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
5.3 Accessing Elements of Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
5.4 Building Cons Cells and Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
5.5 Modifying List Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
5.6 Modifying Existing List Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
5.6.1 Altering List Elements with setcar . . . . . . . . . . . . . . . . . . . . . . 73
5.6.2 Altering the CDR of a List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
5.6.3 Functions that Rearrange Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
5.7 Using Lists as Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
5.8 Association Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
5.9 Managing a Fixed-Size Ring of Objects . . . . . . . . . . . . . . . . . . . . . . . . 84
6 Sequences, Arrays, and Vectors . . . . . . . . . . . . . . 87
6.1 Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
6.2 Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

6.3 Functions that Operate on Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
6.4 Vectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
6.5 Functions for Vectors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
6.6 Char-Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
6.7 Bool-vectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
7 Hash Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
7.1 Creating Hash Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
7.2 Hash Table Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
7.3 Defining Hash Comparisons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
7.4 Other Hash Table Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
8 Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
8.1 Symbol Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
8.2 Defining Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
8.3 Creating and Interning Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
8.4 Property Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
8.4.1 Property Lists and Association Lists. . . . . . . . . . . . . . . . . . . . . 107
8.4.2 Property List Functions for Symbols . . . . . . . . . . . . . . . . . . . . . 108
8.4.3 Property Lists Outside Symbols . . . . . . . . . . . . . . . . . . . . . . . . . 108
vi
9 Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
9.1 Kinds of Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
9.1.1 Self-Evaluating Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
9.1.2 Symbol Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
9.1.3 Classification of List Forms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
9.1.4 Symbol Function Indirection . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
9.1.5 Evaluation of Function Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
9.1.6 Lisp Macro Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
9.1.7 Special Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
9.1.8 Autoloading. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
9.2 Quoting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

9.3 Eval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
10 Control Structures . . . . . . . . . . . . . . . . . . . . . . . . . . 119
10.1 Sequencing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
10.2 Conditionals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
10.3 Constructs for Combining Conditions . . . . . . . . . . . . . . . . . . . . . . . 122
10.4 Iteration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
10.5 Nonlocal Exits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
10.5.1 Explicit Nonlocal Exits: catch and throw . . . . . . . . . . . . . . 125
10.5.2 Examples of catch and throw . . . . . . . . . . . . . . . . . . . . . . . . . . 126
10.5.3 Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
10.5.3.1 How to Signal an Error. . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
10.5.3.2 How Emacs Processes Errors . . . . . . . . . . . . . . . . . . . . . . 129
10.5.3.3 Writing Code to Handle Errors . . . . . . . . . . . . . . . . . . . . 129
10.5.3.4 Error Symbols and Condition Names . . . . . . . . . . . . . . 132
10.5.4 Cleaning Up from Nonlocal Exits. . . . . . . . . . . . . . . . . . . . . . . 133
11 Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
11.1 Global Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
11.2 Variables that Never Change . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
11.3 Local Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
11.4 When a Variable is “Void” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
11.5 Defining Global Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
11.6 Tips for Defining Variables Robustly . . . . . . . . . . . . . . . . . . . . . . . . 141
11.7 Accessing Variable Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
11.8 How to Alter a Variable Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
11.9 Scoping Rules for Variable Bindings . . . . . . . . . . . . . . . . . . . . . . . . . 145
11.9.1 Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
11.9.2 Extent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
11.9.3 Implementation of Dynamic Scoping . . . . . . . . . . . . . . . . . . . 146
11.9.4 Proper Use of Dynamic Scoping . . . . . . . . . . . . . . . . . . . . . . . . 147
11.10 Buffer-Local Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

11.10.1 Introduction to Buffer-Local Variables. . . . . . . . . . . . . . . . . 148
11.10.2 Creating and Deleting Buffer-Local Bindings . . . . . . . . . . 149
11.10.3 The Default Value of a Buffer-Local Variable . . . . . . . . . . 152
11.11 Frame-Local Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
vii
11.12 Possible Future Local Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
11.13 File Local Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
11.14 Variable Aliases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
11.15 Variables with Restricted Values . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
12 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
12.1 What Is a Function? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
12.2 Lambda Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
12.2.1 Components of a Lambda Expression . . . . . . . . . . . . . . . . . . . 162
12.2.2 A Simple Lambda-Expression Example . . . . . . . . . . . . . . . . . 162
12.2.3 Other Features of Argument Lists . . . . . . . . . . . . . . . . . . . . . . 163
12.2.4 Documentation Strings of Functions . . . . . . . . . . . . . . . . . . . . 164
12.3 Naming a Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
12.4 Defining Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
12.5 Calling Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
12.6 Mapping Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
12.7 Anonymous Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
12.8 Accessing Function Cell Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
12.9 Declaring Functions Obsolete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
12.10 Inline Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
12.11 Determining whether a Function is Safe to Call . . . . . . . . . . . . 174
12.12 Other Topics Related to Functions . . . . . . . . . . . . . . . . . . . . . . . . . 174
13 Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
13.1 A Simple Example of a Macro. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
13.2 Expansion of a Macro Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
13.3 Macros and Byte Compilation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

13.4 Defining Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
13.5 Backquote . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
13.6 Common Problems Using Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
13.6.1 Wrong Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
13.6.2 Evaluating Macro Arguments Repeatedly. . . . . . . . . . . . . . . 180
13.6.3 Local Variables in Macro Expansions . . . . . . . . . . . . . . . . . . . 182
13.6.4 Evaluating Macro Arguments in Expansion . . . . . . . . . . . . . 182
13.6.5 How Many Times is the Macro Expanded? . . . . . . . . . . . . . 183
13.7 Indenting Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
14 Writing Customization Definitions . . . . . . . . 185
14.1 Common Item Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
14.2 Defining Customization Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
14.3 Defining Customization Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
14.4 Customization Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
14.4.1 Simple Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
14.4.2 Composite Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
14.4.3 Splicing into Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
14.4.4 Type Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
14.4.5 Defining New Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
viii
15 Loading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
15.1 How Programs Do Loading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
15.2 Load Suffixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
15.3 Library Search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
15.4 Loading Non-ASCII Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
15.5 Autoload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
15.6 Repeated Loading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
15.7 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
15.8 Which File Defined a Certain Symbol . . . . . . . . . . . . . . . . . . . . . . . 211
15.9 Unloading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

15.10 Hooks for Loading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
16 Byte Compilation . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
16.1 Performance of Byte-Compiled Code . . . . . . . . . . . . . . . . . . . . . . . . 214
16.2 The Compilation Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
16.3 Documentation Strings and Compilation . . . . . . . . . . . . . . . . . . . . 217
16.4 Dynamic Loading of Individual Functions . . . . . . . . . . . . . . . . . . . 218
16.5 Evaluation During Compilation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
16.6 Compiler Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
16.7 Byte-Code Function Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
16.8 Disassembled Byte-Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
17 Advising Emacs Lisp Functions. . . . . . . . . . . . 226
17.1 A Simple Advice Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
17.2 Defining Advice. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
17.3 Around-Advice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
17.4 Computed Advice. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
17.5 Activation of Advice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
17.6 Enabling and Disabling Advice. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
17.7 Preactivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
17.8 Argument Access in Advice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
17.9 Advising Primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
17.10 The Combined Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
18 Debugging Lisp Programs . . . . . . . . . . . . . . . . . . 237
18.1 The Lisp Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
18.1.1 Entering the Debugger on an Error . . . . . . . . . . . . . . . . . . . . . 237
18.1.2 Debugging Infinite Loops. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
18.1.3 Entering the Debugger on a Function Call . . . . . . . . . . . . . . 239
18.1.4 Explicit Entry to the Debugger . . . . . . . . . . . . . . . . . . . . . . . . . 240
18.1.5 Using the Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
18.1.6 Debugger Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
18.1.7 Invoking the Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242

18.1.8 Internals of the Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
18.2 Edebug . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
18.2.1 Using Edebug . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
18.2.2 Instrumenting for Edebug . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
ix
18.2.3 Edebug Execution Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
18.2.4 Jumping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
18.2.5 Miscellaneous Edebug Commands . . . . . . . . . . . . . . . . . . . . . . 249
18.2.6 Breaks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
18.2.6.1 Edebug Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
18.2.6.2 Global Break Condition . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
18.2.6.3 Source Breakpoints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
18.2.7 Trapping Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
18.2.8 Edebug Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
18.2.9 Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
18.2.10 Evaluation List Buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
18.2.11 Printing in Edebug . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
18.2.12 Trace Buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
18.2.13 Coverage Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
18.2.14 The Outside Context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
18.2.14.1 Checking Whether to Stop . . . . . . . . . . . . . . . . . . . . . . . 257
18.2.14.2 Edebug Display Update . . . . . . . . . . . . . . . . . . . . . . . . . . 257
18.2.14.3 Edebug Recursive Edit . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
18.2.15 Edebug and Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
18.2.15.1 Instrumenting Macro Calls . . . . . . . . . . . . . . . . . . . . . . . 258
18.2.15.2 Specification List. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
18.2.15.3 Backtracking in Specifications . . . . . . . . . . . . . . . . . . . . 262
18.2.15.4 Specification Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
18.2.16 Edebug Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
18.3 Debugging Invalid Lisp Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265

18.3.1 Excess Open Parentheses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
18.3.2 Excess Close Parentheses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
18.4 Test Coverage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
18.5 Debugging Problems in Compilation . . . . . . . . . . . . . . . . . . . . . . . . 267
19 Reading and Printing Lisp Objects. . . . . . . . 268
19.1 Introduction to Reading and Printing . . . . . . . . . . . . . . . . . . . . . . . 268
19.2 Input Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
19.3 Input Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
19.4 Output Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
19.5 Output Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
19.6 Variables Affecting Output. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
20 Minibuffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
20.1 Introduction to Minibuffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
20.2 Reading Text Strings with the Minibuffer . . . . . . . . . . . . . . . . . . . 279
20.3 Reading Lisp Objects with the Minibuffer . . . . . . . . . . . . . . . . . . . 281
20.4 Minibuffer History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
20.5 Initial Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
20.6 Completion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
20.6.1 Basic Completion Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
20.6.2 Completion and the Minibuffer . . . . . . . . . . . . . . . . . . . . . . . . . 288
20.6.3 Minibuffer Commands that Do Completion . . . . . . . . . . . . . 289
x
20.6.4 High-Level Completion Functions . . . . . . . . . . . . . . . . . . . . . . 291
20.6.5 Reading File Names. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
20.6.6 Programmed Completion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
20.7 Yes-or-No Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
20.8 Asking Multiple Y-or-N Questions . . . . . . . . . . . . . . . . . . . . . . . . . . 298
20.9 Reading a Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
20.10 Minibuffer Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
20.11 Minibuffer Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300

20.12 Minibuffer Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
20.13 Recursive Minibuffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
20.14 Minibuffer Miscellany . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
21 Command Loop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
21.1 Command Loop Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
21.2 Defining Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
21.2.1 Using interactive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
21.2.2 Code Characters for interactive . . . . . . . . . . . . . . . . . . . . . . 307
21.2.3 Examples of Using interactive . . . . . . . . . . . . . . . . . . . . . . . 309
21.3 Interactive Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
21.4 Information from the Command Loop . . . . . . . . . . . . . . . . . . . . . . . 312
21.5 Adjusting Point After Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
21.6 Input Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
21.6.1 Keyboard Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
21.6.2 Function Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
21.6.3 Mouse Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
21.6.4 Click Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
21.6.5 Drag Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
21.6.6 Button-Down Events. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
21.6.7 Repeat Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
21.6.8 Motion Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
21.6.9 Focus Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
21.6.10 Miscellaneous System Events. . . . . . . . . . . . . . . . . . . . . . . . . . 322
21.6.11 Event Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
21.6.12 Classifying Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
21.6.13 Accessing Events. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
21.6.14 Putting Keyboard Events in Strings . . . . . . . . . . . . . . . . . . . 328
21.7 Reading Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
21.7.1 Key Sequence Input. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
21.7.2 Reading One Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331

21.7.3 Modifying and Translating Input Events. . . . . . . . . . . . . . . . 333
21.7.4 Invoking the Input Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
21.7.5 Quoted Character Input. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
21.7.6 Miscellaneous Event Input Features . . . . . . . . . . . . . . . . . . . . 335
21.8 Special Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
21.9 Waiting for Elapsed Time or Input . . . . . . . . . . . . . . . . . . . . . . . . . . 337
21.10 Quitting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
21.11 Prefix Command Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
21.12 Recursive Editing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
xi
21.13 Disabling Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
21.14 Command History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
21.15 Keyboard Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
22 Keymaps. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
22.1 Key Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
22.2 Keymap Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
22.3 Format of Keymaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
22.4 Creating Keymaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
22.5 Inheritance and Keymaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
22.6 Prefix Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
22.7 Active Keymaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
22.8 Searching the Active Keymaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
22.9 Controlling the Active Keymaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
22.10 Key Lookup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
22.11 Functions for Key Lookup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
22.12 Changing Key Bindings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
22.13 Remapping Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364
22.14 Keymaps for Translating Sequences of Events . . . . . . . . . . . . . . 365
22.15 Commands for Binding Keys. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
22.16 Scanning Keymaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368

22.17 Menu Keymaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
22.17.1 Defining Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
22.17.1.1 Simple Menu Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
22.17.1.2 Extended Menu Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
22.17.1.3 Menu Separators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374
22.17.1.4 Alias Menu Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
22.17.2 Menus and the Mouse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
22.17.3 Menus and the Keyboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
22.17.4 Menu Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
22.17.5 The Menu Bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
22.17.6 Tool bars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
22.17.7 Modifying Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
23 Major and Minor Modes . . . . . . . . . . . . . . . . . . . 382
23.1 Hooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
23.2 Major Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
23.2.1 Major Mode Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
23.2.2 Major Mode Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
23.2.3 How Emacs Chooses a Major Mode . . . . . . . . . . . . . . . . . . . . 388
23.2.4 Getting Help about a Major Mode . . . . . . . . . . . . . . . . . . . . . 390
23.2.5 Defining Derived Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391
23.2.6 Generic Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392
23.2.7 Mode Hooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393
23.2.8 Major Mode Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394
23.3 Minor Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397
23.3.1 Conventions for Writing Minor Modes . . . . . . . . . . . . . . . . . . 397
23.3.2 Keymaps and Minor Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
xii
23.3.3 Defining Minor Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
23.4 Mode-Line Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
23.4.1 Mode Line Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402

23.4.2 The Data Structure of the Mode Line . . . . . . . . . . . . . . . . . . 402
23.4.3 The Top Level of Mode Line Control . . . . . . . . . . . . . . . . . . . 404
23.4.4 Variables Used in the Mode Line . . . . . . . . . . . . . . . . . . . . . . . 405
23.4.5 %-Constructs in the Mode Line . . . . . . . . . . . . . . . . . . . . . . . . . 407
23.4.6 Properties in the Mode Line. . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
23.4.7 Window Header Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
23.4.8 Emulating Mode-Line Formatting . . . . . . . . . . . . . . . . . . . . . . 410
23.5 Imenu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410
23.6 Font Lock Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412
23.6.1 Font Lock Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413
23.6.2 Search-based Fontification. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414
23.6.3 Customizing Search-Based Fontification . . . . . . . . . . . . . . . . 417
23.6.4 Other Font Lock Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418
23.6.5 Levels of Font Lock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419
23.6.6 Precalculated Fontification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419
23.6.7 Faces for Font Lock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419
23.6.8 Syntactic Font Lock. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420
23.6.9 Setting Syntax Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
23.6.10 Multiline Font Lock Constructs . . . . . . . . . . . . . . . . . . . . . . . 422
23.6.10.1 Font Lock Multiline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423
23.6.10.2 Region to Fontify after a Buffer Change . . . . . . . . . . 423
23.7 Desktop Save Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424
24 Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425
24.1 Documentation Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425
24.2 Access to Documentation Strings. . . . . . . . . . . . . . . . . . . . . . . . . . . . 426
24.3 Substituting Key Bindings in Documentation . . . . . . . . . . . . . . . . 428
24.4 Describing Characters for Help Messages . . . . . . . . . . . . . . . . . . . . 429
24.5 Help Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431
25 Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434
25.1 Visiting Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434

25.1.1 Functions for Visiting Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434
25.1.2 Subroutines of Visiting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436
25.2 Saving Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437
25.3 Reading from Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440
25.4 Writing to Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441
25.5 File Locks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442
25.6 Information about Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443
25.6.1 Testing Accessibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443
25.6.2 Distinguishing Kinds of Files . . . . . . . . . . . . . . . . . . . . . . . . . . . 445
25.6.3 Truenames. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446
25.6.4 Other Information about Files. . . . . . . . . . . . . . . . . . . . . . . . . . 447
25.6.5 How to Locate Files in Standard Places . . . . . . . . . . . . . . . . 449
25.7 Changing File Names and Attributes . . . . . . . . . . . . . . . . . . . . . . . . 450
xiii
25.8 File Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453
25.8.1 File Name Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453
25.8.2 Absolute and Relative File Names . . . . . . . . . . . . . . . . . . . . . . 455
25.8.3 Directory Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456
25.8.4 Functions that Expand Filenames . . . . . . . . . . . . . . . . . . . . . . 457
25.8.5 Generating Unique File Names . . . . . . . . . . . . . . . . . . . . . . . . . 459
25.8.6 File Name Completion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461
25.8.7 Standard File Names. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462
25.9 Contents of Directories. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462
25.10 Creating and Deleting Directories . . . . . . . . . . . . . . . . . . . . . . . . . . 464
25.11 Making Certain File Names “Magic” . . . . . . . . . . . . . . . . . . . . . . . 464
25.12 File Format Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468
26 Backups and Auto-Saving . . . . . . . . . . . . . . . . . . 471
26.1 Backup Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471
26.1.1 Making Backup Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471
26.1.2 Backup by Renaming or by Copying?. . . . . . . . . . . . . . . . . . . 473

26.1.3 Making and Deleting Numbered Backup Files . . . . . . . . . . 474
26.1.4 Naming Backup Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474
26.2 Auto-Saving . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 476
26.3 Reverting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479
27 Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481
27.1 Buffer Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481
27.2 The Current Buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481
27.3 Buffer Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484
27.4 Buffer File Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 485
27.5 Buffer Modification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487
27.6 Buffer Modification Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488
27.7 Read-Only Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489
27.8 The Buffer List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490
27.9 Creating Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492
27.10 Killing Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493
27.11 Indirect Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494
27.12 The Buffer Gap. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495
28 Windows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497
28.1 Basic Concepts of Emacs Windows . . . . . . . . . . . . . . . . . . . . . . . . . . 497
28.2 Splitting Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498
28.3 Deleting Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501
28.4 Selecting Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 502
28.5 Cyclic Ordering of Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 503
28.6 Buffers and Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505
28.7 Displaying Buffers in Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 506
28.8 Choosing a Window for Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 508
28.9 Windows and Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 511
28.10 The Window Start Position . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512
xiv
28.11 Textual Scrolling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 515

28.12 Vertical Fractional Scrolling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 518
28.13 Horizontal Scrolling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 518
28.14 The Size of a Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 520
28.15 Changing the Size of a Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . 522
28.16 Coordinates and Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524
28.17 The Window Tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 525
28.18 Window Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526
28.19 Hooks for Window Scrolling and Changes . . . . . . . . . . . . . . . . . . 527
29 Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529
29.1 Creating Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529
29.2 Multiple Displays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 530
29.3 Frame Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 531
29.3.1 Access to Frame Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . 531
29.3.2 Initial Frame Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532
29.3.3 Window Frame Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533
29.3.3.1 Basic Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533
29.3.3.2 Position Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533
29.3.3.3 Size Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534
29.3.3.4 Layout Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534
29.3.3.5 Buffer Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535
29.3.3.6 Window Management Parameters . . . . . . . . . . . . . . . . . 536
29.3.3.7 Cursor Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536
29.3.3.8 Color Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537
29.3.4 Frame Size And Position . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 538
29.3.5 Geometry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 540
29.4 Frame Titles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 540
29.5 Deleting Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 541
29.6 Finding All Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 541
29.7 Frames and Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542
29.8 Minibuffers and Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 543

29.9 Input Focus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 543
29.10 Visibility of Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 545
29.11 Raising and Lowering Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 546
29.12 Frame Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 546
29.13 Mouse Tracking. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547
29.14 Mouse Position . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547
29.15 Pop-Up Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 548
29.16 Dialog Boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 549
29.17 Pointer Shape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 550
29.18 Window System Selections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 550
29.19 Drag and Drop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 552
29.20 Color Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 552
29.21 Text Terminal Colors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 554
29.22 X Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 555
29.23 Display Feature Testing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 555
xv
30 Positions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 559
30.1 Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 559
30.2 Motion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 560
30.2.1 Motion by Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 560
30.2.2 Motion by Words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 561
30.2.3 Motion to an End of the Buffer. . . . . . . . . . . . . . . . . . . . . . . . . 561
30.2.4 Motion by Text Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 562
30.2.5 Motion by Screen Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 564
30.2.6 Moving over Balanced Expressions . . . . . . . . . . . . . . . . . . . . . 566
30.2.7 Skipping Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 567
30.3 Excursions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 568
30.4 Narrowing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 569
31 Markers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 572
31.1 Overview of Markers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 572

31.2 Predicates on Markers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 573
31.3 Functions that Create Markers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 573
31.4 Information from Markers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575
31.5 Marker Insertion Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 576
31.6 Moving Marker Positions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 576
31.7 The Mark . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 577
31.8 The Region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 579
32 Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 581
32.1 Examining Text Near Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 581
32.2 Examining Buffer Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 582
32.3 Comparing Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 584
32.4 Inserting Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 585
32.5 User-Level Insertion Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 586
32.6 Deleting Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 587
32.7 User-Level Deletion Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 589
32.8 The Kill Ring. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 591
32.8.1 Kill Ring Concepts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 591
32.8.2 Functions for Killing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 592
32.8.3 Yanking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 592
32.8.4 Functions for Yanking. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 593
32.8.5 Low-Level Kill Ring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 594
32.8.6 Internals of the Kill Ring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 595
32.9 Undo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 596
32.10 Maintaining Undo Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 598
32.11 Filling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 599
32.12 Margins for Filling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 602
32.13 Adaptive Fill Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 603
32.14 Auto Filling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 604
32.15 Sorting Text. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 605
32.16 Counting Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 609

32.17 Indentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 609
xvi
32.17.1 Indentation Primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 610
32.17.2 Indentation Controlled by Major Mode . . . . . . . . . . . . . . . . 610
32.17.3 Indenting an Entire Region . . . . . . . . . . . . . . . . . . . . . . . . . . . 611
32.17.4 Indentation Relative to Previous Lines . . . . . . . . . . . . . . . . 612
32.17.5 Adjustable “Tab Stops” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 613
32.17.6 Indentation-Based Motion Commands . . . . . . . . . . . . . . . . . 613
32.18 Case Changes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 613
32.19 Text Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 615
32.19.1 Examining Text Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . 615
32.19.2 Changing Text Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 616
32.19.3 Text Property Search Functions . . . . . . . . . . . . . . . . . . . . . . . 618
32.19.4 Properties with Special Meanings . . . . . . . . . . . . . . . . . . . . . 620
32.19.5 Formatted Text Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . 624
32.19.6 Stickiness of Text Properties . . . . . . . . . . . . . . . . . . . . . . . . . . 625
32.19.7 Saving Text Properties in Files . . . . . . . . . . . . . . . . . . . . . . . . 626
32.19.8 Lazy Computation of Text Properties . . . . . . . . . . . . . . . . . 627
32.19.9 Defining Clickable Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 628
32.19.10 Links and Mouse-1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 629
32.19.11 Defining and Using Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . 630
32.19.12 Why Text Properties are not Intervals . . . . . . . . . . . . . . . 632
32.20 Substituting for a Character Code . . . . . . . . . . . . . . . . . . . . . . . . . 633
32.21 Registers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 634
32.22 Transposition of Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 635
32.23 Base 64 Encoding. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 635
32.24 MD5 Checksum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 636
32.25 Atomic Change Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 637
32.26 Change Hooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 638
33 Non-ASCII Characters. . . . . . . . . . . . . . . . . . . . . . 640

33.1 Text Representations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 640
33.2 Converting Text Representations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 641
33.3 Selecting a Representation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 642
33.4 Character Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 643
33.5 Character Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 644
33.6 Characters and Bytes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 645
33.7 Splitting Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 645
33.8 Scanning for Character Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 646
33.9 Translation of Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 647
33.10 Coding Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 648
33.10.1 Basic Concepts of Coding Systems . . . . . . . . . . . . . . . . . . . . 648
33.10.2 Encoding and I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 649
33.10.3 Coding Systems in Lisp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 650
33.10.4 User-Chosen Coding Systems . . . . . . . . . . . . . . . . . . . . . . . . . 652
33.10.5 Default Coding Systems. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 653
33.10.6 Specifying a Coding System for One Operation . . . . . . . . 655
33.10.7 Explicit Encoding and Decoding . . . . . . . . . . . . . . . . . . . . . . 656
33.10.8 Terminal I/O Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 657
33.10.9 MS-DOS File Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 658
xvii
33.11 Input Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 659
33.12 Locales . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 660
34 Searching and Matching. . . . . . . . . . . . . . . . . . . . 661
34.1 Searching for Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 661
34.2 Searching and Case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 663
34.3 Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 663
34.3.1 Syntax of Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . 663
34.3.1.1 Special Characters in Regular Expressions . . . . . . . . . 664
34.3.1.2 Character Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 667
34.3.1.3 Backslash Constructs in Regular Expressions . . . . . . 668

34.3.2 Complex Regexp Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671
34.3.3 Regular Expression Functions . . . . . . . . . . . . . . . . . . . . . . . . . . 672
34.4 Regular Expression Searching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 673
34.5 POSIX Regular Expression Searching . . . . . . . . . . . . . . . . . . . . . . . 676
34.6 The Match Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 676
34.6.1 Replacing the Text that Matched. . . . . . . . . . . . . . . . . . . . . . . 676
34.6.2 Simple Match Data Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 677
34.6.3 Accessing the Entire Match Data . . . . . . . . . . . . . . . . . . . . . . . 679
34.6.4 Saving and Restoring the Match Data . . . . . . . . . . . . . . . . . . 680
34.7 Search and Replace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 681
34.8 Standard Regular Expressions Used in Editing . . . . . . . . . . . . . . 683
35 Syntax Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 684
35.1 Syntax Table Concepts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 684
35.2 Syntax Descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 684
35.2.1 Table of Syntax Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 685
35.2.2 Syntax Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 687
35.3 Syntax Table Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 688
35.4 Syntax Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 690
35.5 Motion and Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 691
35.6 Parsing Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 691
35.6.1 Motion Commands Based on Parsing . . . . . . . . . . . . . . . . . . . 692
35.6.2 Finding the Parse State for a Position . . . . . . . . . . . . . . . . . . 692
35.6.3 Parser State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 693
35.6.4 Low-Level Parsing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 694
35.6.5 Parameters to Control Parsing . . . . . . . . . . . . . . . . . . . . . . . . . 695
35.7 Some Standard Syntax Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 695
35.8 Syntax Table Internals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 695
35.9 Categories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 696
36 Abbrevs and Abbrev Expansion . . . . . . . . . . . 699
36.1 Setting Up Abbrev Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 699

36.2 Abbrev Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 699
36.3 Defining Abbrevs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 700
36.4 Saving Abbrevs in Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 701
36.5 Looking Up and Expanding Abbreviations . . . . . . . . . . . . . . . . . . 702
36.6 Standard Abbrev Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 704
xviii
37 Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 705
37.1 Functions that Create Subprocesses . . . . . . . . . . . . . . . . . . . . . . . . . 705
37.2 Shell Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 706
37.3 Creating a Synchronous Process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 707
37.4 Creating an Asynchronous Process . . . . . . . . . . . . . . . . . . . . . . . . . . 710
37.5 Deleting Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 712
37.6 Process Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 712
37.7 Sending Input to Processes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 714
37.8 Sending Signals to Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 715
37.9 Receiving Output from Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . 717
37.9.1 Process Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 717
37.9.2 Process Filter Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 718
37.9.3 Decoding Process Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 720
37.9.4 Accepting Output from Processes . . . . . . . . . . . . . . . . . . . . . . 721
37.10 Sentinels: Detecting Process Status Changes . . . . . . . . . . . . . . . 721
37.11 Querying Before Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 723
37.12 Transaction Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 723
37.13 Network Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 724
37.14 Network Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 726
37.15 Datagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 726
37.16 Low-Level Network Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 727
37.16.1 make-network-process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 727
37.16.2 Network Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 729
37.16.3 Testing Availability of Network Features . . . . . . . . . . . . . . 730

37.17 Misc Network Facilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 731
37.18 Packing and Unpacking Byte Arrays . . . . . . . . . . . . . . . . . . . . . . . 732
37.18.1 Describing Data Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 732
37.18.2 Functions to Unpack and Pack Bytes . . . . . . . . . . . . . . . . . . 734
37.18.3 Examples of Byte Unpacking and Packing . . . . . . . . . . . . . 735
38 Emacs Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 739
38.1 Refreshing the Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 739
38.2 Forcing Redisplay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 739
38.3 Truncation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 740
38.4 The Echo Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 741
38.4.1 Displaying Messages in the Echo Area . . . . . . . . . . . . . . . . . . 741
38.4.2 Reporting Operation Progress . . . . . . . . . . . . . . . . . . . . . . . . . . 743
38.4.3 Logging Messages in ‘*Messages*’. . . . . . . . . . . . . . . . . . . . . . 744
38.4.4 Echo Area Customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 745
38.5 Reporting Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 745
38.5.1 Warning Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 746
38.5.2 Warning Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 746
38.5.3 Warning Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 748
38.6 Invisible Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 748
38.7 Selective Display. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 750
38.8 Temporary Displays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 752
38.9 Overlays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 754
38.9.1 Managing Overlays. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 754
xix
38.9.2 Overlay Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 756
38.9.3 Searching for Overlays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 759
38.10 Width . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 760
38.11 Line Height. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 761
38.12 Faces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 762
38.12.1 Defining Faces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 763

38.12.2 Face Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 765
38.12.3 Face Attribute Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 767
38.12.4 Displaying Faces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 770
38.12.5 Font Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 771
38.12.6 Functions for Working with Faces . . . . . . . . . . . . . . . . . . . . . 772
38.12.7 Automatic Face Assignment. . . . . . . . . . . . . . . . . . . . . . . . . . . 773
38.12.8 Looking Up Fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 773
38.12.9 Fontsets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 774
38.13 Fringes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 776
38.13.1 Fringe Size and Position . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 776
38.13.2 Fringe Indicators. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 777
38.13.3 Fringe Cursors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 779
38.13.4 Fringe Bitmaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 779
38.13.5 Customizing Fringe Bitmaps . . . . . . . . . . . . . . . . . . . . . . . . . . 780
38.13.6 The Overlay Arrow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 780
38.14 Scroll Bars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 781
38.15 The display Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 783
38.15.1 Specified Spaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 783
38.15.2 Pixel Specification for Spaces . . . . . . . . . . . . . . . . . . . . . . . . . 784
38.15.3 Other Display Specifications . . . . . . . . . . . . . . . . . . . . . . . . . . 785
38.15.4 Displaying in the Margins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 786
38.16 Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 787
38.16.1 Image Descriptors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 788
38.16.2 XBM Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 791
38.16.3 XPM Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 792
38.16.4 GIF Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 792
38.16.5 PostScript Images. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 792
38.16.6 Other Image Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 792
38.16.7 Defining Images. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 793
38.16.8 Showing Images. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 795

38.16.9 Image Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 796
38.17 Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 796
38.17.1 Button Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 797
38.17.2 Button Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 798
38.17.3 Making Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 798
38.17.4 Manipulating Buttons. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 799
38.17.5 Button Buffer Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 800
38.18 Abstract Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 800
38.18.1 Abstract Display Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 801
38.18.2 Abstract Display Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . 803
38.19 Blinking Parentheses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 805
38.20 Usual Display Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 806
xx
38.21 Display Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 807
38.21.1 Display Table Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 807
38.21.2 Active Display Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 809
38.21.3 Glyphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 809
38.22 Beeping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 810
38.23 Window Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 811
39 Operating System Interface . . . . . . . . . . . . . . . . 812
39.1 Starting Up Emacs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 812
39.1.1 Summary: Sequence of Actions at Startup . . . . . . . . . . . . . . 812
39.1.2 The Init File, ‘.emacs’ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 813
39.1.3 Terminal-Specific Initialization . . . . . . . . . . . . . . . . . . . . . . . . . 814
39.1.4 Command-Line Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 815
39.2 Getting Out of Emacs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 817
39.2.1 Killing Emacs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 817
39.2.2 Suspending Emacs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 817
39.3 Operating System Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 819
39.4 User Identification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 822

39.5 Time of Day . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 824
39.6 Time Conversion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 825
39.7 Parsing and Formatting Times . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 826
39.8 Processor Run time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 828
39.9 Time Calculations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 828
39.10 Timers for Delayed Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 829
39.11 Idle Timers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 831
39.12 Terminal Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 832
39.12.1 Input Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 832
39.12.2 Recording Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 833
39.13 Terminal Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 834
39.14 Sound Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 835
39.15 Operating on X11 Keysyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 835
39.16 Batch Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 836
39.17 Session Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 836
Appendix A Emacs 21 Antinews . . . . . . . . . . . . . 838
A.1 Old Lisp Features in Emacs 21 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 838
Appendix B GNU Free Documentation License
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 843
ADDENDUM: How to use this License for your documents . . . . . . . . 849
Appendix C GNU General Public License. . . 850
Preamble . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 850
Terms and Conditions for Copying, Distribution and Modification . . 851
How to Apply These Terms to Your New Programs . . . . . . . . . . . . . . . . 855
xxi
Appendix D Tips and Conventions . . . . . . . . . . . 856
D.1 Emacs Lisp Coding Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 856
D.2 Key Binding Conventions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 859
D.3 Emacs Programming Tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 860
D.4 Tips for Making Compiled Code Fast . . . . . . . . . . . . . . . . . . . . . . . . 861

D.5 Tips for Avoiding Compiler Warnings. . . . . . . . . . . . . . . . . . . . . . . . 862
D.6 Tips for Documentation Strings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 862
D.7 Tips on Writing Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 865
D.8 Conventional Headers for Emacs Libraries . . . . . . . . . . . . . . . . . . . 867
Appendix E GNU Emacs Internals . . . . . . . . . . 870
E.1 Building Emacs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 870
E.2 Pure Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 871
E.3 Garbage Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 872
E.4 Memory Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 875
E.5 Writing Emacs Primitives. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 876
E.6 Object Internals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 880
E.6.1 Buffer Internals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 880
E.6.2 Window Internals. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 886
E.6.3 Process Internals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 889
Appendix F Standard Errors . . . . . . . . . . . . . . . . . 891
Appendix G Buffer-Local Variables . . . . . . . . . . 895
Appendix H Standard Keymaps . . . . . . . . . . . . . . 899
Appendix I Standard Hooks . . . . . . . . . . . . . . . . . 903
Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 908
Chapter 1: Introduction 1
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 introduc-
tion 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 coun-
terparts in many programming languages, and later chapters describe features that are
peculiar to Emacs Lisp or relate specifically to editing.
This is edition 2.9 of the GNU Emacs Lisp Reference Manual, corresponding to Emacs
version 22.1.
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. This
includes most information about usage on VMS.
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 mark pages with corrections so you can later
look them up and send them to us. 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 chapter name, section name, and function name, as appropriate, since
page numbers and chapter and section numbers will change and we may have trouble finding
the text you are talking about. Also state the number of the edition you are criticizing.
Please mail comments and corrections to

We let mail to this list accumulate unread until someone decides to apply the corrections.

Months, and sometimes years, go by between updates. So please attach no significance to
the lack of a reply—your mail will be acted on in due time. If you want to contact the
Emacs maintainers more quickly, send mail to
Chapter 1: Introduction 2
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 id-
iosyncrasies. 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 to-
gether 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. See Info
file ‘cl’, node ‘Top’.
Emacs Lisp is not at all influenced by Scheme; but the GNU project has an imple-
mentation of Scheme, called Guile. We use Guile in all new GNU software that calls for
extensibility.
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.
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. See Section 2.1 [Printed Representation], page 8, 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.
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.