Previous Table of Contents Next


2.3. Example: Two Plus Two

Here is a simple program that illustrates, in a limited way, how Emacs Lisp works. In subsequent sections, I discuss primary concepts in more detail.

In Lisp, a program is a list. For example, (+ 2 2) is a list of three elements, +, 2, and 2. This list is a short program; when evaluated, it adds two plus two.

In Emacs, you can evaluate a program such as this by positioning your cursor after the closing parenthesis and typing C-x C-e. (There are other ways to evaluate a list; this is just one of the ways.)

If you evaluate this expression, the number 4 appears.

The first element of the list, +, is a function, which is to say, a program itself, that takes arguments which in this example are the numbers following the +, 2 and 2.

Here is another simple addition: (+ 2 (+ 1 1))

In this example, the list (+ 1 1) is embedded inside the list whose other elements are + and 2.

When the overall list, (+ 2 (+ 1 1)), is evaluated, the inner list is evaluated first, adding one plus one to produce two. Then the result of the first evaluation is provided as an argument to the outer +.

2.4. Evaluation

Here is what the Lisp interpreter does when it evaluates an expression. First, it checks whether there is a quote before the expression; if there is, the interpreter just gives the expression. On the other hand, if there is no quote, the interpreter checks whether the expression is a list, and if so, it looks at the first element in the list to see whether it has a function definition. If it does, the interpreter carries out the instructions in the function definition. Otherwise, the interpreter prints an error message.

Note that lists are not the only kind of expression in Lisp. The Lisp interpreter can also evaluate a symbol that is not quoted and does not have parentheses around it. In this case, the Lisp interpreter will attempt to determine the symbol’s value as a variable.

Moreover, some functions are unusual and do not work in the usual manner. These are called special forms. They are used for special jobs, such as defining a function, and there are not many of them.

Finally, if the Lisp interpreter is looking at a list that has a list inside it, the interpreter first figures out what it should do with the inside list, and then it works on the outside list. If there is yet another list embedded inside the inner list, it works on that one first, and so on. The result may be used by the enclosing expression.

Otherwise, the interpreter works left to right, from one expression to the next.

2.5. A Function Definition

You can write your own functions in Emacs Lisp using a special form called defun, which stands for function definition.

Here is an example of a function definition that upcases the last letter of a word.

   (defun capitalize-backward ()
     “Upcase the last letter of a word.”
     (interactive)
     (backward-word 1)           ; This is a comment.
     (forward-word 1)
     (backward-char 1)
     (capitalize-word 1))

This function definition has five parts following the word defun:

  The name of the symbol to which the function definition should be attached, in this case capitalize-backward.
  A list of the arguments that are passed to the function. In this case, there are none, so the list is an empty list.
  Documentation that describes what the function does.
  An expression that makes the function interactive so you can use it by typing M-x and then the name of the function; or by typing an appropriate key or set of keys (a keychord). In this case, you could run the function inside of Emacs (after loading it) by typing M-x capitalize-backward.
  The code that instructs the computer what to do: the body of the function definition.
In this definition, the code says to move point4 backward to the beginning of the word point is in, or if point is between words, to move to the beginning of the preceding word; then to move forward to the end of the word; then move back one character; and finally to capitalize the word (that is, the character) following point. (This latter action depends on the specific way capitalize-word works, which is to assume that point is at the beginning of the word, or before it in whitespace, and to uppercase the first non-whitespace character reached by moving forward.)

4Point is the location at which editing commands take effect. The cursor shows its position. Point always lies between two characters, although in some cases the shape of a cursor makes it look as if it were on top of a character rather than immediately before it.

The body also includes a comment, which is text between a semicolon and the end of a line. The Lisp interpreter ignores a comment. (Usually, of course, comments do more than simply announce themselves, as here; comments should be informative.)

That is all there is to it.

To make a definition such as this available for use, you need to evaluate the expression. You can do this by placing your cursor immediately after the closing parenthesis and typing C-x C-e.5


5You could also use eval-region to evaluate the region of text that makes up the definition, or insert the definition into a file of its own and use load-file or other load function to evaluate the function, or use yet other means. Load is another term for evaluate.)

Then, to use the definition, type M-x capitalize-backward.

Here, in brief, is a template of the five parts of a function definition:

   (defun function-name (arguments...)
     “optional-documentation...”
     ;; interactive section is optional
     (interactive argument-passing-info-if-any)
     body...)

Both documentation and the interactive section are optional.

As a practical matter, however, you should write documentation for every function you define. It will help you and whoever uses your function or reads your code.

Whether you make your function interactive depends on how it is to be used. If you expect a user will call it, make it interactive; if you expect it will be part of another definition and not called directly by a user, there is no need to make it interactive.


Previous Table of Contents Next