defun Special Form
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). Because
defun does not evaluate its arguments in the usual way, it is
called a special form.
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:
().
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 section Make 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 case, 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 section 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 case, 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 given or "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 installed (or `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.
Go to the first, previous, next, last section, table of contents.