GNU Emacs Lisp Reference ManualFor Emacs Version 22.1Revision 2.9, April 2007

by Bil Lewis, Dan LaLiberte, Richard Stallmanand 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 underthe terms of the GNU Free Documentation License, Version 1.2 or any laterversion published by the Free Software Foundation; with the Invariant Sectionsbeing GNU General Public License, with the Front-Cover texts being AGNU Manual, and with the Back-Cover Texts as in (a) below. A copy of thelicense is included in the section entitled GNU Free Documentation License.(a) The FSFs Back-Cover Text is: You have freedom to copy and modifythis GNU Manual, like GNU software. Copies published by the Free SoftwareFoundation raise funds for GNU development.

Published by the Free Software Foundation51 Franklin St, Fifth FloorBoston, MA 02110-1301USAISBN 1-882114-74-4

Cover art by Etienne Suvasa.

iShort Contents

1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 Lisp Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324 Strings and Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475 Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 636 Sequences, Arrays, and Vectors . . . . . . . . . . . . . . . . . . . . . . . . . 877 Hash Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 978 Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1029 Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11010 Control Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11911 Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13512 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16013 Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17614 Writing Customization Definitions . . . . . . . . . . . . . . . . . . . . . . 18515 Loading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20116 Byte Compilation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21417 Advising Emacs Lisp Functions . . . . . . . . . . . . . . . . . . . . . . . . 22618 Debugging Lisp Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23719 Reading and Printing Lisp Objects . . . . . . . . . . . . . . . . . . . . . 26820 Minibuffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27821 Command Loop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30422 Keymaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34723 Major and Minor Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38224 Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42525 Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43426 Backups and Auto-Saving . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47127 Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48128 Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49729 Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52930 Positions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55931 Markers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57232 Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58133 Non-ASCII Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64034 Searching and Matching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66135 Syntax Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 684

ii

36 Abbrevs and Abbrev Expansion . . . . . . . . . . . . . . . . . . . . . . . . 69937 Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70538 Emacs Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73939 Operating System Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . 812A Emacs 21 Antinews . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 838B GNU Free Documentation License . . . . . . . . . . . . . . . . . . . . . . 843C GNU General Public License . . . . . . . . . . . . . . . . . . . . . . . . . . 850D Tips and Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 856E GNU Emacs Internals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 870F Standard Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 891G Buffer-Local Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 895H Standard Keymaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 899I Standard Hooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 903Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 908

iii

Table of Contents

1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.1 Caveats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.2 Lisp History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21.3 Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

1.3.1 Some Terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21.3.2 nil and t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21.3.3 Evaluation Notation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.3.4 Printing Notation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.3.5 Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.3.6 Buffer Text Notation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.3.7 Format of Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

1.3.7.1 A Sample Function Description . . . . . . . . . . . . . . . . . . . . . . . 41.3.7.2 A Sample Variable Description . . . . . . . . . . . . . . . . . . . . . . . . 6

1.4 Version Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61.5 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

2 Lisp Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82.1 Printed Representation and Read Syntax . . . . . . . . . . . . . . . . . . . . . . . 82.2 Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92.3 Programming Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

2.3.1 Integer Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92.3.2 Floating Point Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102.3.3 Character Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

2.3.3.1 Basic Char Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102.3.3.2 General Escape Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112.3.3.3 Control-Character Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . 122.3.3.4 Meta-Character Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122.3.3.5 Other Character Modifier Bits . . . . . . . . . . . . . . . . . . . . . . . 13

2.3.4 Symbol Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132.3.5 Sequence Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142.3.6 Cons Cell and List Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

2.3.6.1 Drawing Lists as Box Diagrams . . . . . . . . . . . . . . . . . . . . . . 152.3.6.2 Dotted Pair Notation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162.3.6.3 Association List Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

2.3.7 Array Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182.3.8 String Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

2.3.8.1 Syntax for Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182.3.8.2 Non-ASCII Characters in Strings . . . . . . . . . . . . . . . . . . . . . 192.3.8.3 Nonprinting Characters in Strings . . . . . . . . . . . . . . . . . . . 192.3.8.4 Text Properties in Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

2.3.9 Vector Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202.3.10 Char-Table Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202.3.11 Bool-Vector Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

iv

2.3.12 Hash Table Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212.3.13 Function Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212.3.14 Macro Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222.3.15 Primitive Function Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222.3.16 Byte-Code Function Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222.3.17 Autoload Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

2.4 Editing Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232.4.1 Buffer Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232.4.2 Marker Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242.4.3 Window Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242.4.4 Frame Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252.4.5 Window Configuration Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252.4.6 Frame Configuration Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252.4.7 Process Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252.4.8 Stream Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252.4.9 Keymap Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262.4.10 Overlay Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

2.5 Read Syntax for Circular Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262.6 Type Predicates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272.7 Equality Predicates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

3 Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323.1 Integer Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323.2 Floating Point Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333.3 Type Predicates for Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343.4 Comparison of Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353.5 Numeric Conversions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363.6 Arithmetic Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383.7 Rounding Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403.8 Bitwise Operations on Integers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413.9 Standard Mathematical Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443.10 Random Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

