Introduction and First Steps

First Steps in Emacs

So, you've downloaded an Emacs package and installed it. Depending on what you downloaded and from where, there might be a friendly menu bar at the top with basic operations. Maybe not. There are two main boxes on your screen-- the big one you can obviously type in, and another at the bottom. The one at the top is your main view and the bottom one is the minibuffer where commands are run and user prompts happen.

Before proceding, here's a warning: most Emacs commands are driven by esoteric keyboard sequences. The manual writes key sequences the way that they are presented here. (I strongly recommend perusing the manual if you're serious about using Emacs. This tutorial will only teach you enough to become dangerous. To become elite, you must be one with the manual.) It's best learned by example— when you see something like C-x b (the switch buffer command), press and hold the Ctrl (C) and then press x, release both the ctrl and the x button and press b. Simple enough. If you see M-w (the equivalent of "copying" a selected area in Notepad or TextEdit-- spoken as "meta-w"), then press and hold Alt and press w, or, if you're on a terminal and the alt key doesn't work, press Esc, release it, then press w.

Most Important Keys

For commands involving filenames, TAB-completion works like in a terminal window. Begin typing and press tab to fill in the rest or bring up a completion buffer. Otherwise, terms ("save as", "paste", etc) comes from most text editors or IDEs presently in use.

These keys are the ones I use most and have committed to muscle memory from constant use. A strong suggestion is to leave Emacs running most/all of the time and simply create and destroy buffers rather than having many Emacses with lots of stuff open.

Each key sequence can be changed/removed in a configuration file. New key sequences can be added. They usual map to an internal command. You can run these commands by typing M-x command name. Pressing tab in the M-x prompt will show you all the commands. Running a command that's bound to a key sequence will actually cause Emacs to remind you in the minibuffer that you could have run that command by mashing some keys. That's actually how I learned some of these.

This list is far from complete and is missing lots of the more exciting features, but is meant for beginners to successfully navigate Emacs as well as they might any other text editor. The best help for Emacs is the manual-- available on their website or interactively through Emacs with C-h i (use the arrow keys and Enter to follow links).

Also mentioned in the above list, for beginners, Emacs comes with a tutorial. I strongly recommend playing it through.

First Steps in Emacs Lisp

After starting up Emacs, you may find yourself in a buffer called *Scratch*. This is a little playground for interpreting Elisp. Emacs Lisp is, I find, a little friendlier than Common Lisp since it can be treated like C or any other procedural language, but the syntax is a little strange. So, let's jump in! Type this into your *Scratch* buffer:

;Standard example!
(message "Hello, world!")

Then, with your cursor on immediately past the final ")" and press C-x C-e.

You'll see something strange happen. The expected Hello, world! will appear, but then, a split-second later, the quoted string "Hello, world!" will appear. That's a side-effect of executing a single line of Emacs code: it outputs the "return value" of that function to the minibuffer. To see all the messages from your program, visit the *Messages* buffer.

Lines that begin with a semicolon are comments. They are ignored by the evaluator if you were to execute the entire buffer. In C or Java, this is the equivalent of "//". In Basic, it's the equivalent of an apostrophe (') or the "REM" keyword.

To execute an entire buffer, use M-x eval-buffer.

A quick word about running Elisp programs-- the eval-buffer command in Emacs is the easiest and best way to run the program you're writing. If you want to temporarily assign a key to it, use M-x global-set-key, type the key you want assigned to run your program, press enter, then type eval-buffer. As always, there's tab completion to speed that up. Personally, I added this line to my ~/.emacs file to make my F6 key execute the current buffer:

(global-set-key (kbd "<f6>") 'eval-buffer)

To edit your default configuration, use C-x C-f ~/.emacs regardless of your operating system and start editing. That file is an Elisp file that gets executed on Emacs startup. Running M-x eval-buffer will force its effects on your current Emacs session.

If you're coming from a programming language like C or Java, this is a functional language. There are no keywords-- everything is (you guessed it) a function. It's also dynamically typed, so it's closer to JavaScript than Java when it comes to declaring variables. Let's take a look:

(setq name "Mark")
(message (concat "Hello, " name))

We've got three functions in the previous example: setq, message, and concat. Functions are within parentheses and stuff passed to functions (called their arguments) follow the function name. So, the arguments to setq are name and "Mark". The setq function takes a variable name and assigns it a value. This can also be written as:

(set 'name "Mark")

The "q" in setq removes the need for this apostrophe (single quote). setq has some other nifty side effects, too, like allowing mutliple variables to be set with a single function. Like so:

(setq
friday "warm friday"
fridayjr "cool friday"
)

Besides setq, which sets a global variable, sometimes we need need a temporary variable that's only used inside some function or small corner of your program. For that, we have let.

(let (
(i 0)
(b "Martians are destroying our world!")
(lastVariable "lastValue")
)
(message (concat b " but i is " (number-to-string i) " ... " lastVariable))
)

But I get ahead of myself... There'll be another example of let in the control structures segment (part 4).

Besides setq and message (which we had seen with the 'Hello World' example), there's concat. This function puts strings together, or concatenates them. This is another example (like setq) of a function that can take any number of arguments. Notice, also, that you can stick function calls inside other function calls. They work in precedence from the inside out— concat happens before message.

Since Elisp is functional, there's not much to teach in a tutorial like this. All the function names are self-documented within Emacs and there is no surprise syntactic sugar (i.e. generics or anonymous inner classes in Java or anything in Perl), all Elisp statements begin with a parenthesis and a function name followed by parameters. Naturally, there's more under the hood— some functions are macros or special forms, but they all work the same way.

Some Notes on Paradigms

Since most programmers come from (or are headed toward) a C or Java world, this tutorial is going to aim at some of the more "procedural" aspects of Elisp. C and Java are both procedural. Source code looks kind of like a recipe with ingredients (global varibles) and then steps to cook stuff (functions or methods and their step-by-step algorithms from start-to-finish).

Lisp, in general, tries to hide away these ingredients (seen here in set and setq) into the scope they're used and then throw them away. There's another syntax (let) that we'll see later on that's more globally accepted. Also, in Control Structures, this tutorial teaches if statements, for loops and while loops for their simplicity and familiarity for imperative programmers, while more purists favor recursion.

With all this said, there are a few different ways in Elisp to do things. None of them are wrong, per se. In the preliminary stages, it's hard to mess things up catastrophically, so be brave. Also, don't get discouraged if some dinosaur tells you that you're doing something incorrectly. The most important principles held herein are to have fun, keep learning, and make cool stuff.

Documentation

Lisp is designed to be self-documenting. Each function contains a place where users and implementors can define a documentation string. More importantly, it comes with extensive, interactive help! Use C-h i or, if you're on a terminal where C-h does backspace, use M-x info to open the info page. Choose "Elisp" then "Index" for the best resource for any function. It'll include the definition, a description, and, for some of the more fundamental or confusing things, an example.

As I did research for putting this tutorial together, I consulted the documentation a lot to ensure my examples were correct. In so doing, I remember a different resource, too: the built-in Elisp tutorial. Inside the "Info" screen, try "Emacs Lisp Introduction" and click around that. It's a bit more in-depth than this tutorial and it taught me a lot of what I used to get up and running.