.EL File Format – Functions

defun and lambda

(defun NAME ARGLIST [DOCSTRING] [DECLARE] [INTERACTIVE] BODY…) stores a function in the function cell of NAME and returns NAME. (lambda ARGLIST [DOCSTRING] [INTERACTIVE] BODY…) makes an anonymous one. Both return the value of the last body form; a body with no forms returns nil. The order of the optional parts matters: the docstring comes first, the declare form next, then interactive.

(defun greet (name &optional greeting)
  "Return a greeting for NAME.
GREETING defaults to \"Hello\".

(fn NAME &optional GREETING)"
  (declare (pure t) (side-effect-free t))
  (format "%s, %s!" (or greeting "Hello") name))

Argument lists

The parameters of a lambda are local variables. There are no keyword parameters in the language itself; cl-defun adds them (below). A parameter whose name begins with an underscore signals to the compiler that it is unused. A function’s arity is found with func-arity, which returns (MIN . MAX) with many as MAX when there is a &rest.

Docstrings

The documentation is a string in the first position of the body, provided another form follows it, or provided it is the only body form (in which case it is also the return value). Its first line should be a full sentence that stands alone, because apropos shows only that line. Parameter names are written in capitals. Help shows the call signature taken from the argument list; if a function is advised, a macro, or compiled with a different list, the docstring may end with a line (fn ARGS), preceded by a blank line, to give the signature that should be displayed. A \\[command] sequence inside a docstring prints the key bound to a command, \\{map} prints a keymap, \\<map> chooses the keymap, and `symbol' or ‘symbol’ makes a link.

Closures

With lexical-binding on, evaluating a lambda (or function of one) yields a closure: the code plus the lexical variables it refers to. The captured variables live on after the form that made them has returned, and the closure can change them.

;;; -*- lexical-binding: t -*-
(defun make-counter ()
  (let ((n 0))
    (lambda () (setq n (1+ n)))))

(let ((c (make-counter)))
  (funcall c) (funcall c))   ; => 2

Before Emacs 30 the interpreter represented a closure as a list (closure ENV ARGS BODY…). From Emacs 30 the interpreter produces an interpreted-function object, and a byte-compiled function is a byte-code-function object; the two are laid out in the same slots (arguments, code, constants, depth, docstring, interactive form), and closurep is true for both. A list that starts with lambda is now only source code that is still callable. Under dynamic binding there are no closures: a lambda sees the variable values at the time of the call. See Data types and Variables and scope.

The function cell, aliases and indirection

A loop of aliases signals cyclic-function-indirection. The function cell may hold a lambda, a closure object, a byte-code object, a subr, a macro (macro . F), an autoload object, or a symbol.

Calling and mapping

The declare form

A (declare SPEC…) form at the top of a defun, defmacro or cl-defmethod body records facts about the definition. The specs are expanded by the macro at load time, through the lists defun-declarations-alist and macro-declarations-alist.

Advice

Advice wraps an existing function without editing it. nadvice.el provides advice-add for named functions and add-function for any place that holds a function (a variable, a hook slot, a process filter). The advice receives the original function as an argument when it is an :around.

(define-advice save-buffer (:before (&rest _) trim)
  (delete-trailing-whitespace))

(advice-add 'forward-line :around
            (lambda (orig n) (funcall orig (* 2 n))))

Common Lisp style definitions

Inline functions and primitives

A primitive (a subr) is written in C and has a fixed number of parameters from 0 up to 8, or takes MANY arguments as a vector, or is an UNEVALLED special form. From Lisp a subr is called like any function and signals wrong-number-of-arguments for a bad count; its arity is (MIN . MAX), where unevalled as MAX marks a special form. Help for a primitive shows a signature taken from the C source, which can differ from the real parameter names. Native compilation produces subr objects as well (Native compilation); the byte compiler is covered in Byte-compilation.

Not described

Known, not yet covered

• Reference: the full cl-defun lambda-list grammar and the dispatch rules of cl-defmethod (specialiser order, method combination) are outlined, not listed.
• Reference: the interactive spec codes, covered in Commands and modes, and the functions that call commands.
• Reference: oclosure is named, not described: its slot definitions, accessors and use in advice are not given.
• Reference: the versions that introduced define-inline, define-advice and cl-flet semantics are not stated; the pages for Emacs releases are in Emacs versions.

See also

• Macros – defmacro, compiler macros and expansion
• Variables and scope – lexical and dynamic binding
• Commands and modes – interactive and key bindings
• Byte-compilation – how functions become byte-code objects
• Functions – the manual’s chapter
• Advising Functions – the manual’s section on advice