4 Strings and Characters . . . . . . . . . . . . . . . . . . . . . . . . 474.1 String and Character Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474.2 The Predicates for Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484.3 Creating Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484.4 Modifying Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 514.5 Comparison of Characters and Strings . . . . . . . . . . . . . . . . . . . . . . . . . 524.6 Conversion of Characters and Strings . . . . . . . . . . . . . . . . . . . . . . . . . . 544.7 Formatting Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 564.8 Case Conversion in Lisp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 584.9 The Case Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

v5 Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 635.1 Lists and Cons Cells . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 635.2 Predicates on Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 645.3 Accessing Elements of Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 645.4 Building Cons Cells and Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 675.5 Modifying List Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 715.6 Modifying Existing List Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

5.6.1 Altering List Elements with setcar . . . . . . . . . . . . . . . . . . . . . . 735.6.2 Altering the CDR of a List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 745.6.3 Functions that Rearrange Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

5.7 Using Lists as Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 785.8 Association Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 815.9 Managing a Fixed-Size Ring of Objects . . . . . . . . . . . . . . . . . . . . . . . . 84

6 Sequences, Arrays, and Vectors . . . . . . . . . . . . . . 876.1 Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 876.2 Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 896.3 Functions that Operate on Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 906.4 Vectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 916.5 Functions for Vectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 926.6 Char-Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 936.7 Bool-vectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

7 Hash Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 977.1 Creating Hash Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 977.2 Hash Table Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 997.3 Defining Hash Comparisons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 997.4 Other Hash Table Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

8 Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1028.1 Symbol Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1028.2 Defining Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1038.3 Creating and Interning Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1048.4 Property Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

8.4.1 Property Lists and Association Lists . . . . . . . . . . . . . . . . . . . . . 1078.4.2 Property List Functions for Symbols . . . . . . . . . . . . . . . . . . . . . 1088.4.3 Property Lists Outside Symbols . . . . . . . . . . . . . . . . . . . . . . . . . 108

vi

9 Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1109.1 Kinds of Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

9.1.1 Self-Evaluating Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1119.1.2 Symbol Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1119.1.3 Classification of List Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1129.1.4 Symbol Function Indirection . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1129.1.5 Evaluation of Function Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . 1139.1.6 Lisp Macro Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1139.1.7 Special Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1149.1.8 Autoloading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

9.2 Quoting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1159.3 Eval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

10 Control Structures . . . . . . . . . . . . . . . . . . . . . . . . . . 11910.1 Sequencing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11910.2 Conditionals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12010.3 Constructs for Combining Conditions . . . . . . . . . . . . . . . . . . . . . . . 12210.4 Iteration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12410.5 Nonlocal Exits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

10.5.1 Explicit Nonlocal Exits: catch and throw . . . . . . . . . . . . . . 12510.5.2 Examples of catch and throw . . . . . . . . . . . . . . . . . . . . . . . . . . 12610.5.3 Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

10.5.3.1 How to Signal an Error . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12810.5.3.2 How Emacs Processes Errors . . . . . . . . . . . . . . . . . . . . . . 12910.5.3.3 Writing Code to Handle Errors . . . . . . . . . . . . . . . . . . . . 12910.5.3.4 Error Symbols and Condition Names . . . . . . . . . . . . . . 132

10.5.4 Cleaning Up from Nonlocal Exits . . . . . . . . . . . . . . . . . . . . . . . 133

11 Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13511.1 Global Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13511.2 Variables that Never Change . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13511.3 Local Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13611.4 When a Variable is Void . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13811.5 Defining Global Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13911.6 Tips for Defining Variables Robustly . . . . . . . . . . . . . . . . . . . . . . . . 14111.7 Accessing Variable Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14311.8 How to Alter a Variable Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14311.9 Scoping Rules for Variable Bindings . . . . . . . . . . . . . . . . . . . . . . . . . 145

11.9.1 Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14511.9.2 Extent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14611.9.3 Implementation of Dynamic Scoping . . . . . . . . . . . . . . . . . . . 14611.9.4 Proper Use of Dynamic Scoping . . . . . . . . . . . . . . . . . . . . . . . . 147

11.10 Buffer-Local Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14711.10.1 Introduction to Buffer-Local Variables . . . . . . . . . . . . . . . . . 14811.10.2 Creating and Deleting Buffer-Local Bindings . . . . . . . . . . 14911.10.3 The Default Value of a Buffer-Local Variable . . . . . . . . . . 152

11.11 Frame-Local Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

vii

11.12 Possible Future Local Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15511.13 File Local Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15511.14 Variable Aliases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15711.15 Variables with Restricted Values . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

12 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16012.1 What Is a Function? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16012.2 Lambda Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

