Clojure for the Brave and True
If you spend your nights pining for the next chapter of Clojure for the Brave and True, then follow @nonrecursive or submit this:

Start Using Emacs

Before we get started with Emacs, here are some resources for setting up other text editors for Clojure development:

If you're already familiar with Emacs, skip ahead to the next chapter.

You can, of course, use any editor you want. Other editors get pretty close to Emacs's Clojure functionality. The primary reason I recommend Emacs, however, is that it offers tight integration with a Clojure REPL. This allows you to instantly try out your code as you write. That kind of tight feedback loop will be useful both when learning Clojure and, later, when writing real Clojure programs. If you don't follow the thorough Emacs instructions below, then it's still worthwhile to invest time in setting up your editor to work with a REPL. A secondary reason for using Emacs is that it's really great for working with any Lisp dialect; Emacs itself is written in a Lisp dialect called Emacs Lisp.

By the end of this chapter, your Emacs setup will look something like this:

Final look

To get there, we'll do the following:

After we're done installing and setting up Emacs, we'll cover:

1. Installation

You should use the latest major version of Emacs, Emacs 24.

After you're done installing Emacs, open it up. You should see something like this:

Fresh Emacs installation

2. Configuration

I've created a github repo which contains all the files you need to get started. Just do the following:

  1. Close Emacs
  2. Delete ~/.emacs or ~/.emacs.d if they exist
  3. Run git clone https://github.com/flyingmachine/emacs-for-clojure.git ~/.emacs.d
  4. (Optional) delete the .emacs.d/.git directory. You'll probably want to create your own git repo for .emacs.d
  5. Open Emacs

When you open Emacs you should see a lot of activity. This is because Emacs is downloading a bunch of packages which will be useful for Clojure development. Once the activity stops, go ahead and just quit Emacs and open it again. After you do so you should see this:

Emacs configged

Feel free to resize it however you please. Now that we've got everything set up, let's actually start doing some editing!

3. Emacs Escape Hatch

Before we go further, you need to know an important Emacs key binding: Control+g. This key binding quits whatever Emacs command you're trying to run, so if things aren't going right hit, hold down the Control key and press "g" and then try again. It won't close Emacs or make you lose any work; it'll just cancel your current action.

4. Emacs Buffers

All editing happens in an Emacs buffer. When you first start Emacs, a buffer named *scratch* is open. Emacs will always show you the name of the current buffer, as shown here:

Buffer name

By default, the scratch buffer behaves in a way that's optimal for Lisp development. Let's go ahead and create a fresh buffer so that we can play around without having unexpected things happen. To create a buffer, do this:

Since that is very wordy, let's express the same sequence in a compact format:

C-x b

Once you perform the above key sequence, you'll see a prompt at the bottom of the application:

Minibuffer

This area is called the minibuffer and it's where Emacs prompts you for input. Right now it's prompting us for a buffer name. You can enter the name of a buffer which is already open, or you can enter a new buffer name. Let's enter emacs-fun-times and hit enter.

You should now see a completely blank buffer. Go ahead and just start typing stuff. You should find that keys mostly work the way you'd expect:

You'll also notice that you're not sporting a bushy Unix beard or birkenstocks unless you had them to begin with, which should help ease any lingering trepidation you feel about using Emacs.

When you're done messing around, go ahead and kill the buffer:

C-x k enter

Sidenote: it might come as a surprise, but Emacs is actually quite violent, making ample use of the term "kill."

Now that you've killed the "emacs-fun-times" buffer, you should be back in the "*scratch*" buffer. In general, you can create as many new buffers as you want with C-x b. You can also quickly switch between buffers using the same command.

When you create a new buffer this way, it exists only in memory until you save it as a file. Let's learn about working with files.

5. Working with Files

Here's the key binding for opening a file in Emacs:

C-x C-f

Notice that you'll need to hold down the Control key when pressing both "x" and "f".

After you do that, you'll get another minibuffer prompt. Go ahead and navigate to ~/.emacs.d/user.el, your main Emacs configuration file. Emacs opens the file in a new buffer, and the buffer's name is the same as the filename.

Let's go to line 11 and uncomment it by removing the semi-colons. It will look like this:

(setq initial-frame-alist '((top . 0) (left . 0) (width . 187) (height . 77)))

Then change the values for "width" and "height". Width is the number of characters wide, and height is the number of lines high. By changing these values, you won't have to resize Emacs every time it starts. Go with something small at first, like 80 and 20:

(setq initial-frame-alist '((top . 0) (left . 0) (width . 80) (height . 20)))

Now save your file with the following key binding:

C-x C-s

You should get a message at the bottom of Emacs like "Wrote /Users/chauncy/.emacs.d/user.el". Also go ahead and try saving your buffer using the key binding you use in every other app. For me, it's ⌘-s. The Emacs config you downloaded should allow that to work, but if it doesn't that's no big deal!

After saving the file, go ahead and quit Emacs and start it again. I bet it's really tiny!

Tinemacs

Go through that same process a couple times until Emacs starts at a size that you like. Or just comment those lines out again and be done with it. If you're done editing user.el, you can close its buffer with C-x k. Either way, you're done saving your first file in Emacs! If something crazy happens, just use git to revert your changes.

If you want to create a new file, just do C-x C-f and enter the new file's path in the minibuffer. As soon as you save the buffer, Emacs will create a file with the buffer's contents at the path you entered.

Let's recap:

  1. In Emacs, editing takes place in buffers
  2. To switch to a buffer, do C-x b and enter the buffer name in the minibuffer
  3. To create a new buffer, do C-x b and enter a new buffer name
  4. To open a file, do C-x C-f and navigate to the file
  5. To save a buffer to a file, do C-x C-s.
  6. To create a new file, do C-x C-f and enter the new file's path. When you save the buffer, Emacs will create the file on the file system.

6. Key Bindings and Modes

We've already come a long way, and can now use Emacs like a basic very editor. This should help you get by if you ever need to use Emacs on a server or are forced into pairing with an Emacs nerd.

To really be productive, however, it'll be useful to go over some "key" details about key bindings (ha ha!). Then we'll introduce Emacs "modes". After that, we'll cover some core terminology and go over a bunch of super useful key bindings.

6.1. Key Bindings / Emacs is a Lisp Interpreter

First, the term key binding derives from the fact that Emacs binds keystrokes to commands, which are just elisp functions (I'll use "command" and "function" interchangeable). For example, C-x b is bound to the function switch-to-buffer. Likewise, C-x C-s is bound to save-file.

But it goes even further than that. Even simple keystrokes like f and a are bound to a function, in this case self-insert-command.

From Emacs's point of view, all functions are created equal. You can redefine functions, even core functions like save-file. You probably won't want to, but you can.

This is because, at its core, Emacs is "just" a Lisp interpreter which happens to load code editing facilities. From the perspective of Emacs, save-file is just a function, as is switch-to-buffer and almost any other command you can run. Not only that, any functions you create are treated the same as any built-in functions. You can even use Emacs to execute elisp, modifying Emacs as it runs - but that's a tale for another day.

This is why Emacs is so flexible and why people such as myself are so crazy about Emacs. Yes, it has a lot of surface of complexity which can be difficult to learn. But underlying it is the elegant simplicity of Lisp and the infinite tinkerability which comes with it.

This tinkerability extends to key bindings in another way. Just as you can redefine existing functions or redefine existing functions, you can create, redefine, and remove key bindings.

You can also run functions by name, without a specific keybinding, using M-x {function-name}, e.g. M-x save-buffer. "M" stands for "meta", a key which modern keyboards don't possess but which is usually mapped to "Alt" or "Option". M-x runs the smex command, which prompts you for the name of another command to be run.

Now that we understand key bindings and functions, we can understand what modes are and how they work.

6.2. Modes

An Emacs mode is primarily a collection of key bindings and functions which are packaged together to help you be productive when editing different types of files. Modes also do things like tell Emacs how to do syntax highlighting but I think that's of secondary importance and we won't cover that.

For example, when editing a Clojure file you'll want to load Clojure mode. Right now I'm writing a Markdown file and I'm using Markdown mode. When editing Clojure, we'll make use of the key binding C-c C-k to load the current buffer into a REPL and compile it.

Modes is that they come in two flavors: major modes and minor modes. Markdown mode and Clojure mode are both major modes. Major modes are usually set by Emacs when you open a file, but you can also set the mode explicitly with e.g. M-x clojure-mode or M-x major-mode - you set a mode by running the relevant Emacs command. Only one major mode is active at a time.

Whereas major modes special Emacs for a certain file type, minor modes usually provide functionally that's useful across many file types. For example, Abbrev mode "automatically expands text based on pre-defined abbreviation definitions" (per the Emacs manual). You can have multiple minor modes active at the same time.

You can see which modes are active on the mode line:

Emacs mode line

6.3. Installing Packages

A lot of modes are distributed as packages, which are just bundles of elisp files stored in a package repository. Emacs 24, which you should have installed, makes it very easy to browse and install packages. M-x package-list-packages will show you almost every package available. You can install packages with M-x package-install.

You can also customize Emacs by loading your own elisp files or files you find on the Internet. [This guide] has a good description of how to load customizations under the section "Loading New Packages" toward the bottom of the article.

7. Core Editing Terminology and Key Bindings

If all you want to do is use Emacs like Notepad, then you can skip this section entirely! But you'll be missing out on some great stuff:

To get started, open up a new buffer in Emacs and name it "jack-handy". Then paste in the following text:

If you were a pirate, you know what would be the one thing that would really make you mad? Treasure chests with no handles. How the hell are you supposed to carry it?!

The face of a child can say it all, especially the mouth part of the face.

To me, boxing is like a ballet, except there's no music, no choreography, and the dancers hit each other.

7.1. Point

If you've been following along, then you should see an orangey-red rectangle in your Emacs buffer. This is the cursor and it's the graphical representation of the point. Point is where all the magic happens - you insert text at point and most editing commands happen in relation to point. And even though your cursor appears to rest on top of a character, point is actually located between that character and the previous one.

For example, place your cursor over the "f" in "If you were a pirate". Point is located between "I" and "f". Now, if you do C-k, then all the text from the letter "f" onward will disappear. C-k runs the command kill-line, which "kills" all text after point on the current line (We'll talk more about killing later). Go ahead and undo that change.

7.2. Movement

You can use your arrow keys to move point just like in any GUI text editor, but there are many key bindings which will allow you to move more efficiently:

C-a Move to beginning of line
M-m Move to the first non-whitespace character on the line
C-e Move to end of line
C-f Move forward one character
C-b Move backward one character
M-f Move forward one word (I use this a lot)
M-b Move backward one word (I use this a lot, too)
C-s Regex search for text in the current buffer and move to it. Hit C-s again to move to the next match
C-r Same as above, but search in reverse
M-< Move to beginning of buffer
M-> Move to end of buffer
M-g g Go to line

Go ahead and try these out in your Jack Handy quotes buffer!

7.3. Selection / Regions

In Emacs, we don't select text. We create regions, and we do so by setting the mark with C-spc (control+space). Then, when you move point, everything between mark and point is the region. It's very similar to shift-selecting text for basic purposes. For example, do the following in your Jack Handy quotes buffer:

  1. Go to the beginning of the file
  2. Do C-spc
  3. Do M-f twice. You should see a highlighted region encompassing "If you".
  4. Press backspace. That should delete "If you".

One cool thing about using mark instead of shift-selecting text is that you're free to use all of Emacs's movement commands after you set the mark. For example, you could set a mark and then use C-s to search for some bit of text hundreds of lines down in your buffer. Doing so would create a very large region, and you wouldn't have to strain your pinky holding down the shift key.

Regions also let you operate within limited areas of the buffer:

  1. Create a region encompassing "The face of a child can say it all"
  2. Do M-x replace-string and replace "face" with "head"

This will perform the replacement only in the current region rather than the entire buffer after point, which is the default behavior.

7.4. Killing and the Kill Ring

In most applications we can "cut" text, which is mostly innocuous. We can also "copy" and "paste." Cutting and copying add the selection to the clipboard, and pasting copies the contents of the clipboard to the current application.

In Emacs, we take the homicidal approach and kill regions, adding them to do the kill ring. We then yank, inserting the most recently killed text at point. We can also copy text to the kill ring without actually killing it.

Why bother with all this morbid terminology? Well, first, so you won't be frightened when you hear someone talking about killing things in Emacs. But more importantly, Emacs allows you to do things that you can't do with the simple cut/copy/paste/clipboard featureset.

Emacs stores multiple blocks of text on the kill ring, and you can cycle through them. This is cool because you can cycle through the kill ring to retrieve text you killed a long time ago. Let's see this in action:

  1. Create a region over the word "Treasure" in the first line.
  2. Do M-w, which is bound to the kill-ring-save command.
  3. Move point to the word "choreograpahy" on the last line.
  4. Do M-d, which is bound to the kill-word command
  5. Do C-y. This will insert the text you just killed, "choreograpahy"
  6. Do M-y. This will remove "choreograpahy" and insert "Treasure"

So what just happened here? First, you added "Treasure" to the kill ring. Then you added "choreograpahy" to the kill ring . Next, you yanked "choreograpahy" from the kill ring. Finally, you replaced the last yank, "choreograpahy", with the previous kill, "Treasure".

Here's a summary of key bindings:

C-w Kill region
M-w Copy region to kill ring
C-y Yank
M-y Cycle through kill ring after yanking
M-d Kill word
C-k Kill line

8. More Resources

9. Summary

Whew! We covered a lot of ground:

With all of this hard-won Emacs knowledge under our belt, let's start using Emacs with Clojure!