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.

Conventions Used in This Book

The following conventions are used in this book.

Typographic Conventions

Constant Willison

Used for Emacs commands and all elements of code.

Italic

Used to introduce new terms. Used for filenames, commands entered from a UNIX shell, newsgroups, and Internet addresses.

Bold

Used for keystrokes.

Emacs Commands

This book follows the standard Emacs documentation when referring to keys. When you hold down the CONTROL (CTRL) key, the syntax C- is used. When you hold down the META or ALT key (or use the ESCAPE key for the same effect), the syntax M- is used. We also refer to RET for the RETURN or ENTER key, TAB for the TAB key, ESC for the ESCAPE key, and SPC for the space bar.

Examples

When you see xy, it means that the result of computing the expression on the left yields the value on the right.

Organization of This Book

Each chapter in this book builds on the chapters before it. I recommend that you read the chapters in order; that way everything should make sense.

Chapter 1

Introduces some basic changes you can make to Emacs. It will familiarize you with Emacs Lisp, how to evaluate Lisp expressions, and how that alters Emacs’s behavior.

Chapter 2

Continues the tutorial by teaching you how to write Lisp functions and install them so they’re invoked at the right time. Hooks and the feature called advice are introduced.

Chapter 3

Teaches techniques for saving information between separate function calls and helping groups of functions work together—the first step in writing systems instead of mere commands. Symbol properties and markers are among the topics introduced along the way.

Chapter 4

Shows some of the most common techniques you’ll need: those that affect the current buffer and strings within it. Regular expressions are introduced.

Chapter 5

Discusses loading, autoloading, and packages, which are features you’ll need when you start creating large groups of related functions.

Chapter 6

Fills in some background on this fundamental feature of Lisp.

Chapter 7

Shows how to assemble related functions and variables into an editing package called a “minor mode.” The central example in this chapter deals with making paragraph formatting in Emacs work more like paragraph formatting in a word processor.

Chapter 8

Shows the flexibility of the Emacs Lisp interpreter, how to control what gets evaluated when, and how to write code that is impervious to run-time errors.

Chapter 9

Explains the differences between minor and major modes, and offers a simple example of the latter: a mode for treating a file of quotations in a more structured manner than ordinary text.

Chapter 10

Defines a major mode that drastically alters Emacs’s normal behavior. It’s a crossword puzzle editor and an illustration of how flexible an environment Emacs is for developing text-oriented applications.

Appendix B

Provides a handy guide to Lisp’s syntax, data types, and control structures.

Appendix C

Describes tools you can use to track down problems in your Emacs Lisp code.

Appendix D

Explains the steps you should take when you want to distribute your creations to other people.

Appendix E

Outlines the steps necessary to get a working version of Emacs running on your system.

Obtaining the Example Programs

If you’re using a Web browser, you can get the examples from ftp://ftp.oreilly.com/published/oreilly/nutshell/emacs_extensions.

FTP

To use FTP, you need a machine with direct access to the Internet. A sample session is shown, with what you should type in boldface.

% ftp ftp.oreilly.com
Connected to ftp.oreilly.com.
220 FTP server (Version 6.21 Tue Mar 10 22:09:55 EST 1992) ready.
Name (ftp.oreilly.com:yourname): anonymous
331 Guest login ok, send domain style e-mail address as password.
Password: yourname@yourhost.com (use your user name and host here)
230 Guest login ok, access restrictions apply.
ftp> cd /published/oreilly/nutshell/emacs_extensions
250 CWD command successful.
ftp> binary (Very important! You must specify binary transfer for gzipped files.)
200 Type set to I.
ftp> get examples.tar.gz
200 PORT command successful.
150 Opening BINARY mode data connection for examples.tar.gz.
226 Transfer complete.
ftp> quit
221 Goodbye.
%

The file is a gzipped tar archive; extract the files from the archive by typing:

% gzip -dc examples.tar.gz | tar -xvf -

System V systems require the following tar command instead:

% gzip -dc examples.tar.gz | tar -xvof -

If gzip is not available on your system, use separate uncompress and tar commands.

% uncompress examples.tar.gz
% tar xvf examples.tar

Acknowledgments

Thanks to Nathaniel Borenstein, who helped to dispel my chauvinism about C and taught me an appreciation for the world’s amazing variety of programming languages.

Thanks to Richard Stallman for writing Emacs—twice—and who was right about an amazing phenomenon: hackers write better code when it’s for their own satisfaction instead of for pay.

Thanks to Mike McInerny, whose stubborn persistence got me started using GNU Emacs—even after several false starts convinced me it wasn’t worth my time.

Thanks to Ben Liblit for ideas, code, and bug hunting in my Defer package (which was going to be a chapter in this book until Emacs evolved parallel functionality: the timer package.) Additional help was provided by Simon Marshall, who used and improved on many of the ideas in his defer-lock. Hi, Si.

Thanks to Linda Branagan for showing me it’s possible for an ordinary person like me to write a book. (Not that she’s ordinary; not even close.)

Thanks to Emily Cox and Henry Rathvon for some insider information about crossword puzzles.

Thanks to all the folks who reviewed and commented on early drafts of this book: Julie Epelboim, Greg Fox, David Hartmann, Bart Schaefer, Ellen Siever, and Steve Webster.

Thanks to my partners at Zanshin Inc. and the Internet Movie Database for allowing me to divide my energies between those projects and this book.

Thanks to my editor, Andy Oram, for coping flexibly with the aforementioned divided energies.

Thanks to Alex, my dog, for curling happily by my feet for much of the writing of this book.

Most of all, to Andrea Dougherty, who encouraged me, supported me, made innumerable sacrifices, performed uncountable services, provided companionship when I needed it and solitude when I needed that (never the other way around), and who in all other respects was good for me and for this book: it must be love.

Get Writing GNU Emacs Extensions now with O’Reilly online learning.

O’Reilly members experience live online training, plus books, videos, and digital content from 200+ publishers.