12.2.1 Components of a Lambda Expression . . . . . . . . . . . . . . . . . . . 16212.2.2 A Simple Lambda-Expression Example . . . . . . . . . . . . . . . . . 16212.2.3 Other Features of Argument Lists . . . . . . . . . . . . . . . . . . . . . . 16312.2.4 Documentation Strings of Functions . . . . . . . . . . . . . . . . . . . . 164

12.3 Naming a Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16512.4 Defining Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16512.5 Calling Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16712.6 Mapping Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16812.7 Anonymous Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17012.8 Accessing Function Cell Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . 17112.9 Declaring Functions Obsolete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17312.10 Inline Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17312.11 Determining whether a Function is Safe to Call . . . . . . . . . . . . 17412.12 Other Topics Related to Functions . . . . . . . . . . . . . . . . . . . . . . . . . 174

13 Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17613.1 A Simple Example of a Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17613.2 Expansion of a Macro Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17613.3 Macros and Byte Compilation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17713.4 Defining Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17813.5 Backquote . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17913.6 Common Problems Using Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . 180

13.6.1 Wrong Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18013.6.2 Evaluating Macro Arguments Repeatedly . . . . . . . . . . . . . . . 18013.6.3 Local Variables in Macro Expansions . . . . . . . . . . . . . . . . . . . 18213.6.4 Evaluating Macro Arguments in Expansion . . . . . . . . . . . . . 18213.6.5 How Many Times is the Macro Expanded? . . . . . . . . . . . . . 183

13.7 Indenting Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184

14 Writing Customization Definitions . . . . . . . . 18514.1 Common Item Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18514.2 Defining Customization Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18714.3 Defining Customization Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . 18814.4 Customization Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

14.4.1 Simple Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19114.4.2 Composite Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19414.4.3 Splicing into Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19714.4.4 Type Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19814.4.5 Defining New Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199

viii

15 Loading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20115.1 How Programs Do Loading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20115.2 Load Suffixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20315.3 Library Search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20315.4 Loading Non-ASCII Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20515.5 Autoload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20615.6 Repeated Loading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20815.7 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20915.8 Which File Defined a Certain Symbol . . . . . . . . . . . . . . . . . . . . . . . 21115.9 Unloading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21115.10 Hooks for Loading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

16 Byte Compilation . . . . . . . . . . . . . . . . . . . . . . . . . . . 21416.1 Performance of Byte-Compiled Code . . . . . . . . . . . . . . . . . . . . . . . . 21416.2 The Compilation Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21516.3 Documentation Strings and Compilation . . . . . . . . . . . . . . . . . . . . 21716.4 Dynamic Loading of Individual Functions . . . . . . . . . . . . . . . . . . . 21816.5 Evaluation During Compilation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21916.6 Compiler Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22016.7 Byte-Code Function Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22016.8 Disassembled Byte-Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221

17 Advising Emacs Lisp Functions . . . . . . . . . . . . 22617.1 A Simple Advice Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22617.2 Defining Advice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22717.3 Around-Advice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22917.4 Computed Advice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23017.5 Activation of Advice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23017.6 Enabling and Disabling Advice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23217.7 Preactivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23217.8 Argument Access in Advice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23317.9 Advising Primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23417.10 The Combined Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235

18 Debugging Lisp Programs . . . . . . . . . . . . . . . . . . 23718.1 The Lisp Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237

18.1.1 Entering the Debugger on an Error . . . . . . . . . . . . . . . . . . . . . 23718.1.2 Debugging Infinite Loops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23918.1.3 Entering the Debugger on a Function Call . . . . . . . . . . . . . . 23918.1.4 Explicit Entry to the Debugger . . . . . . . . . . . . . . . . . . . . . . . . . 24018.1.5 Using the Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24018.1.6 Debugger Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24118.1.7 Invoking the Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24218.1.8 Internals of the Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243

18.2 Edebug . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24518.2.1 Using Edebug . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24618.2.2 Instrumenting for Edebug . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247

ix

18.2.3 Edebug Execution Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24718.2.4 Jumping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24918.2.5 Miscellaneous Edebug Commands . . . . . . . . . . . . . . . . . . . . . . 24918.2.6 Breaks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250

18.2.6.1 Edebug Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25018.2.6.2 Global Break Condition . . . . . . . . . . . . . . . . . . . . . . . . . . . 25118.2.6.3 Source Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251

18.2.7 Trapping Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25218.2.8 Edebug Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25218.2.9 Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25318.2.10 Evaluation List Buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25318.2.11 Printing in Edebug . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25418.2.12 Trace Buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25518.2.13 Coverage Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25618.2.14 The Outside Context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257

18.2.14.1 Checking Whether to Stop . . . . . . . . . . . . . . . . . . . . . . . 25718.2.14.2 Edebug Display Update . . . . . . . . . . . . . . . . . . . . . . . . . . 25718.2.14.3 Edebug Recursive Edit . . . . . . . . . . . . . . . . . . . . . . . . . . . 258

18.2.15 Edebug and Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25818.2.15.1 Instrumenting Macro Calls . . . . . . . . . . . . . . . . . . . . . . . 25818.2.15.2 Specification List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25918.2.15.3 Backtracking in Specifications . . . . . . . . . . . . . . . . . . . . 26218.2.15.4 Specification Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 263

