Writing GNU Emacs Extensions

Preface

Before you even begin to extend Emacs, it's already the highest-function text editor there is. Not only can it do everything you'd normally expect (formatting paragraphs, centering lines, searching for patterns, putting a block in upper case), not only does it have advanced features (matching braces in source code, employing color to highlight syntactic elements in your files, giving online help on every keystroke and other commands), but it also performs a host of functions you'd never dream of finding in a text editor. You can use Emacs to read and compose email and to browse the World Wide Web; you can have it run FTP for you, transparently making remote files editable as if they were local; you can ask it to remind you about upcoming meetings, appointments, and anniversaries. As if that weren't enough, Emacs can also play you in a game of Go-Moku (and win, more than likely); it can tell you today's date in the ancient Mayan calendar; and it can decompose a number into its prime factors.

With all that functionality, it may seem crazy that Emacs users often spend a significant portion of their time extending Emacs. After all, most programmers view their editors as tools for creating other software; why spend so much energy modifying the tool itself? A carpenter doesn't tinker with his hammer; a plumber doesn't tinker with his wrench; they use their tools to accomplish the job at hand. So why are Emacs users different?

The answer is that the carpenter and the plumber would tinker with their tools to make them better, if they knew how. Who knows exactly what they need better than they do? But they're not toolsmiths. On the other hand, Emacs is a special kind of tool: it's software, which means the tool is the same stuff as what Emacs users use it on. The user of Emacs is often a programmer, and programming Emacs is, after all, just programming. Emacs users are in the happy position of being their own toolsmiths.

This book teaches Emacs Lisp programming using a series of real-life examples progressing from trivial to sophisticated. We'll start with simple configuration tweaks that you can put in your Emacs startup file, and by the end we'll be writing "major modes" and modifying Emacs's own "command loop." Along the way we'll learn about variables, keymaps, interactive commands, buffers, windows, process I/O, and more.

When I refer to Emacs in this book, I specifically mean GNU Emacs. There are many editors that call themselves Emacs. Here's a bit of the history of the name according to the authoritative On-line Hacker Jargon File, version 4.0.0, 24-Jul-1996:

[Emacs] was originally written by Richard Stallman in TECO under ITS at the MIT AI lab; AI Memo 554 described it as "an advanced, self-documenting, customizable, extensible real-time display editor." It has since been re-implemented any number of times, by various hackers, and versions exist that run under most major operating systems. Perhaps the most widely used version, also written by Stallman and now called "GNU EMACS" or GNUMACS, runs principally under UNIX. It includes facilities to run compilation subprocesses and send and receive mail; many hackers spend up to 80% of their tube time inside it. Other variants include GOSMACS, CCA EMACS, UniPress EMACS, Montgomery EMACS, jove, epsilon, and MicroEMACS.

The examples in this book were all developed and tested in GNU Emacs version 19.34 and a pre-release version of Emacs 20.1 under various flavors of UNIX. See Appendix E, for information on where to find the Emacs distribution.

I've let my own progression as an Emacs user be my guide in selecting instructive examples. The sequence of examples in this book essentially retells the story of how my own Emacs usage matured. For instance, from the very first moment I started using Emacs I knew I had to do something about getting that damn BACKSPACE key not to invoke the online help! Maybe you have that problem, too. Solving that problem is the first example we'll cover in the next chapter.

After I'd been using Emacs for a short while, I found myself wanting a number of cursor-motion shortcuts. As I learned, they were easily written in terms of Emacs's existing motion primitives. We'll see several examples of those in Chapter 2. Later I needed to have some way of undoing one of my most common and maddening typing errors: pressing CONTROL-v several times, when I meant to press CONTROL-b. Instead of moving the cursor a few spaces to the left, I'd scroll the whole window a few times and lose my place. Fixing this was easily done, too, as you'll see in Chapter 3. When I began to manage files full of clever quotations, I needed special tools to handle the specially formatted files. We'll see some of those in Chapter 9.

Except for the first handful of examples, which are simple one- and two-liners, each example has its own chapter. Each chapter illustrates some problem needing an Emacs Lisp solution, then presents a function or set of functions that solves the problem. Then, just as real-life customizations tend to evolve to become more useful and more general, we'll revise the solution once or twice before going on to the next subject.

