An Introduction to Programming in Emacs Lisp An Introduction to Programming in Emacs Lisp Second Edition by Robert J. Chassell Copyright c  1990, 1991, 1992, 1993, 1994, 1995, 1997, 2001, 2002 Free Software Foundation, Inc. Published by the Free Software Foundation, Inc. 59 Temple Place, Suite 330 Boston, MA 02111-1307 USA Edition 2.05, 2001 Jan 5 ISBN 1-882114-43-4 Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; there being no Invariant Section, 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.” i Short Contents Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi 1 List Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 2 Practicing Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 3 How To Write Function Definitions . . . . . . . . . . . . . . . . . . 29 4 A Few Buffer–Related Functions . . . . . . . . . . . . . . . . . . . . 51 5 A Few More Complex Functions . . . . . . . . . . . . . . . . . . . . 63 6 Narrowing and Widening . . . . . . . . . . . . . . . . . . . . . . . . . 77 7 car, cdr, cons: Fundamental Functions . . . . . . . . . . . . . 81 8 Cutting and Storing Text . . . . . . . . . . . . . . . . . . . . . . . . . 89 9 How Lists are Implemented . . . . . . . . . . . . . . . . . . . . . . . 113 10 Yanking Text Back . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 11 Loops and Recursion . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 12 Regular Expression Searches . . . . . . . . . . . . . . . . . . . . . . 149 13 Counting: Repetition and Regexps . . . . . . . . . . . . . . . . . . 167 14 Counting Words in a defun . . . . . . . . . . . . . . . . . . . . . . 181 15 Readying a Graph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 16 Your ‘.emacs’ File . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213 17 Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231 18 Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239 Appendix A The the-the Function . . . . . . . . . . . . . . . . . . 241 Appendix B Handling the Kill Ring . . . . . . . . . . . . . . . . . . . 243 Appendix C A Graph with Labelled Axes . . . . . . . . . . . . . . . 255 Appendix D GNU Free Documentation License . . . . . . . . . . . 279 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287 ii iii Table of Contents Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi On Reading this Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi For Whom This is Written. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii Lisp History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii A Note for Novices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii Thank You . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiv 1 List Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.1 Lisp Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.1.1 Lisp Atoms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.1.2 Whitespace in Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1.3 GNU Emacs Helps You Type Lists . . . . . . . . . . . . . . . 3 1.2 Run a Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.3 Generate an Error Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.4 Symbol Names and Function Definitions . . . . . . . . . . . . . . . . . . 6 1.5 The Lisp Interpreter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 1.5.1 Byte Compiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 1.6 Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 1.6.1 Evaluating Inner Lists . . . . . . . . . . . . . . . . . . . . . . . . . . 9 1.7 Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 1.7.1 Error Message for a Symbol Without a Function 11 1.7.2 Error Message for a Symbol Without a Value . . . . 11 1.8 Arguments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 1.8.1 Arguments’ Data Types . . . . . . . . . . . . . . . . . . . . . . . . 13 1.8.2 An Argument as the Value of a Variable or List . . 13 1.8.3 Variable Number of Arguments . . . . . . . . . . . . . . . . . 14 1.8.4 Using the Wrong Type Object as an Argument . . 14 1.8.5 The message Function . . . . . . . . . . . . . . . . . . . . . . . . . 16 1.9 Setting the Value of a Variable . . . . . . . . . . . . . . . . . . . . . . . . . . 17 1.9.1 Using set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 1.9.2 Using setq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 1.9.3 Counting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 1.10 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 1.11 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 2 Practicing Evaluation . . . . . . . . . . . . . . . . . . . . . 23 2.1 Buffer Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 2.2 Getting Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 2.3 Switching Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 2.4 Buffer Size and the Location of Point . . . . . . . . . . . . . . . . . . . . 27 2.5 Exercise . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 iv 3 How To Write Function Definitions . . . . . . . . 29 3.1 The defun Special Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 3.2 Install a Function Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 3.2.1 Change a Function Definition . . . . . . . . . . . . . . . . . . . 32 3.3 Make a Function Interactive . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 3.3.1 An Interactive multiply-by-seven . . . . . . . . . . . . . 34 3.4 Different Options for interactive . . . . . . . . . . . . . . . . . . . . . . 35 3.5 Install Code Permanently . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 3.6 let . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 3.6.1 The Parts of a let Expression . . . . . . . . . . . . . . . . . . 37 3.6.2 Sample let Expression. . . . . . . . . . . . . . . . . . . . . . . . . 38 3.6.3 Uninitialized Variables in a let Statement. . . . . . . 39 3.7 The if Special Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 3.7.1 The type-of-animal Function in Detail. . . . . . . . . 41 3.8 If–then–else Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 3.9 Truth and Falsehood in Emacs Lisp . . . . . . . . . . . . . . . . . . . . . 43 3.10 save-excursion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 3.10.1 Template for a save-excursion Expression . . . . 45 3.11 Review . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 3.12 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 4 A Few Buffer–Related Functions . . . . . . . . . . . 51 4.1 Finding More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 4.2 A Simplified beginning-of-buffer Definition. . . . . . . . . . . . 52 4.3 The Definition of mark-whole-buffer . . . . . . . . . . . . . . . . . . . 54 4.3.1 Body of mark-whole-buffer . . . . . . . . . . . . . . . . . . . 55 4.4 The Definition of append-to-buffer . . . . . . . . . . . . . . . . . . . . 56 4.4.1 The append-to-buffer Interactive Expression. . . 57 4.4.2 The Body of append-to-buffer . . . . . . . . . . . . . . . . 57 4.4.3 save-excursion in append-to-buffer. . . . . . . . . . 58 4.5 Review . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 4.6 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 v 5 A Few More Complex Functions . . . . . . . . . . . 63 5.1 The Definition of copy-to-buffer. . . . . . . . . . . . . . . . . . . . . . . 63 5.2 The Definition of insert-buffer. . . . . . . . . . . . . . . . . . . . . . . . 64 5.2.1 The Interactive Expression in insert-buffer. . . . 65 A Read-only Buffer. . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 ‘b’ in an Interactive Expression. . . . . . . . . . . . . . . . . 65 5.2.2 The Body of the insert-buffer Function . . . . . . . 65 5.2.3 insert-buffer With an if Instead of an or. . . . . 66 5.2.4 The or in the Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 5.2.5 The let Expression in insert-buffer . . . . . . . . . . 68 5.3 Complete Definition of beginning-of-buffer . . . . . . . . . . . . 69 5.3.1 Optional Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 5.3.2 beginning-of-buffer with an Argument . . . . . . . 71 What happens in a large buffer. . . . . . . . . . . . . . . . . 71 What happens in a small buffer . . . . . . . . . . . . . . . . 72 5.3.3 The Complete beginning-of-buffer . . . . . . . . . . . 73 5.4 Review . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 5.5 optional Argument Exercise . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 6 Narrowing and Widening. . . . . . . . . . . . . . . . . . 77 6.1 The save-restriction Sp ecial Form . . . . . . . . . . . . . . . . . . . . 77 6.2 what-line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 6.3 Exercise with Narrowing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 7 car, cdr, cons: Fundamental Functions . . . . . 81 7.1 car and cdr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 7.2 cons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 7.2.1 Find the Length of a List: length . . . . . . . . . . . . . . 84 7.3 nthcdr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 7.4 nth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 7.5 setcar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 7.6 setcdr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 7.7 Exercise . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 vi 8 Cutting and Storing Text . . . . . . . . . . . . . . . . . 89 8.1 zap-to-char . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 8.1.1 The interactive Expression . . . . . . . . . . . . . . . . . . . 90 8.1.2 The Body of zap-to-char. . . . . . . . . . . . . . . . . . . . . . 91 8.1.3 The search-forward Function . . . . . . . . . . . . . . . . . 92 8.1.4 The progn Special Form . . . . . . . . . . . . . . . . . . . . . . . 93 8.1.5 Summing up zap-to-char . . . . . . . . . . . . . . . . . . . . . 93 8.2 kill-region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 8.2.1 condition-case. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 8.2.2 delete-and-extract-region . . . . . . . . . . . . . . . . . . 96 8.3 delete-and-extract-region: Digressing into C . . . . . . . . . 98 8.4 Initializing a Variable with defvar . . . . . . . . . . . . . . . . . . . . . 100 8.4.1 defvar and an asterisk. . . . . . . . . . . . . . . . . . . . . . . . 101 8.5 copy-region-as-kill. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 8.5.1 The Body of copy-region-as-kill. . . . . . . . . . . . 103 The kill-append function. . . . . . . . . . . . . . . . . . . . 104 The kill-new function . . . . . . . . . . . . . . . . . . . . . . . 105 8.6 Review . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 8.7 Searching Exercises. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 9 How Lists are Implemented . . . . . . . . . . . . . . 113 9.1 Symbols as a Chest of Drawers . . . . . . . . . . . . . . . . . . . . . . . . . 115 9.2 Exercise . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 10 Yanking Text Back . . . . . . . . . . . . . . . . . . . . . 117 10.1 Kill Ring Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 10.2 The kill-ring-yank-pointer Variable . . . . . . . . . . . . . . . 117 10.3 Exercises with yank and nthcdr . . . . . . . . . . . . . . . . . . . . . . . 119 11 Loops and Recursion. . . . . . . . . . . . . . . . . . . . 121 11.1 while . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 11.1.1 A while Loop and a List. . . . . . . . . . . . . . . . . . . . . 122 11.1.2 An Example: print-elements-of-list . . . . . . 123 11.1.3 A Loop with an Incrementing Counter . . . . . . . . 124 Example with incrementing counter . . . . . . . . . . . 125 The parts of the function definition . . . . . . . . . . . . 126 Putting the function definition together . . . . . . . . 127 11.1.4 Loop with a Decrementing Counter . . . . . . . . . . . 129 Example with decrementing counter . . . . . . . . . . . 129 The parts of the function definition . . . . . . . . . . . . 130 Putting the function definition together . . . . . . . . 130 11.2 Save your time: dolist and dotimes . . . . . . . . . . . . . . . . . . 131 The dolist Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 The dotimes Macro . . . . . . . . . . . . . . . . . . . . . . . . . . 133 [...]... in association only with Emacs, it is a full computer programming language You can use Emacs Lisp as you would any other programming language Perhaps you want to understand programming; perhaps you want to extend Emacs; or perhaps you want to become a programmer This introduction to Emacs Lisp is designed to get you started: to guide you in learning the fundamentals of programming, and more importantly,... having a dragon’s cave of treasures In addition to learning about Emacs as an editor and Emacs Lisp as a programming language, the examples and guided tours will give you an xii Preface opportunity to get acquainted with Emacs as a Lisp programming environment GNU Emacs supports programming and provides tools that you will want to become comfortable using, such as M- (the key which invokes the find-tag... rather than as a daunting mountain This introduction to Programming in Emacs Lisp has a companion document, The GNU Emacs Lisp Reference Manual The reference manual has more detail than this introduction In the reference manual, all the information about one topic is concentrated in one place You should turn to it if you are like the programmer quoted above And, of course, after you have read this Introduction, ... Arguments” in The GNU Emacs Manual If you are reading this in Info using GNU Emacs, you can read through this whole document just by pressing the space bar, SPC (To learn about Info, type C-h i and then select Info.) A note on terminology: when I use the word Lisp alone, I often am referring to the various dialects of Lisp in general, but when I speak of Emacs Lisp, I am referring to GNU Emacs Lisp in particular... only to learn to move around your computer screen You can teach yourself how to use Emacs with the on-line tutorial To use it, type C-h t (This means you press and release the CTRL key and the h at the same time, and then press and release t.) Also, I often refer to one of Emacs standard commands by listing the keys which you press to invoke the command and then giving the name of the command in parentheses,... called Emacs Lisp The code written in this programming language is the software—the sets of instructions—that tell the computer what to do when you give it commands Emacs is designed so that you can write new code in Emacs Lisp and easily install it as an extension to the editor (GNU Emacs is sometimes called an “extensible editor”, but it does much more than provide editing capabilities It is better to. .. ‘a’, ‘list’, ‘inside’, ‘of’, ‘it’ 1.1.1 Lisp Atoms In Lisp, what we have been calling words are called atoms This term comes from the historical meaning of the word atom, which means ‘indivisible’ As far as Lisp is concerned, the words we have been using in the lists cannot be divided into any smaller parts and still mean the same thing as part of a program; likewise with numbers and single character... GNU Emacs Helps You Type Lists When you type a Lisp expression in GNU Emacs using either Lisp Interaction mode or Emacs Lisp mode, you have available to you several commands to format the Lisp expression so it is easy to read For example, pressing the TAB key automatically indents the line the cursor is on by the right amount A command to properly indent the code in a region is customarily bound to. .. quoted list) appear in the echo area In both cases, what you are doing is giving a command to the program inside of GNU Emacs called the Lisp interpreter—giving the interpreter a command to evaluate the expression The name of the Lisp interpreter comes from the word for the task done by a human who comes up with the meaning of an expression—who “interprets” it You can also evaluate an atom that is not... similar to the way the name Cambridge can refer to the city in Massachusetts and have some information attached to the name as well, such as “great programming center” Another way to think about this is to imagine a symbol as being a chest of drawers The function definition is put in one drawer, the value in another, and so on What is put in the drawer holding the value can be changed without affecting the . An Introduction to Programming in Emacs Lisp An Introduction to Programming in Emacs Lisp Second Edition by Robert J. Chassell Copyright c . You can learn from it and mine it for ideas. Having GNU Emacs is like having a dragon’s cave of treasures. In addition to learning about Emacs as an editor and Emacs Lisp as a programming language,. book is intended as an approachable hill, rather than as a daunting mountain. This introduction to Programming in Emacs Lisp has a companion doc- ument, The GNU Emacs Lisp Reference Manual. The