18.2.16 Edebug Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26318.3 Debugging Invalid Lisp Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265

18.3.1 Excess Open Parentheses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26518.3.2 Excess Close Parentheses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266

18.4 Test Coverage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26618.5 Debugging Problems in Compilation . . . . . . . . . . . . . . . . . . . . . . . . 267

19 Reading and Printing Lisp Objects . . . . . . . . 26819.1 Introduction to Reading and Printing . . . . . . . . . . . . . . . . . . . . . . . 26819.2 Input Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26819.3 Input Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27119.4 Output Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27119.5 Output Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27319.6 Variables Affecting Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276

20 Minibuffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27820.1 Introduction to Minibuffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27820.2 Reading Text Strings with the Minibuffer . . . . . . . . . . . . . . . . . . . 27920.3 Reading Lisp Objects with the Minibuffer . . . . . . . . . . . . . . . . . . . 28120.4 Minibuffer History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28220.5 Initial Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28420.6 Completion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285

20.6.1 Basic Completion Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28520.6.2 Completion and the Minibuffer . . . . . . . . . . . . . . . . . . . . . . . . . 28820.6.3 Minibuffer Commands that Do Completion . . . . . . . . . . . . . 289

x20.6.4 High-Level Completion Functions . . . . . . . . . . . . . . . . . . . . . . 29120.6.5 Reading File Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29320.6.6 Programmed Completion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296

20.7 Yes-or-No Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29620.8 Asking Multiple Y-or-N Questions . . . . . . . . . . . . . . . . . . . . . . . . . . 29820.9 Reading a Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29920.10 Minibuffer Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30020.11 Minibuffer Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30020.12 Minibuffer Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30120.13 Recursive Minibuffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30220.14 Minibuffer Miscellany . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302

21 Command Loop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30421.1 Command Loop Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30421.2 Defining Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305

21.2.1 Using interactive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30521.2.2 Code Characters for interactive . . . . . . . . . . . . . . . . . . . . . . 30721.2.3 Examples of Using interactive . . . . . . . . . . . . . . . . . . . . . . . 309

21.3 Interactive Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31021.4 Information from the Command Loop . . . . . . . . . . . . . . . . . . . . . . . 31221.5 Adjusting Point After Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . 31521.6 Input Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315

21.6.1 Keyboard Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31521.6.2 Function Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31621.6.3 Mouse Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31721.6.4 Click Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31821.6.5 Drag Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31921.6.6 Button-Down Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32021.6.7 Repeat Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32021.6.8 Motion Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32121.6.9 Focus Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32221.6.10 Miscellaneous System Events . . . . . . . . . . . . . . . . . . . . . . . . . . 32221.6.11 Event Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32421.6.12 Classifying Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32421.6.13 Accessing Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32621.6.14 Putting Keyboard Events in Strings . . . . . . . . . . . . . . . . . . . 328

21.7 Reading Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32921.7.1 Key Sequence Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33021.7.2 Reading One Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33121.7.3 Modifying and Translating Input Events . . . . . . . . . . . . . . . . 33321.7.4 Invoking the Input Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33421.7.5 Quoted Character Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33521.7.6 Miscellaneous Event Input Features . . . . . . . . . . . . . . . . . . . . 335

21.8 Special Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33721.9 Waiting for Elapsed Time or Input . . . . . . . . . . . . . . . . . . . . . . . . . . 33721.10 Quitting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33821.11 Prefix Command Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34021.12 Recursive Editing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342

xi

21.13 Disabling Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34421.14 Command History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34421.15 Keyboard Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345

22 Keymaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34722.1 Key Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34722.2 Keymap Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34822.3 Format of Keymaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34822.4 Creating Keymaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35022.5 Inheritance and Keymaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35122.6 Prefix Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35222.7 Active Keymaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35322.8 Searching the Active Keymaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35522.9 Controlling the Active Keymaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35622.10 Key Lookup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35822.11 Functions for Key Lookup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36022.12 Changing Key Bindings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36122.13 Remapping Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36422.14 Keymaps for Translating Sequences of Events . . . . . . . . . . . . . . 36522.15 Commands for Binding Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36722.16 Scanning Keymaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36822.17 Menu Keymaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370

22.17.1 Defining Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37022.17.1.1 Simple Menu Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37122.17.1.2 Extended Menu Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37222.17.1.3 Menu Separators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37422.17.1.4 Alias Menu Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375

22.17.2 Menus and the Mouse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37522.17.3 Menus and the Keyboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37622.17.4 Menu Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37622.17.5 The Menu Bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37722.17.6 Tool bars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37822.17.7 Modifying Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381

23 Major and Minor Modes . . . . . . . . . . . . . . . . . . . 38223.1 Hooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38223.2 Major Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384

