eintr: defun
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. 
Making a
Function Interactive 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. (‘let’ 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.
Info Catalog
eintr: Primitive Functions
eintr: Writing Defuns
eintr: Install