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 [...]... manual presumes considerable familiarity with the use of Emacs for editing; see The GNU Emacs Manual for this basic information Generally speaking, the earlier chapters describe features of Emacs Lisp that have counterparts in many programming languages, and later chapters describe features that are peculiar to Emacs Lisp or relate specifically to editing This is edition 2.9 of the GNU Emacs Lisp Reference. .. displays, subprocesses, and so on Emacs Lisp is closely integrated with the editing facilities; thus, editing commands are functions that can also conveniently be called from Lisp programs, and parameters for customization are ordinary Lisp variables This manual attempts to be a full description of Emacs Lisp For a beginner’s introduction to Emacs Lisp, see An Introduction to Emacs Lisp Programming, by Bob... 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... 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 implementation... 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... bug -lisp- manual @gnu. org 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 bug -gnu- emacs @gnu. org Chapter 1: Introduction 2 1.2 Lisp History Lisp. .. 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,... These facilities provide information about which version of Emacs is in use emacs- version &optional here [Command] This function returns a string describing the version of Emacs that is running It is useful to include this string in bug reports (emacs- version) ⇒ "GNU Emacs 20.3.5 (i486-pc-linux-gnulibc1, X toolkit) of Sat Feb 14 1998 on psilocin .gnu. org" If here is non-nil, it inserts the text in the buffer... exist in Emacs Lisp A Lisp variable can have any type of value, and it remembers whatever value you store in it, type and all (Actually, a small number of Emacs Lisp variables can only take on values of a certain type See Section 11.15 [Variables with Restricted Values], page 158.) This chapter describes the purpose, printed representation, and read syntax of each of the standard types in GNU Emacs Lisp. .. comments 2.3 Programming Types There are two general categories of types in Emacs Lisp: those having to do with Lisp programming, and those having to do with editing The former exist in many Lisp implementations, in one form or another The latter are unique to Emacs Lisp 2.3.1 Integer Type The range of values for integers in Emacs Lisp is −268435456 to 268435455 (29 bits; i.e., −228 to 228 − 1) on most