23.2.1 Major Mode Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38423.2.2 Major Mode Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38523.2.3 How Emacs Chooses a Major Mode . . . . . . . . . . . . . . . . . . . . 38823.2.4 Getting Help about a Major Mode . . . . . . . . . . . . . . . . . . . . . 39023.2.5 Defining Derived Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39123.2.6 Generic Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39223.2.7 Mode Hooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39323.2.8 Major Mode Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394

23.3 Minor Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39723.3.1 Conventions for Writing Minor Modes . . . . . . . . . . . . . . . . . . 39723.3.2 Keymaps and Minor Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399

xii

23.3.3 Defining Minor Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39923.4 Mode-Line Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402

23.4.1 Mode Line Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40223.4.2 The Data Structure of the Mode Line . . . . . . . . . . . . . . . . . . 40223.4.3 The Top Level of Mode Line Control . . . . . . . . . . . . . . . . . . . 40423.4.4 Variables Used in the Mode Line . . . . . . . . . . . . . . . . . . . . . . . 40523.4.5 %-Constructs in the Mode Line . . . . . . . . . . . . . . . . . . . . . . . . . 40723.4.6 Properties in the Mode Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40923.4.7 Window Header Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40923.4.8 Emulating Mode-Line Formatting . . . . . . . . . . . . . . . . . . . . . . 410

23.5 Imenu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41023.6 Font Lock Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412

23.6.1 Font Lock Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41323.6.2 Search-based Fontification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41423.6.3 Customizing Search-Based Fontification . . . . . . . . . . . . . . . . 41723.6.4 Other Font Lock Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41823.6.5 Levels of Font Lock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41923.6.6 Precalculated Fontification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41923.6.7 Faces for Font Lock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41923.6.8 Syntactic Font Lock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42023.6.9 Setting Syntax Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42123.6.10 Multiline Font Lock Constructs . . . . . . . . . . . . . . . . . . . . . . . 422

23.6.10.1 Font Lock Multiline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42323.6.10.2 Region to Fontify after a Buffer Change . . . . . . . . . . 423

23.7 Desktop Save Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424

24 Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42524.1 Documentation Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42524.2 Access to Documentation Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42624.3 Substituting Key Bindings in Documentation . . . . . . . . . . . . . . . . 42824.4 Describing Characters for Help Messages . . . . . . . . . . . . . . . . . . . . 42924.5 Help Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431

25 Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43425.1 Visiting Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434

25.1.1 Functions for Visiting Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43425.1.2 Subroutines of Visiting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436

25.2 Saving Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43725.3 Reading from Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44025.4 Writing to Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44125.5 File Locks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44225.6 Information about Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443

25.6.1 Testing Accessibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44325.6.2 Distinguishing Kinds of Files . . . . . . . . . . . . . . . . . . . . . . . . . . . 44525.6.3 Truenames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44625.6.4 Other Information about Files . . . . . . . . . . . . . . . . . . . . . . . . . . 44725.6.5 How to Locate Files in Standard Places . . . . . . . . . . . . . . . . 449

25.7 Changing File Names and Attributes . . . . . . . . . . . . . . . . . . . . . . . . 450

xiii

25.8 File Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45325.8.1 File Name Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45325.8.2 Absolute and Relative File Names . . . . . . . . . . . . . . . . . . . . . . 45525.8.3 Directory Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45625.8.4 Functions that Expand Filenames . . . . . . . . . . . . . . . . . . . . . . 45725.8.5 Generating Unique File Names . . . . . . . . . . . . . . . . . . . . . . . . . 45925.8.6 File Name Completion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46125.8.7 Standard File Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462

25.9 Contents of Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46225.10 Creating and Deleting Directories . . . . . . . . . . . . . . . . . . . . . . . . . . 46425.11 Making Certain File Names Magic . . . . . . . . . . . . . . . . . . . . . . . 46425.12 File Format Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468

26 Backups and Auto-Saving . . . . . . . . . . . . . . . . . . 47126.1 Backup Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471

26.1.1 Making Backup Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47126.1.2 Backup by Renaming or by Copying? . . . . . . . . . . . . . . . . . . . 47326.1.3 Making and Deleting Numbered Backup Files . . . . . . . . . . 47426.1.4 Naming Backup Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474

26.2 Auto-Saving . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47626.3 Reverting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479

27 Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48127.1 Buffer Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48127.2 The Current Buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48127.3 Buffer Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48427.4 Buffer File Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48527.5 Buffer Modification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48727.6 Buffer Modification Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48827.7 Read-Only Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48927.8 The Buffer List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49027.9 Creating Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49227.10 Killing Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49327.11 Indirect Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49427.12 The Buffer Gap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495

28 Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49728.1 Basic Concepts of Emacs Windows . . . . . . . . . . . . . . . . . . . . . . . . . . 49728.2 Splitting Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49828.3 Deleting Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50128.4 Selecting Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50228.5 Cyclic Ordering of Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50328.6 Buffers and Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50528.7 Displaying Buffers in Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50628.8 Choosing a Window for Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50828.9 Windows and Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51128.10 The Window Start Position . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512

xiv

