3.1 The defun Macro

In Lisp, a symbol such as mark-whole-buffer has code attached to it that tells the computer what to do when the function is called. This code is called the function definition and is created by evaluating a Lisp expression that starts with the symbol defun (which is an abbreviation for define function).

In subsequent sections, we will look at function definitions from the Emacs source code, such as mark-whole-buffer. In this section, we will describe a simple function definition so you can see how it looks. This function definition uses arithmetic because it makes for a simple example. Some people dislike examples using arithmetic; however, if you are such a person, do not despair. Hardly any of the code we will study in the remainder of this introduction involves arithmetic or mathematics. The examples mostly involve text in one way or another.

A function definition has up to five parts following the word defun:

1. The name of the symbol to which the function definition should be attached.
2. A list of the arguments that will be passed to the function. If no arguments will be passed to the function, this is an empty list, ().
3. Documentation describing the function. (Technically optional, but strongly recommended.)
4. Optionally, an expression to make 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 keychord.
5. The code that instructs the computer what to do: the body of the function definition.

It is helpful to think of the five parts of a function definition as being organized in a template, with slots for each part:

(defun function-name (arguments…)
  "optional-documentation…"
  (interactive argument-passing-info)     ; optional
  body…)

As an example, here is the code for a function that multiplies its argument by 7. (This example is not interactive. See Making a Function Interactive, for that information.)

(defun multiply-by-seven (number)
  "Multiply NUMBER by seven."
  (* 7 number))

This definition begins with a parenthesis and the symbol defun, followed by the name of the function.

The name of the function is followed by a list that contains the arguments that will be passed to the function. This list is called the argument list. In this example, the list has only one element, the symbol, number. When the function is used, the symbol will be bound to the value that is used as the argument to the function.

Instead of choosing the word number for the name of the argument, I could have picked any other name. For example, I could have chosen the word multiplicand. I picked the word “number” because it tells what kind of value is intended for this slot; but I could just as well have chosen the word “multiplicand” to indicate the role that the value placed in this slot will play in the workings of the function. I could have called it foogle, but that would have been a bad choice because it would not tell humans what it means. The choice of name is up to the programmer and should be chosen to make the meaning of the function clear.

Indeed, you can choose any name you wish for a symbol in an argument list, even the name of a symbol used in some other function: the name you use in an argument list is private to that particular definition. In that definition, the name refers to a different entity than any use of the same name outside the function definition. Suppose you have a nick-name “Shorty” in your family; when your family members refer to “Shorty”, they mean you. But outside your family, in a movie, for example, the name “Shorty” refers to someone else. Because a name in an argument list is private to the function definition, you can change the value of such a symbol inside the body of a function without changing its value outside the function. The effect is similar to that produced by a let expression. (See let.)

The argument list is followed by the documentation string that describes the function. This is what you see when you type C-h f and the name of a function. Incidentally, when you write a documentation string like this, you should make the first line a complete sentence since some commands, such as apropos, print only the first line of a multi-line documentation string. Also, you should not indent the second line of a documentation string, if you have one, because that looks odd when you use C-h f (describe-function). The documentation string is optional, but it is so useful, it should be included in almost every function you write.

The third line of the example consists of the body of the function definition. (Most functions’ definitions, of course, are longer than this.) In this function, the body is the list, (* 7 number), which says to multiply the value of number by 7. (In Emacs Lisp, * is the function for multiplication, just as + is the function for addition.)

When you use the multiply-by-seven function, the argument number evaluates to the actual number you want used. Here is an example that shows how multiply-by-seven is used; but don’t try to evaluate this yet!

(multiply-by-seven 3)

The symbol number, specified in the function definition in the next section, is bound to the value 3 in the actual use of the function. Note that although number was inside parentheses in the function definition, the argument passed to the multiply-by-seven function is not in parentheses. The parentheses are written in the function definition so the computer can figure out where the argument list ends and the rest of the function definition begins.

If you evaluate this example, you are likely to get an error message. (Go ahead, try it!) This is because we have written the function definition, but not yet told the computer about the definition—we have not yet loaded the function definition in Emacs. Installing a function is the process that tells the Lisp interpreter the definition of the function. Installation is described in the next section.