Defining Functions

We usually give a name to a function when it is first created. This is called defining a function, and we usually do it with the defun macro. This section also describes other ways to define a function.

Macro: defun name args [doc] [declare] [interactive] body…

defun is the usual way to define new Lisp functions. It defines the symbol name as a function with argument list args (see Features of Argument Lists) and body forms given by body. Neither name nor args should be quoted.

doc, if present, should be a string specifying the function’s documentation string (see Documentation Strings of Functions). declare, if present, should be a declare form specifying function metadata (see The declare Form). interactive, if present, should be an interactive form specifying how the function is to be called interactively (see Interactive Call).

The return value of defun is undefined.

Here are some examples:

(defun foo () 5)
(foo)
     ⇒ 5

(defun bar (a &optional b &rest c)
    (list a b c))
(bar 1 2 3 4 5)
     ⇒ (1 2 (3 4 5))

(bar 1)
     ⇒ (1 nil nil)

(bar)
error→ Wrong number of arguments.

(defun capitalize-backwards ()
  "Upcase the last letter of the word at point."
  (interactive)
  (backward-word 1)
  (forward-word 1)
  (backward-char 1)
  (capitalize-word 1))

Most Emacs functions are part of the source code of Lisp programs, and are defined when the Emacs Lisp reader reads the program source before executing it. However, you can also define functions dynamically at run time, e.g., by generating defun calls when your program’s code is executed. If you do this, be aware that Emacs’s Help commands, such as C-h f, which present in the *Help* buffer a button to jump to the function’s definition, might be unable to find the source code because generating a function dynamically usually looks very different from the usual static calls to defun. You can make the job of finding the code that generates such functions easier by using the definition-name or find-function-type-alist property, see Standard Symbol Properties.

Be careful not to redefine existing functions unintentionally. defun redefines even primitive functions such as car without any hesitation or notification. Emacs does not prevent you from doing this, because redefining a function is sometimes done deliberately, and there is no way to distinguish deliberate redefinition from unintentional redefinition.

Function: defalias name definition &optional doc

This function defines the symbol name as a function, with definition definition. definition can be any valid Lisp function or macro, or a special form (see Special Forms), or a keymap (see Keymaps), or a vector or string (a keyboard macro). The return value of defalias is undefined.

If doc is non-nil, it becomes the function documentation of name. Otherwise, any documentation provided by definition is used.

Internally, defalias normally uses fset to set the definition. If name has a defalias-fset-function property, however, the associated value is used as a function to call in place of fset.

The proper place to use defalias is where a specific function or macro name is being defined—especially where that name appears explicitly in the source file being loaded. This is because defalias records which file defined the function, just like defun (see Unloading).

By contrast, in programs that manipulate function definitions for other purposes, it is better to use fset, which does not keep such records. See Accessing Function Cell Contents.

If the resulting function definition chain would be circular, then Emacs will signal a cyclic-function-indirection error.

Function: function-alias-p object

Checks whether object is a function alias. If it is, it returns a list of symbols representing the function alias chain, else nil. For instance, if a is an alias for b, and b is an alias for c:

(function-alias-p 'a)
    ⇒ (b c)

There is also a second, optional argument that is obsolete and has no effect.

You cannot create a new primitive function with defun or defalias, but you can use them to change the function definition of any symbol, even one such as car or x-popup-menu whose normal definition is a primitive. However, this is risky: for instance, it is next to impossible to redefine car without breaking Lisp completely. Redefining an obscure function such as x-popup-menu is less dangerous, but it still may not work as you expect. If there are calls to the primitive from C code, they call the primitive’s C definition directly, so changing the symbol’s definition will have no effect on them.

See also defsubst, which defines a function like defun and tells the Lisp compiler to perform inline expansion on it. See Inline Functions.

To undefine a function name, use fmakunbound. See Accessing Function Cell Contents.

• Finding Definitions