28.11 Textual Scrolling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51528.12 Vertical Fractional Scrolling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51828.13 Horizontal Scrolling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51828.14 The Size of a Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52028.15 Changing the Size of a Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52228.16 Coordinates and Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52428.17 The Window Tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52528.18 Window Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52628.19 Hooks for Window Scrolling and Changes . . . . . . . . . . . . . . . . . . 527

29 Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52929.1 Creating Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52929.2 Multiple Displays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53029.3 Frame Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 531

29.3.1 Access to Frame Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . 53129.3.2 Initial Frame Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53229.3.3 Window Frame Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533

29.3.3.1 Basic Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53329.3.3.2 Position Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53329.3.3.3 Size Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53429.3.3.4 Layout Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53429.3.3.5 Buffer Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53529.3.3.6 Window Management Parameters . . . . . . . . . . . . . . . . . 53629.3.3.7 Cursor Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53629.3.3.8 Color Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537

29.3.4 Frame Size And Position . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53829.3.5 Geometry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 540

29.4 Frame Titles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54029.5 Deleting Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54129.6 Finding All Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54129.7 Frames and Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54229.8 Minibuffers and Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54329.9 Input Focus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54329.10 Visibility of Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54529.11 Raising and Lowering Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54629.12 Frame Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54629.13 Mouse Tracking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54729.14 Mouse Position . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54729.15 Pop-Up Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54829.16 Dialog Boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54929.17 Pointer Shape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55029.18 Window System Selections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55029.19 Drag and Drop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55229.20 Color Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55229.21 Text Terminal Colors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55429.22 X Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55529.23 Display Feature Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 555

xv

30 Positions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55930.1 Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55930.2 Motion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 560

30.2.1 Motion by Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56030.2.2 Motion by Words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56130.2.3 Motion to an End of the Buffer . . . . . . . . . . . . . . . . . . . . . . . . . 56130.2.4 Motion by Text Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56230.2.5 Motion by Screen Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56430.2.6 Moving over Balanced Expressions . . . . . . . . . . . . . . . . . . . . . 56630.2.7 Skipping Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 567

30.3 Excursions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56830.4 Narrowing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 569

31 Markers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57231.1 Overview of Markers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57231.2 Predicates on Markers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57331.3 Functions that Create Markers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57331.4 Information from Markers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57531.5 Marker Insertion Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57631.6 Moving Marker Positions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57631.7 The Mark . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57731.8 The Region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 579

32 Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58132.1 Examining Text Near Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58132.2 Examining Buffer Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58232.3 Comparing Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58432.4 Inserting Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58532.5 User-Level Insertion Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58632.6 Deleting Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58732.7 User-Level Deletion Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58932.8 The Kill Ring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 591

32.8.1 Kill Ring Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59132.8.2 Functions for Killing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59232.8.3 Yanking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59232.8.4 Functions for Yanking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59332.8.5 Low-Level Kill Ring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59432.8.6 Internals of the Kill Ring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 595

32.9 Undo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59632.10 Maintaining Undo Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59832.11 Filling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59932.12 Margins for Filling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60232.13 Adaptive Fill Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60332.14 Auto Filling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60432.15 Sorting Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60532.16 Counting Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60932.17 Indentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 609

xvi

32.17.1 Indentation Primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61032.17.2 Indentation Controlled by Major Mode . . . . . . . . . . . . . . . . 61032.17.3 Indenting an Entire Region . . . . . . . . . . . . . . . . . . . . . . . . . . . 61132.17.4 Indentation Relative to Previous Lines . . . . . . . . . . . . . . . . 61232.17.5 Adjustable Tab Stops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61332.17.6 Indentation-Based Motion Commands . . . . . . . . . . . . . . . . . 613

32.18 Case Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61332.19 Text Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 615

32.19.1 Examining Text Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61532.19.2 Changing Text Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61632.19.3 Text Property Search Functions . . . . . . . . . . . . . . . . . . . . . . . 61832.19.4 Properties with Special Meanings . . . . . . . . . . . . . . . . . . . . . 62032.19.5 Formatted Text Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62432.19.6 Stickiness of Text Properties . . . . . . . . . . . . . . . . . . . . . . . . . . 62532.19.7 Saving Text Properties in Files . . . . . . . . . . . . . . . . . . . . . . . . 62632.19.8 Lazy Computation of Text Properties . . . . . . . . . . . . . . . . . 62732.19.9 Defining Clickable Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62832.19.10 Links and Mouse-1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62932.19.11 Defining and Using Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63032.19.12 Why Text Properties are not Intervals . . . . . . . . . . . . . . . 632

32.20 Substituting for a Character Code . . . . . . . . . . . . . . . . . . . . . . . . . 63332.21 Registers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63432.22 Transposition of Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63532.23 Base 64 Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63532.24 MD5 Checksum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63632.25 Atomic Change Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63732.26 Change Hooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 638