Each example builds on the concepts of prior examples and introduces a few new ones of its own. By the end of the book, we will have covered most major topics in Emacs Lisp programming and discussed the techniques for quickly finding out how to do anything you might need to do in Emacs Lisp, using on-line documentation and other information. To borrow an old saying: Give a man a new Emacs command and he can hack for a night; teach a man to make new Emacs commands and he can hack for a lifetime.

This book presumes that you're familiar with programming and with Emacs use. It would help if you were acquainted with some variant of the Lisp programming language (of which Emacs Lisp is one dialect), but that's not strictly necessary. The essentials of Lisp programming are pretty simple and should quickly become clear through the examples we'll be using. There's also Appendix B, which briefly recaps Lisp fundamentals.

If you aren't familiar with the basic concepts in Emacs, refer to Learning GNU Emacs, 2nd edition by Debra Cameron, Bill Rosenblatt, and Eric Raymond. Also useful is Emacs's own online documentation, especially the Emacs "info" manual, which is also available in book form as The GNU Emacs Manual. If you'd like a more complete understanding of Lisp programming, I recommend Common Lisp: A Gentle Introduction to Symbolic Computation by David Touretzky.

This book is not a reference manual for Emacs Lisp; nor, in fact, is it particularly thorough in its coverage of the language. It's a tutorial, covering topics chosen more for good instructional flow than for exhaustiveness. For best effect it should be read from beginning to end. The Free Software Foundation publishes The GNU Emacs Lisp Reference Manual, the definitive reference manual on which it would be difficult to improve. It's available in printed and electronic forms from several sources; see Appendix E.

What Is Emacs?

It's missing the point to say that Emacs is just a programmable text editor. It's also, for instance, a C code editor. That may seem like nitpicking, but editing C code and editing text are two very different activities, and Emacs accommodates the differences by being two different editors. When editing code, you don't care about paragraph structure. When editing text, you don't care about indenting each line according to its syntax.

Emacs is also a Lisp code editor. It's also a hexadecimal binary file editor. It's also a structured outline editor. It's also a directory editor, a tar file editor, an email editor, and a hundred others. Each kind of editor is an Emacs mode, a chunk of Lisp code that combines Emacs's primitive types and operations in some new way. Each mode is therefore an extension of Emacs, which means that when you strip away all those modes—when you remove the extensions and you're left with just the core of Emacs—you don't have any editors at all; you have the raw materials for making editors. You have an editor-builder.

What can you build with an editor-builder? Editors, of course, but what's an editor? An editor is a program for viewing and altering a representation of data of some kind. By "representation" I mean a set of rules for showing the data's structure and content, and for indicating naturally how interactions with the data are supposed to proceed. When editing a text file, the rules are pretty simple: each printable byte gets displayed in sequence, with newline characters causing line breaks; and a cursor indicates where in the byte sequence the next user-invoked operation will occur. When editing a directory, the metaphor is a little less straightforward—data in the directory file must first be translated into a human-readable form—but the resulting interactions still seem natural.

This definition of editor covers nearly the whole range of interactive applications, and that's no accident. Interactive applications are almost always editors for some kind of data or another. Emacs therefore is, in the end, a general-purpose, interactive application builder. It's a user interface toolkit! Like any good toolkit, Emacs supplies a set of user-interface widgets, a set of operations on them, an event loop, a sophisticated I/O regime, and a language for putting them all together. The widget set may not be fancy and graphical like X11, Windows, or Macintosh toolkits are, but as Emacs programmers discover, a full-blown graphical toolkit is often overkill. 99% of most applications is textual, whether it's rows and columns of numbers, lists of menu items, or letters in a crossword puzzle diagram (as in our culminating example in Chapter 10). For such applications, Emacs surpasses other toolkits in power, sophistication, simplicity, and performance.

The real answer to "Why are Emacs users different?" isn't merely that they spend time tinkering with the tools they use. They're using Emacs for its intended purpose: to create a universe of new tools.