33 Non-ASCII Characters . . . . . . . . . . . . . . . . . . . . . . 64033.1 Text Representations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64033.2 Converting Text Representations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64133.3 Selecting a Representation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64233.4 Character Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64333.5 Character Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64433.6 Characters and Bytes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64533.7 Splitting Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64533.8 Scanning for Character Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64633.9 Translation of Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64733.10 Coding Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 648

33.10.1 Basic Concepts of Coding Systems . . . . . . . . . . . . . . . . . . . . 64833.10.2 Encoding and I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64933.10.3 Coding Systems in Lisp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65033.10.4 User-Chosen Coding Systems . . . . . . . . . . . . . . . . . . . . . . . . . 65233.10.5 Default Coding Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65333.10.6 Specifying a Coding System for One Operation . . . . . . . . 65533.10.7 Explicit Encoding and Decoding . . . . . . . . . . . . . . . . . . . . . . 65633.10.8 Terminal I/O Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65733.10.9 MS-DOS File Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 658

xvii

33.11 Input Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65933.12 Locales . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 660

34 Searching and Matching . . . . . . . . . . . . . . . . . . . . 66134.1 Searching for Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66134.2 Searching and Case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66334.3 Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 663

34.3.1 Syntax of Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . 66334.3.1.1 Special Characters in Regular Expressions . . . . . . . . . 66434.3.1.2 Character Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66734.3.1.3 Backslash Constructs in Regular Expressions . . . . . . 668

34.3.2 Complex Regexp Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67134.3.3 Regular Expression Functions . . . . . . . . . . . . . . . . . . . . . . . . . . 672

34.4 Regular Expression Searching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67334.5 POSIX Regular Expression Searching . . . . . . . . . . . . . . . . . . . . . . . 67634.6 The Match Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 676

34.6.1 Replacing the Text that Matched . . . . . . . . . . . . . . . . . . . . . . . 67634.6.2 Simple Match Data Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67734.6.3 Accessing the Entire Match Data . . . . . . . . . . . . . . . . . . . . . . . 67934.6.4 Saving and Restoring the Match Data . . . . . . . . . . . . . . . . . . 680

34.7 Search and Replace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68134.8 Standard Regular Expressions Used in Editing . . . . . . . . . . . . . . 683

35 Syntax Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68435.1 Syntax Table Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68435.2 Syntax Descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 684

35.2.1 Table of Syntax Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68535.2.2 Syntax Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 687

35.3 Syntax Table Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68835.4 Syntax Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69035.5 Motion and Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69135.6 Parsing Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 691

35.6.1 Motion Commands Based on Parsing . . . . . . . . . . . . . . . . . . . 69235.6.2 Finding the Parse State for a Position . . . . . . . . . . . . . . . . . . 69235.6.3 Parser State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69335.6.4 Low-Level Parsing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69435.6.5 Parameters to Control Parsing . . . . . . . . . . . . . . . . . . . . . . . . . 695

35.7 Some Standard Syntax Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69535.8 Syntax Table Internals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69535.9 Categories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 696

36 Abbrevs and Abbrev Expansion . . . . . . . . . . . 69936.1 Setting Up Abbrev Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69936.2 Abbrev Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69936.3 Defining Abbrevs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70036.4 Saving Abbrevs in Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70136.5 Looking Up and Expanding Abbreviations . . . . . . . . . . . . . . . . . . 70236.6 Standard Abbrev Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 704

xviii

37 Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70537.1 Functions that Create Subprocesses . . . . . . . . . . . . . . . . . . . . . . . . . 70537.2 Shell Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70637.3 Creating a Synchronous Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70737.4 Creating an Asynchronous Process . . . . . . . . . . . . . . . . . . . . . . . . . . 71037.5 Deleting Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71237.6 Process Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71237.7 Sending Input to Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71437.8 Sending Signals to Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71537.9 Receiving Output from Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . 717

37.9.1 Process Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71737.9.2 Process Filter Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71837.9.3 Decoding Process Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72037.9.4 Accepting Output from Processes . . . . . . . . . . . . . . . . . . . . . . 721

37.10 Sentinels: Detecting Process Status Changes . . . . . . . . . . . . . . . 72137.11 Querying Before Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72337.12 Transaction Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72337.13 Network Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72437.14 Network Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72637.15 Datagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72637.16 Low-Level Network Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 727

37.16.1 make-network-process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72737.16.2 Network Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72937.16.3 Testing Availability of Network Features . . . . . . . . . . . . . . 730

37.17 Misc Network Facilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73137.18 Packing and Unpacking Byte Arrays . . . . . . . . . . . . . . . . . . . . . . . 732

37.18.1 Describing Data Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73237.18.2 Functions to Unpack and Pack Bytes . . . . . . . . . . . . . . . . . . 73437.18.3 Examples of Byte Unpacking and Packing . . . . . . . . . . . . . 735

38 Emacs Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73938.1 Refreshing the Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73938.2 Forcing Redisplay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73938.3 Truncation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74038.4 The Echo Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 741

38.4.1 Displaying Messages in the Echo Area . . . . . . . . . . . . . . . . . . 74138.4.2 Reporting Operation Progress . . . . . . . . . . . . . . . . . . . . . . . . . . 74338.4.3 Logging Messages in *Messages* . . . . . . . . . . . . . . . . . . . . . . 74438.4.4 Echo Area Customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 745

38.5 Reporting Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74538.5.1 Warning Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74638.5.2 Warning Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74638.5.3 Warning Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 748

38.6 Invisible Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74838.7 Selective Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75038.8 Temporary Displays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75238.9 Overlays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 754

38.9.1 Managing Overlays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 754

xix

38.9.2 Overlay Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75638.9.3 Searching for Overlays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 759

38.10 Width . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76038.11 Line Height . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76138.12 Faces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 762

38.12.1 Defining Faces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76338.12.2 Face Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76538.12.3 Face Attribute Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76738.12.4 Displaying Faces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77038.12.5 Font Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77138.12.6 Functions for Working with Faces . . . . . . . . . . . . . . . . . . . . . 77238.12.7 Automatic Face Assignment . . . . . . . . . . . . . . . . . . . . . . . . . . . 77338.12.8 Looking Up Fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77338.12.9 Fontsets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 774

38.13 Fringes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77638.13.1 Fringe Size and Position . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77638.13.2 Fringe Indicators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77738.13.3 Fringe Cursors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77938.13.4 Fringe Bitmaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77938.13.5 Customizing Fringe Bitmaps . . . . . . . . . . . . . . . . . . . . . . . . . . 78038.13.6 The Overlay Arrow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 780

38.14 Scroll Bars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78138.15 The display Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 783

38.15.1 Specified Spaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78338.15.2 Pixel Specification for Spaces . . . . . . . . . . . . . . . . . . . . . . . . . 78438.15.3 Other Display Specifications . . . . . . . . . . . . . . . . . . . . . . . . . . 78538.15.4 Displaying in the Margins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 786

38.16 Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78738.16.1 Image Descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78838.16.2 XBM Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79138.16.3 XPM Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79238.16.4 GIF Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79238.16.5 PostScript Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79238.16.6 Other Image Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79238.16.7 Defining Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79338.16.8 Showing Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79538.16.9 Image Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 796

38.17 Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79638.17.1 Button Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79738.17.2 Button Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79838.17.3 Making Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79838.17.4 Manipulating Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79938.17.5 Button Buffer Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 800

38.18 Abstract Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80038.18.1 Abstract Display Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 80138.18.2 Abstract Display Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . 803

38.19 Blinking Parentheses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80538.20 Usual Display Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 806

xx

38.21 Display Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80738.21.1 Display Table Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80738.21.2 Active Display Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80938.21.3 Glyphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 809

38.22 Beeping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81038.23 Window Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 811

39 Operating System Interface . . . . . . . . . . . . . . . . 81239.1 Starting Up Emacs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 812

39.1.1 Summary: Sequence of Actions at Startup . . . . . . . . . . . . . . 81239.1.2 The Init File, .emacs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81339.1.3 Terminal-Specific Initialization . . . . . . . . . . . . . . . . . . . . . . . . . 81439.1.4 Command-Line Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 815

39.2 Getting Out of Emacs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81739.2.1 Killing Emacs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81739.2.2 Suspending Emacs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 817

39.3 Operating System Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81939.4 User Identification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82239.5 Time of Day . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82439.6 Time Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82539.7 Parsing and Formatting Times . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82639.8 Processor Run time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82839.9 Time Calculations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82839.10 Timers for Delayed Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82939.11 Idle Timers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83139.12 Terminal Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 832

39.12.1 Input Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83239.12.2 Recording Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 833

39.13 Terminal Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83439.14 Sound Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83539.15 Operating on X11 Keysyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83539.16 Batch Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83639.17 Session Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 836

Appendix A Emacs 21 Antinews . . . . . . . . . . . . . 838A.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 . . . 850Preamble . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 850Terms and Conditions for Copying, Distribution and Modification . . 851How to Apply These Terms to Your New Programs . . . . . . . . . . . . . . . . 855

xxi

Appendix D Tips and Conventions . . . . . . . . . . . 856D.1 Emacs Lisp Coding Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 856D.2 Key Binding Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 859D.3 Emacs Programming Tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 860D.4 Tips for Making Compiled Code Fast . . . . . . . . . . . . . . . . . . . . . . . . 861D.5 Tips for Avoiding Compiler Warnings . . . . . . . . . . . . . . . . . . . . . . . . 862D.6 Tips for Documentation Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 862D.7 Tips on Writing Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 865D.8 Conventional Headers for Emacs Libraries . . . . . . . . . . . . . . . . . . . 867

Appendix E GNU Emacs Internals . . . . . . . . . . 870E.1 Building Emacs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 870E.2 Pure Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 871E.3 Garbage Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 872E.4 Memory Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 875E.5 Writing Emacs Primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 876E.6 Object Internals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 880

E.6.1 Buffer Internals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 880E.6.2 Window Internals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 886E.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