A Lisp program is composed mainly of Lisp functions. This chapter explains what functions are, how they accept arguments, and how to define them.
declare FormIn a general sense, a function is a rule for carrying out a computation given input values called arguments. The result of the computation is called the value or return value of the function. The computation can also have side effects, such as lasting changes in the values of variables or the contents of data structures (see Definition of side effect). A pure function is a function which, in addition to having no side effects, always returns the same value for the same combination of arguments, regardless of external factors such as machine type or system state.
In most computer languages, every function has a name. But in Lisp,
a function in the strictest sense has no name: it is an object which
can optionally be associated with a symbol (e.g., car)
that serves as the function name. See Naming a Function. When a
function has been given a name, we usually also refer to that symbol
as a “function” (e.g., we refer to “the function car”).
In this manual, the distinction between a function name and the
function object itself is usually unimportant, but we will take note
wherever it is relevant.
Certain function-like objects, called special forms and macros, also accept arguments to carry out computations. However, as explained below, these are not considered functions in Emacs Lisp.
Here are important terms for functions and function-like objects:
A function (in the strict sense, i.e., a function object) which is written in Lisp. These are described in the following section. See Lambda Expressions.
A function which is callable from Lisp but is actually written in C.
Primitives are also called built-in functions, or subrs.
Examples include functions like car and append. In
addition, all special forms (see below) are also considered
primitives.
Usually, a function is implemented as a primitive because it is a
fundamental part of Lisp (e.g., car), or because it provides a
low-level interface to operating system services, or because it needs
to run fast. Unlike functions defined in Lisp, primitives can be
modified or added only by changing the C sources and recompiling
Emacs. See Writing Emacs Primitives.
A primitive that is like a function but does not evaluate all of its
arguments in the usual way. It may evaluate only some of the
arguments, or may evaluate them in an unusual order, or several times.
Examples include if, and, and while.
See Special Forms.
A construct defined in Lisp, which differs from a function in that it translates a Lisp expression into another expression which is to be evaluated instead of the original expression. Macros enable Lisp programmers to do the sorts of things that special forms can do. See Macros.
An object which can be invoked via the command-execute
primitive, usually due to the user typing in a key sequence
bound to that command. See Interactive Call. A command is
usually a function; if the function is written in Lisp, it is made
into a command by an interactive form in the function
definition (see Defining Commands). Commands that are functions
can also be called from Lisp expressions, just like other functions.
Keyboard macros (strings and vectors) are commands also, even though they are not functions. See Keyboard Macros. We say that a symbol is a command if its function cell contains a command (see Symbol Components); such a named command can be invoked with M-x.
A function object that is much like a lambda expression, except that it also encloses an environment of lexical variable bindings. See Closures.
A function that has been compiled by the byte compiler. See Closure Function Type.
A place-holder for a real function. If the autoload object is called, Emacs loads the file containing the definition of the real function, and then calls the real function. See Autoload.
You can use the function functionp to test if an object is a
function:
This function returns t if object is any kind of
function, i.e., can be passed to funcall. Note that
functionp returns t for symbols that are function names,
and returns nil for symbols that are macros or special forms.
If object is not a function, this function ordinarily returns
nil. However, the representation of function objects is
complicated, and for efficiency reasons in rare cases this function
can return t even when object is not a function.
It is also possible to find out how many arguments an arbitrary function expects:
This function provides information about the argument list of the
specified function. The returned value is a cons cell of the
form (min . max), where min is the
minimum number of arguments, and max is either the maximum
number of arguments, or the symbol many for functions with
&rest arguments, or the symbol unevalled if
function is a special form.
Note that this function might return inaccurate results in some situations, such as the following:
apply-partially (see apply-partially).
advice-add (see Advising Named Functions).
Unlike functionp, the next functions do not treat a symbol
as its function definition.
This function returns t if object is a built-in function
(i.e., a Lisp primitive).
(subrp 'message) ; message is a symbol,
⇒ nil ; not a subr object.
(subrp (symbol-function 'message))
⇒ t
This function returns t if object is a byte-code
function. For example:
(byte-code-function-p (symbol-function 'next-line))
⇒ t
This function returns t if object is a function object
that is not in the form of Lisp source code but something like
machine code or byte code instead. More specifically it returns
t if the function is built-in (a.k.a. “primitive”,
see What Is a Function?), or byte-compiled (see Byte Compilation), or native-compiled (see Compilation of Lisp to Native Code), or
a function loaded from a dynamic module (see Emacs Dynamic Modules).
This function returns t if object is an interpreted function.
This function returns t if object is a closure, which is
a particular kind of function object. Currently closures are used
for all byte-code functions and all interpreted functions.
This works like func-arity, but only for built-in functions and
without symbol indirection. It signals an error for non-built-in
functions. We recommend to use func-arity instead.
This function is like functionp, except it returns nil for
lists and symbols.
This function returns t if object is a built-in primitive
written in C (see Primitive Function Type). Note that special forms
are explicitly excluded, as they are not functions. Use
subr-primitive-p if you need to recognize special forms as well.
A lambda expression is a function object written in Lisp. Here is an example:
(lambda (x) "Return the hyperbolic cosine of X." (* 0.5 (+ (exp x) (exp (- x)))))
In Emacs Lisp, such a list is a valid expression which evaluates to a function object.
A lambda expression, by itself, has no name; it is an anonymous function. Although lambda expressions can be used this way (see Anonymous Functions), they are more commonly associated with symbols to make named functions (see Naming a Function). Before going into these details, the following subsections describe the components of a lambda expression and what they do.
A lambda expression is a list that looks like this:
(lambda (arg-variables...) [documentation-string] [interactive-declaration] body-forms...)
The first element of a lambda expression is always the symbol
lambda. This indicates that the list represents a function. The
reason functions are defined to start with lambda is so that
other lists, intended for other uses, will not accidentally be valid as
functions.
The second element is a list of symbols—the argument variable names (see Features of Argument Lists). This is called the lambda list. When a Lisp function is called, the argument values are matched up against the variables in the lambda list, which are given local bindings with the values provided. See Local Variables.
The documentation string is a Lisp string object placed within the function definition to describe the function for the Emacs help facilities. See Documentation Strings of Functions.
The interactive declaration is a list of the form (interactive
code-string). This declares how to provide arguments if the
function is used interactively. Functions with this declaration are called
commands; they can be called using M-x or bound to a key.
Functions not intended to be called in this way should not have interactive
declarations. See Defining Commands, for how to write an interactive
declaration.
The rest of the elements are the body of the function: the Lisp code to do the work of the function (or, as a Lisp programmer would say, “a list of Lisp forms to evaluate”). The value returned by the function is the value returned by the last element of the body.
Consider the following example:
(lambda (a b c) (+ a b c))
We can call this function by passing it to funcall, like this:
(funcall (lambda (a b c) (+ a b c))
1 2 3)
This call evaluates the body of the lambda expression with the variable
a bound to 1, b bound to 2, and c bound to 3.
Evaluation of the body adds these three numbers, producing the result 6;
therefore, this call to the function returns the value 6.
Note that the arguments can be the results of other function calls, as in this example:
(funcall (lambda (a b c) (+ a b c))
1 (* 2 3) (- 5 4))
This evaluates the arguments 1, (* 2 3), and (- 5
4) from left to right. Then it applies the lambda expression to the
argument values 1, 6 and 1 to produce the value 8.
As these examples show, you can use a form with a lambda expression
as its CAR to make local variables and give them values. In the
old days of Lisp, this technique was the only way to bind and
initialize local variables. But nowadays, it is clearer to use the
special form let for this purpose (see Local Variables).
Lambda expressions are mainly used as anonymous functions for passing
as arguments to other functions (see Anonymous Functions), or
stored as symbol function definitions to produce named functions
(see Naming a Function).
Our simple sample function, (lambda (a b c) (+ a b c)),
specifies three argument variables, so it must be called with three
arguments: if you try to call it with only two arguments or four
arguments, you get a wrong-number-of-arguments error
(see Errors).
It is often convenient to write a function that allows certain
arguments to be omitted. For example, the function substring
accepts three arguments—a string, the start index and the end
index—but the third argument defaults to the length of the
string if you omit it. It is also convenient for certain functions to
accept an indefinite number of arguments, as the functions list
and + do.
To specify optional arguments that may be omitted when a function
is called, simply include the keyword &optional before the optional
arguments. To specify a list of zero or more extra arguments, include the
keyword &rest before one final argument.
Thus, the complete syntax for an argument list is as follows:
(required-vars... [&optional [optional-vars...]] [&rest rest-var])
The square brackets indicate that the &optional and &rest
clauses, and the variables that follow them, are optional.
A call to the function requires one actual argument for each of the
required-vars. There may be actual arguments for zero or more of
the optional-vars, and there cannot be any actual arguments beyond
that unless the lambda list uses &rest. In that case, there may
be any number of extra actual arguments.
If actual arguments for the optional and rest variables are omitted,
then they always default to nil. There is no way for the
function to distinguish between an explicit argument of nil and
an omitted argument. However, the body of the function is free to
consider nil an abbreviation for some other meaningful value.
This is what substring does; nil as the third argument to
substring means to use the length of the string supplied.
Common Lisp note: Common Lisp allows the function to specify what default value to use when an optional argument is omitted; Emacs Lisp always uses
nil. Emacs Lisp does not supportsupplied-pvariables that tell you whether an argument was explicitly passed.
For example, an argument list that looks like this:
(a b &optional c d &rest e)
binds a and b to the first two actual arguments, which are
required. If one or two more arguments are provided, c and
d are bound to them respectively; any arguments after the first
four are collected into a list and e is bound to that list.
Thus, if there are only two arguments, c, d and e
are nil; if two or three arguments, d and e are
nil; if four arguments or fewer, e is nil. Note
that exactly five arguments with an explicit nil argument
provided for e will cause that nil argument to be passed
as a list with one element, (nil), as with any other single
value for e.
There is no way to have required arguments following optional
ones—it would not make sense. To see why this must be so, suppose
that c in the example were optional and d were required.
Suppose three actual arguments are given; which variable would the
third argument be for? Would it be used for the c, or for
d? One can argue for both possibilities. Similarly, it makes
no sense to have any more arguments (either required or optional)
after a &rest argument.
Here are some examples of argument lists and proper calls:
(funcall (lambda (n) (1+ n)) ; One required: 1) ; requires exactly one argument. ⇒ 2 (funcall (lambda (n &optional n1) ; One required and one optional: (if n1 (+ n n1) (1+ n))) ; 1 or 2 arguments. 1 2) ⇒ 3 (funcall (lambda (n &rest ns) ; One required and one rest: (+ n (apply '+ ns))) ; 1 or more arguments. 1 2 3 4 5) ⇒ 15
A lambda expression may optionally have a documentation string just after the lambda list. This string does not affect execution of the function; it is a kind of comment, but a systematized comment which actually appears inside the Lisp world and can be used by the Emacs help facilities. See Documentation, for how the documentation string is accessed.
It is a good idea to provide documentation strings for all the functions in your program, even those that are called only from within your program. Documentation strings are like comments, except that they are easier to access.
The first line of the documentation string should stand on its own,
because apropos displays just this first line. It should consist
of one or two complete sentences that summarize the function’s purpose.
The start of the documentation string is usually indented in the source file, but since these spaces come before the starting double-quote, they are not part of the string. Some people make a practice of indenting any additional lines of the string so that the text lines up in the program source. That is a mistake. The indentation of the following lines is inside the string; what looks nice in the source code will look ugly when displayed by the help commands.
A documentation string must always be followed by at least one Lisp
expression; otherwise, it is not a documentation string at all but the
single expression of the body and used as the return value.
When there is no meaningful value to return from a function, it is
standard practice to return nil by adding it after the
documentation string.
The last line of the documentation string can specify calling conventions different from the actual function arguments. Write text like this:
\(fn arglist)
following a blank line, at the beginning of the line, with no newline following it inside the documentation string. (The ‘\’ is used to avoid confusing the Emacs motion commands.) The calling convention specified in this way appears in help messages in place of the one derived from the actual arguments of the function.
This feature is particularly useful for macro definitions, since the arguments written in a macro definition often do not correspond to the way users think of the parts of the macro call.
Do not use this feature if you want to deprecate the calling
convention and favor the one you advertise by the above specification.
Instead, use the advertised-calling-convention declaration
(see The declare Form) or set-advertised-calling-convention
(see Declaring Functions Obsolete), because these two will cause the byte
compiler emit a warning message when it compiles Lisp programs which
use the deprecated calling convention.
The (fn) feature is typically used in the following situations:
(defmacro lambda (&rest cdr) "... \(fn ARGS [DOCSTRING] [INTERACTIVE] BODY)"...)
(defmacro macroexp--accumulate (var+list &rest body) "... \(fn (VAR LIST) BODY...)" (declare (indent 1)) (let ((var (car var+list)) (list (cadr var+list)) ...)))
defalias. Example:
(defalias 'abbrev-get 'get "... \(fn ABBREV PROP)")
Documentation strings are usually static, but occasionally it can be
necessary to generate them dynamically. In some cases you can do so
by writing a macro which generates at compile time the code of the
function, including the desired documentation string. But you can
also generate the docstring dynamically by writing
(:documentation form) instead of the documentation
string. This will evaluate form at run-time when the function
is defined and use it as the documentation string15. You can also compute
the documentation string on the fly when it is requested, by setting
the function-documentation property of the function’s symbol to
a Lisp form that evaluates to a string.
For example:
(defun adder (x)
(lambda (y)
(:documentation (format "Add %S to the argument Y." x))
(+ x y)))
(defalias 'adder5 (adder 5))
(documentation 'adder5)
⇒ "Add 5 to the argument Y."
(put 'adder5 'function-documentation
'(concat (documentation (symbol-function 'adder5) 'raw)
" Consulted at " (format-time-string "%H:%M:%S")))
(documentation 'adder5)
⇒ "Add 5 to the argument Y. Consulted at 15:52:13"
(documentation 'adder5)
⇒ "Add 5 to the argument Y. Consulted at 15:52:18"
A symbol can serve as the name of a function. This happens when the symbol’s function cell (see Symbol Components) contains a function object (e.g., a lambda expression). Then the symbol itself becomes a valid, callable function, equivalent to the function object in its function cell.
The contents of the function cell are also called the symbol’s function definition. The procedure of using a symbol’s function definition in place of the symbol is called symbol function indirection; see Symbol Function Indirection. If you have not given a symbol a function definition, its function cell is said to be void, and it cannot be used as a function.
In practice, nearly all functions have names, and are referred to by
their names. You can create a named Lisp function by defining a
lambda expression and putting it in a function cell (see Accessing Function Cell Contents). However, it is more common to use the defun macro,
described in the next section.
See Defining Functions.
We give functions names because it is convenient to refer to them by their names in Lisp expressions. Also, a named Lisp function can easily refer to itself—it can be recursive. Furthermore, primitives can only be referred to textually by their names, since primitive function objects (see Primitive Function Type) have no read syntax.
A function need not have a unique name. A given function object
usually appears in the function cell of only one symbol, but
this is just a convention. It is easy to store it in several symbols
using fset; then each of the symbols is a valid name for the
same function.
Note that a symbol used as a function name may also be used as a variable; these two uses of a symbol are independent and do not conflict. (This is not the case in some dialects of Lisp, like Scheme.)
By convention, if a function’s symbol consists of two names
separated by ‘--’, the function is intended for internal use and
the first part names the file defining the function. For example, a
function named vc-git--rev-parse is an internal function
defined in vc-git.el. Internal-use functions written in C have
names ending in ‘-internal’, e.g., bury-buffer-internal.
Emacs code contributed before 2018 may follow other internal-use
naming conventions, which are being phased out.
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.
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.
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.
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.
Tools such as Emacs’s built-in help command C-h f (see Help in The GNU Emacs Manual) can find the definition site of functions
and other Lisp objects in the source code. To do this, they use the
variable find-function-regexp-alist.
The alist find-function-regexp-alist associates object types with
a regexp or a function that finds the definition of that object in its
source file. Each element’s car is a symbol that describes the
type of object, or nil, which means a function defined with
defun. Each element’s cdr can be one of the following:
car is a regexp (or function that returns
one) and the cdr is form-matcher: a function that creates a
matcher for macro-expanded forms.
A regexp string is actually a format string, and %s will be
substituted with the name of the symbol we are looking for.
A function will be called with one argument, the (symbol for) the object we are searching for.
The form-matcher function in a cons cell value is called with one
argument (the symbol being sought) and should return a function; that
function should take a form and return non-nil if the form
defines the sought symbol. This is useful for finding definitions that
are created by expansion of macros.
If the function to be found is defined by a macro, it may be hard for
Emacs to find the definition site in the source code. A macro call may
have an unexpected look to it, and find-function-regexp-alist
will fail to identify the definition.
For example, a define-derived-mode (see Defining Derived Modes) might
define a mode-specific function or a variable implicitly; or your Lisp
program might generate a run-time call to defun to define a
function. In these and similar cases, the definition-name
property of the symbol should be another symbol whose definition can be
found by textual search and whose code defines the original symbol. In
the example with define-derived-mode, the value of this property
of the functions and variables it defines should be the mode symbol.
In some cases, the definition cannot be found by looking for the
definition of another symbol. For example, a test file might use a
macro to generate calls to ert-deftest (see How to Write
Tests in ERT: Emacs Lisp Regression Testing) where the code is
boiler plate and only varying data need to be passed in. In such cases,
the find-function-type-alist property of the symbol can be an
alist that augments find-function-regexp-alist telling how to
find the definition of symbols of this type.
The find-function-regexp-alist property is most easily maintained
with the convenience function find-function-update-type-alist.
Update property find-function-type-alist of symbol with
a new element containing key type and value variable.
In the example of a macro defining calls to ert-deftest,
the macro could put the property find-function-type-alist on each
test defined, associating ert--test (the internal type of ERT
tests) with the name of a regexp or function that can find the correct
macro call. The file defining the macro would also have to provide that
definition-finding function or regexp.
Here is an example using a function to find the definition:
(defmacro define-foo-test (data)
"Define a test of the foo system using DATA."
(declare (debug (&rest sexp)))
(let ((test-name (intern (concat ...))))
`(progn
(find-function-update-type-alist
',test-name 'ert--test 'foo-find-test-def-function)
(ert-deftest ,test-name ()
,(concat "Test foo with " ...)
...))))
(defun foo-find-test-def-function (test-name)
"Search for the `define-foo-test' call defining TEST-NAME.
Return non-nil if the definition is found."
(let ((regexp ...))
(re-search-forward regexp nil t)))
Defining functions is only half the battle. Functions don’t do anything until you call them, i.e., tell them to run. Calling a function is also known as invocation.
The most common way of invoking a function is by evaluating a list.
For example, evaluating the list (concat "a" "b") calls the
function concat with arguments "a" and "b".
See Evaluation, for a description of evaluation.
When you write a list as an expression in your program, you specify
which function to call, and how many arguments to give it, in the text
of the program. Usually that’s just what you want. Occasionally you
need to compute at run time which function to call. To do that, use
the function funcall. When you also need to determine at run
time how many arguments to pass, use apply.
funcall calls function with arguments, and returns
whatever function returns.
Since funcall is a function, all of its arguments, including
function, are evaluated before funcall is called. This
means that you can use any expression to obtain the function to be
called. It also means that funcall does not see the
expressions you write for the arguments, only their values.
These values are not evaluated a second time in the act of
calling function; the operation of funcall is like the
normal procedure for calling a function, once its arguments have
already been evaluated.
The argument function must be either a Lisp function or a
primitive function. Special forms and macros are not allowed, because
they make sense only when given the unevaluated argument
expressions. funcall cannot provide these because, as we saw
above, it never knows them in the first place.
If you need to use funcall to call a command and make it behave
as if invoked interactively, use funcall-interactively
(see Interactive Call).
(setq f 'list)
⇒ list
(funcall f 'x 'y 'z)
⇒ (x y z)
(funcall f 'x 'y '(z))
⇒ (x y (z))
(funcall 'and t nil) error→ Invalid function: #<subr and>
Compare these examples with the examples of apply.
apply calls function with arguments, just like
funcall but with one difference: the last of arguments is a
list of objects, which are passed to function as separate
arguments, rather than a single list. We say that apply
spreads this list so that each individual element becomes an
argument.
apply with a single argument is special: the first element of
the argument, which must be a non-empty list, is called as a function
with the remaining elements as individual arguments. Passing two or
more arguments will be faster.
apply returns the result of calling function. As with
funcall, function must either be a Lisp function or a
primitive function; special forms and macros do not make sense in
apply.
(setq f 'list)
⇒ list
(apply f 'x 'y 'z) error→ Wrong type argument: listp, z
(apply '+ 1 2 '(3 4))
⇒ 10
(apply '+ '(1 2 3 4))
⇒ 10
(apply 'append '((a b c) nil (x y z) nil))
⇒ (a b c x y z)
(apply '(+ 3 4))
⇒ 7
For an interesting example of using apply, see Definition of mapcar.
Sometimes it is useful to fix some of the function’s arguments at certain values, and leave the rest of arguments for when the function is actually called. The act of fixing some of the function’s arguments is called partial application of the function16. The result is a new function that accepts the rest of arguments and calls the original function with all the arguments combined.
In Emacs Lisp, this is best done with an anonymous function. For example, if you have a function ‘my-function’ that takes two arguments, you could do something like this:
(mapcar (lambda (x) (my-function 123 x)) ...)
You can also do partial application using the function
apply-partially. However, this will be slower than using an
anonymous function with lambda.
This function returns a new function which, when called, will call
func with the list of arguments composed from args and
additional arguments specified at the time of the call. If func
accepts n arguments, then a call to apply-partially with
m <= n arguments will produce a new function of
n - m arguments17.
Here’s how we could define the built-in function 1+, if it
didn’t exist, using apply-partially and +, another
built-in function18:
(defalias '1+ (apply-partially '+ 1) "Increment argument by one.")
(1+ 10)
⇒ 11
It is common for Lisp functions to accept functions as arguments or
find them in data structures (especially in hook variables and property
lists) and call them using funcall or apply. Functions
that accept function arguments are often called functionals.
Sometimes, when you call a functional, it is useful to supply a no-op function as the argument. Here are three different kinds of no-op functions:
This function returns argument and has no side effects.
This function ignores any arguments and returns nil.
This function ignores any arguments and returns t.
Some functions are user-visible commands, which can be called
interactively (usually by a key sequence). It is possible to invoke
such a command exactly as though it was called interactively, by using
the call-interactively function. See Interactive Call.
A mapping function applies a given function (not a
special form or macro) to each element of a sequence, such as a list or
a vector or a string (see Sequences, Arrays, and Vectors).
Emacs Lisp has several such functions; this section describes
mapcar, mapc, mapconcat, and mapcan, which
map over sequences. See Definition of mapatoms, for the function
mapatoms which maps over the symbols in an obarray.
See Definition of maphash, for the function maphash which
maps over key/value associations in a hash table.
These mapping functions do not work on char-tables because a char-table
is a sparse array whose nominal range of indices is very large. To map
over a char-table in a way that deals properly with its sparse nature,
use the function map-char-table (see Char-Tables).
mapcar applies function to each element of sequence
in turn, and returns a list of the results.
The argument sequence can be any kind of sequence except a char-table; that is, a list, a vector, a bool-vector, or a string. The result is always a list. The length of the result is the same as the length of sequence. For example:
(mapcar #'car '((a b) (c d) (e f)))
⇒ (a c e)
(mapcar #'1+ [1 2 3])
⇒ (2 3 4)
(mapcar #'string "abc")
⇒ ("a" "b" "c")
;; Call each function in my-hooks.
(mapcar 'funcall my-hooks)
(defun mapcar* (function &rest args) "Apply FUNCTION to successive cars of all ARGS. Return the list of results." ;; If no list is exhausted, (if (not (memq nil args)) ;; apply function to CARs. (cons (apply function (mapcar #'car args)) (apply #'mapcar* function ;; Recurse for rest of elements. (mapcar #'cdr args)))))
(mapcar* #'cons '(a b c) '(1 2 3 4))
⇒ ((a . 1) (b . 2) (c . 3))
This function applies function to each element of
sequence, like mapcar, but instead of collecting the
results into a list, it returns a single list with all the elements of
the results (which must be lists), by altering the results (using
nconc; see Functions that Rearrange Lists). Like with mapcar,
sequence can be of any type except a char-table.
;; Contrast this: (mapcar #'list '(a b c d)) ⇒ ((a) (b) (c) (d)) ;; with this: (mapcan #'list '(a b c d)) ⇒ (a b c d)
mapc is like mapcar except that function is used for
side-effects only—the values it returns are ignored, not collected
into a list. mapc always returns sequence.
mapconcat applies function to each element of
sequence; the results, which must be sequences of characters
(strings, vectors, or lists), are concatenated into a single string
return value. Between each pair of result sequences, mapconcat
inserts the characters from separator, which also must be a
string, or a vector or list of characters; a nil value is
treated as the empty string. See Sequences, Arrays, and Vectors.
The argument function must be a function that can take one argument and returns a sequence of characters: a string, a vector, or a list. The argument sequence can be any kind of sequence except a char-table; that is, a list, a vector, a bool-vector, or a string.
(mapconcat #'symbol-name
'(The cat in the hat)
" ")
⇒ "The cat in the hat"
(mapconcat (lambda (x) (format "%c" (1+ x)))
"HAL-8000")
⇒ "IBM.9111"
Although functions are usually defined with defun and given
names at the same time, it is sometimes convenient to use an explicit
lambda expression—an anonymous function. Anonymous functions
are valid wherever function names are. They are often assigned as
variable values, or as arguments to functions; for instance, you might
pass one as the function argument to mapcar, which
applies that function to each element of a list (see Mapping Functions). See describe-symbols example, for a realistic example
of this.
When defining a lambda expression that is to be used as an anonymous
function, you should use the lambda macro, or the
function special form, or the #' read syntax:
This macro returns an anonymous function with argument list args, documentation string doc (if any), interactive spec interactive (if any), and body forms given by body.
For example, this macro makes lambda forms almost self-quoting:
evaluating a form whose CAR is lambda yields a value that is
almost like the form itself:
(lambda (x) (* x x))
⇒ #f(lambda (x) :dynbind (* x x))
When evaluating under lexical binding the result is a similar
closure object, where the :dynbind marker is replaced by the
captured variables (see Closures).
The lambda form has one other effect: it tells the Emacs
evaluator and byte-compiler that its argument is a function, by using
function as a subroutine (see below).
This special form returns the function value of the function-object.
In many ways, it is similar to quote (see Quoting). But unlike
quote, it also serves as a note to the Emacs evaluator and
byte-compiler that function-object is intended to be used as a
function. Assuming function-object is a valid lambda
expression, this has two effects:
When function-object is a symbol and the code is byte compiled, the byte-compiler will warn if that function is not defined or might not be known at run time.
The read syntax #' is a short-hand for using function.
The following forms are all equivalent:
(lambda (x) (* x x)) (function (lambda (x) (* x x))) #'(lambda (x) (* x x))
In the following example, we define a change-property
function that takes a function as its third argument, followed by a
double-property function that makes use of
change-property by passing it an anonymous function:
(defun change-property (symbol prop function)
(let ((value (get symbol prop)))
(put symbol prop (funcall function value))))
(defun double-property (symbol prop) (change-property symbol prop (lambda (x) (* 2 x))))
Note that we do not quote the lambda form.
If you compile the above code, the anonymous function is also compiled. This would not happen if, say, you had constructed the anonymous function by quoting it as a list:
(defun double-property (symbol prop) (change-property symbol prop '(lambda (x) (* 2 x))))
In that case, the anonymous function is kept as a lambda expression in
the compiled code. The byte-compiler cannot assume this list is a
function, even though it looks like one, since it does not know that
change-property intends to use it as a function.
Functions defined using defun have a hard-coded set of
assumptions about the types and expected values of their arguments.
For example, a function that was designed to handle values of its
argument that are either numbers or lists of numbers will fail or
signal an error if called with a value of any other type, such as a
vector or a string. This happens because the implementation of the
function is not prepared to deal with types other than those assumed
during the design.
By contrast, object-oriented programs use polymorphic functions: a set of specialized functions having the same name, each one of which was written for a certain specific set of argument types. Which of the functions is actually called is decided at run time based on the types of the actual arguments.
Emacs provides support for polymorphism. Like other Lisp environments, notably Common Lisp and its Common Lisp Object System (CLOS), this support is based on generic functions. The Emacs generic functions closely follow CLOS, including use of similar names, so if you have experience with CLOS, the rest of this section will sound very familiar.
A generic function specifies an abstract operation, by defining its
name and list of arguments, but (usually) no implementation. The
actual implementation for several specific classes of arguments is
provided by methods, which should be defined separately. Each
method that implements a generic function has the same name as the
generic function, but the method’s definition indicates what kinds of
arguments it can handle by specializing the arguments defined by
the generic function. These argument specializers can be more
or less specific; for example, a string type is more specific
than a more general type, such as sequence.
Note that, unlike in message-based OO languages, such as C++ and
Simula, methods that implement generic functions don’t belong to a
class, they belong to the generic function they implement.
When a generic function is invoked, it selects the applicable methods by comparing the actual arguments passed by the caller with the argument specializers of each method. A method is applicable if the actual arguments of the call are compatible with the method’s specializers. If more than one method is applicable, they are combined using certain rules, described below, and the combination then handles the call.
This macro defines a generic function with the specified name
and arguments. If body is present, it provides the
default implementation. If documentation is present (it should
always be), it specifies the documentation string for the generic
function, in the form (:documentation docstring). The
optional options-and-methods can be one of the following forms:
(declare declarations)A declare form, as described in The declare Form.
(:argument-precedence-order &rest args)This form affects the sorting order for combining applicable methods. Normally, when two methods are compared during combination, method arguments are examined left to right, and the first method whose argument specializer is more specific will come before the other one. The order defined by this form overrides that, and the arguments are examined according to their order in this form, and not left to right.
(:method [qualifiers…] args &rest body)This form defines a method like cl-defmethod does.
This macro defines a particular implementation for the generic
function called name. The implementation code is given by
body. If present, docstring is the documentation string
for the method. The arguments list, which must be identical in
all the methods that implement a generic function, and must match the
argument list of that function, provides argument specializers of the
form (arg spec), where arg is the argument
name as specified in the cl-defgeneric call, and spec is
one of the following specializer forms:
typeThis specializer requires the argument to be of the given type, one of the types from the type hierarchy described below.
(eql object)This specializer requires the argument be eql to the given
object.
(head object)The argument must be a cons cell whose car is eql to
object.
struct-typeThe argument must be an instance of a class named struct-type
defined with cl-defstruct (see Structures in Common Lisp
Extensions for GNU Emacs Lisp), or of one of its child classes.
Method definitions can make use of a new argument-list keyword,
&context, which introduces extra specializers that test the
environment at the time the method is run. This keyword should appear
after the list of required arguments, but before any &rest or
&optional keywords. The &context specializers look much
like regular argument specializers—(expr spec)—except
that expr is an expression to be evaluated in the current
context, and the spec is a value to compare against. For
example, &context (overwrite-mode (eql t)) will make the method
applicable only when overwrite-mode is turned on. The
&context keyword can be followed by any number of context
specializers. Because the context specializers are not part of the
generic function’s argument signature, they may be omitted in methods
that don’t require them.
The type specializer, (arg type), can specify one
of the system types in the following list. When a parent type
is specified, an argument whose type is any of its more specific child
types, as well as grand-children, grand-grand-children, etc. will also
be compatible.
integerParent type: number.
numbernullParent type: symbol
symbolstringParent type: array.
arrayParent type: sequence.
consParent type: list.
listParent type: sequence.
markeroverlayfloatParent type: number.
window-configurationprocesswindowsubrcompiled-functionbufferchar-tableParent type: array.
bool-vectorParent type: array.
vectorParent type: array.
framehash-tablefont-specfont-entityfont-objectThe optional extra element, expressed as ‘:extra string’, allows you to add more methods, distinguished by string, for the same specializers and qualifiers.
The optional qualifier allows combining several applicable methods. If it is not present, the defined method is a primary method, responsible for providing the primary implementation of the generic function for the specialized arguments. You can also define auxiliary methods, by using one of the following values as qualifier:
:beforeThis auxiliary method will run before the primary method. More
accurately, all the :before methods will run before the
primary, in the most-specific-first order.
:afterThis auxiliary method will run after the primary method. More accurately, all such methods will run after the primary, in the most-specific-last order.
:aroundThis auxiliary method will run instead of the primary method.
The most specific of such methods will be run before any other method.
Such methods normally use cl-call-next-method, described below,
to invoke the other auxiliary or primary methods.
Functions defined using cl-defmethod cannot be made
interactive, i.e. commands (see Defining Commands), by adding
the interactive form to them. If you need a polymorphic
command, we recommend defining a normal command that calls a
polymorphic function defined via cl-defgeneric and
cl-defmethod.
Each time a generic function is called, it builds the effective method which will handle this invocation by combining the applicable methods defined for the function. The process of finding the applicable methods and producing the effective method is called dispatch. The applicable methods are those all of whose specializers are compatible with the actual arguments of the call. Since all of the arguments must be compatible with the specializers, they all determine whether a method is applicable. Methods that explicitly specialize more than one argument are called multiple-dispatch methods.
The applicable methods are sorted into the order in which they will be
combined. The method whose left-most argument specializer is the most
specific one will come first in the order. (Specifying
:argument-precedence-order as part of cl-defmethod
overrides that, as described above.) If the method body calls
cl-call-next-method, the next most-specific method will run.
If there are applicable :around methods, the most-specific of
them will run first; it should call cl-call-next-method to run
any of the less specific :around methods. Next, the
:before methods run in the order of their specificity, followed
by the primary method, and lastly the :after methods in the
reverse order of their specificity.
When invoked from within the lexical body of a primary or an
:around auxiliary method, call the next applicable method for
the same generic function. Normally, it is called with no arguments,
which means to call the next applicable method with the same arguments
that the calling method was invoked. Otherwise, the specified
arguments are used instead.
This function, when called from within the lexical body of a primary
or an :around auxiliary method, returns non-nil if there
is a next method to call.
The function definition of a symbol is the object stored in the function cell of the symbol. The functions described here access, test, and set the function cell of symbols.
See also the function indirect-function. See Definition of indirect-function.
This returns the object in the function cell of symbol. It does
not check that the returned object is a legitimate function.
If the function is void, the return value is nil.
(defun bar (n) (+ n 2))
(symbol-function 'bar)
⇒ #f(lambda (n) [t] (+ n 2))
(fset 'baz 'bar)
⇒ bar
(symbol-function 'baz)
⇒ bar
If you have never given a symbol any function definition, its function
cell contains the default value nil and we say
that that function is void. If you try to call
the symbol as a function, Emacs signals a void-function error.
Unlike with void variables (see When a Variable is Void), a symbol’s
function cell that contains nil is indistinguishable from the
function’s being void. Note that void is not the same as the symbol
void: void can be a valid function if you define it with
defun.
You can test the voidness of a symbol’s function definition with
fboundp. After you have given a symbol a function definition, you
can make it void once more using fmakunbound.
This function returns t if the symbol has a non-nil object
in its function cell, nil otherwise. It does not check that the
object is a legitimate function.
This function makes symbol’s function cell nil, so that a
subsequent attempt to access this cell will cause a
void-function error. It returns symbol. (See also
makunbound, in When a Variable is Void.)
(defun foo (x) x)
(foo 1)
⇒1
(fmakunbound 'foo)
⇒ foo
(foo 1) error→ Symbol's function definition is void: foo
This function stores definition in the function cell of symbol. The result is definition. Normally definition should be a function or the name of a function, but this is not checked. The argument symbol is an ordinary evaluated argument.
The primary use of this function is as a subroutine by constructs that define
or alter functions, like defun or advice-add (see Advising Emacs Lisp Functions). You can also use it to give a symbol a function definition that
is not a function, e.g., a keyboard macro (see Keyboard Macros):
;; Define a named keyboard macro.
(fset 'kill-two-lines "\^u2\^k")
⇒ "\^u2\^k"
If you wish to use fset to make an alternate name for a
function, consider using defalias instead. See Definition of defalias.
If the resulting function definition chain would be circular, then
Emacs will signal a cyclic-function-indirection error.
As explained in Scoping Rules for Variable Bindings, Emacs can optionally enable
lexical binding of variables. When lexical binding is enabled, any
named function that you create (e.g., with defun), as well as
any anonymous function that you create using the lambda macro
or the function special form or the #' syntax
(see Anonymous Functions), is automatically converted into a
closure.
A closure is a function that also carries a record of the lexical environment that existed when the function was defined. When it is invoked, any lexical variable references within its definition use the retained lexical environment. In all other respects, closures behave much like ordinary functions; in particular, they can be called in the same way as ordinary functions.
See Lexical Binding, for an example of using a closure.
;; lexical binding is enabled.
(lambda (x) (* x x))
⇒ #f(lambda (x) [t] (* x x))
The internal structure of a closure is an implementation matter and we recommend against examining or altering it directly. For the curious, see Closure Function Objects.
Traditionally, functions are opaque objects which offer no other functionality but to call them. (Emacs Lisp functions aren’t fully opaque since you can extract some info out of them such as their docstring, their arglist, or their interactive spec, but they are still mostly opaque.) This is usually what we want, but occasionally we need functions to expose a bit more information about themselves.
Open closures, or OClosures for short, are function objects which carry additional type information and expose some information about themselves in the form of slots which you can access via accessor functions.
OClosures are defined in two steps: first you use
oclosure-define to define a new OClosure type by specifying the
slots carried by the OClosures of this type, and then you use
oclosure-lambda to create an OClosure object of a given type.
Let’s say we want to define keyboard macros, i.e. interactive functions which re-execute a sequence of key events (see Keyboard Macros). You could do it with a plain function as follows:
(defun kbd-macro (key-sequence)
(lambda (&optional arg)
(interactive "P")
(execute-kbd-macro key-sequence arg)))
But with such a definition there is no easy way to extract the key-sequence from that function, for example to print it.
We can solve this problem using OClosures as follows. First we define
the type of our keyboard macros (to which we decided to add
a counter slot while at it):
(oclosure-define kbd-macro "Keyboard macro." keys (counter :mutable t))
After which we can rewrite our kbd-macro function:
(defun kbd-macro (key-sequence)
(oclosure-lambda (kbd-macro (keys key-sequence) (counter 0))
(&optional arg)
(interactive "P")
(execute-kbd-macro keys arg)
(setq counter (1+ counter))))
As you can see, the keys and counter slots of the
OClosure can be accessed as local variables from within the body
of the OClosure. But we can now also access them from outside of the
body of the OClosure, for example to describe a keyboard macro:
(defun describe-kbd-macro (km)
(if (not (eq 'kbd-macro (oclosure-type km)))
(message "Not a keyboard macro")
(let ((keys (kbd-macro--keys km))
(counter (kbd-macro--counter km)))
(message "Keys=%S, called %d times" keys counter))))
Where kbd-macro--keys and kbd-macro--counter are
accessor functions generated by the oclosure-define macro for
oclosures whose type is kbd-macro.
This macro defines a new OClosure type along with accessor functions
for its slots. oname can be a symbol (the name of the new
type), or a list of the form
(oname . type-props), in which case
type-props is a list of additional properties of this oclosure
type. slots is a list of slot descriptions where each slot can
be either a symbol (the name of the slot) or it can be of the form
(slot-name . slot-props), where
slot-props is a property list of the corresponding slot
slot-name.
The OClosure type’s properties specified by type-props can
include the following:
(:predicate pred-name)This requests creation of a predicate function named pred-name.
This function will be used to recognize OClosures of the type
oname. If this type property is not specified,
oclosure-define will generate a default name for the
predicate.
(:parent otype)This makes type otype of OClosures be the parent of the type oname. The OClosures of type oname inherit the slots defined by their parent type.
(:copier copier-name copier-args)This causes the definition of a functional update function, knows as the copier, which takes an OClosure of type oname as its first argument and returns a copy of it with the slots named in copier-args modified to contain the value passed in the corresponding argument in the actual call to copier-name.
For each slot in slots, the oclosure-define macro creates
an accessor function named oname--slot-name; these
can be used to access the values of the slots. The slot definitions
in slots can specify the following properties of the slots:
:mutable valBy default, slots are immutable, but if you specify the
:mutable property with a non-nil value, the slot can be
mutated, for example with setf (see The setf Macro).
:type val-typeThis specifies the type of the values expected to appear in the slot.
This macro creates an anonymous OClosure of type type, which
should have been defined with oclosure-define. slots
should be a list of elements of the form
(slot-name expr). At run time, each expr
is evaluated, in order, after which the OClosure is created with its
slots initialized with the resulting values.
When called as a function (see Calling Functions), the OClosure created by this macro will accept arguments according to arglist and will execute the code in body. body can refer to the value of any of its slot directly as if it were a local variable that had been captured by static scoping.
This function returns the OClosure type (a symbol) of object if
it is an OClosure, and nil otherwise.
One other function related to OClosures is
oclosure-interactive-form, which allows some types of OClosures
to compute their interactive forms dynamically. See oclosure-interactive-form.
When you need to modify a function defined in another library, or when you need
to modify a hook like foo-function, a process filter, or basically
any variable or object field which holds a function value, you can use the
appropriate setter function, such as fset or defun for named
functions, setq for hook variables, or set-process-filter for
process filters, but those are often too blunt, completely throwing away the
previous value.
The advice feature lets you add to the existing definition of a function, by advising the function. This is a cleaner method than redefining the whole function.
Emacs’s advice system provides two sets of primitives for that: the core set,
for function values held in variables and object fields (with the corresponding
primitives being add-function and remove-function) and another
set layered on top of it for named functions (with the main primitives being
advice-add and advice-remove).
As a trivial example, here’s how to add advice that’ll modify the return value of a function every time it’s called:
(defun my-double (x) (* x 2)) (defun my-increase (x) (+ x 1)) (advice-add 'my-double :filter-return #'my-increase)
After adding this advice, if you call my-double with ‘3’,
the return value will be ‘7’. To remove this advice, say
(advice-remove 'my-double #'my-increase)
A more advanced example would be to trace the calls to the process filter of a process proc:
(defun my-tracing-function (proc string) (message "Proc %S received %S" proc string)) (add-function :before (process-filter proc) #'my-tracing-function)
This will cause the process’s output to be passed to my-tracing-function
before being passed to the original process filter. my-tracing-function
receives the same arguments as the original function. When you’re done with
it, you can revert to the untraced behavior with:
(remove-function (process-filter proc) #'my-tracing-function)
Similarly, if you want to trace the execution of the function named
display-buffer, you could use:
(defun his-tracing-function (orig-fun &rest args)
(message "display-buffer called with args %S" args)
(let ((res (apply orig-fun args)))
(message "display-buffer returned %S" res)
res))
(advice-add 'display-buffer :around #'his-tracing-function)
Here, his-tracing-function is called instead of the original function
and receives the original function (additionally to that function’s arguments)
as argument, so it can call it if and when it needs to.
When you’re tired of seeing this output, you can revert to the untraced
behavior with:
(advice-remove 'display-buffer #'his-tracing-function)
The arguments :before and :around used in the above examples
specify how the two functions are composed, since there are many different
ways to do it. The added function is also called a piece of advice.
This macro is the handy way to add the advice function to the function stored in place (see Generalized Variables).
where determines how function is composed with the existing function, e.g., whether function should be called before, or after the original function. See Ways to compose advice, for the list of available ways to compose the two functions.
When modifying a variable (whose name will usually end with -function),
you can choose whether function is used globally or only in the current
buffer: if place is just a symbol, then function is added to the
global value of place. Whereas if place is of the form
(local symbol), where symbol is an expression which returns
the variable name, then function will only be added in the
current buffer. Finally, if you want to modify a lexical variable, you will
have to use (var variable).
Every function added with add-function can be accompanied by an
association list of properties props. Currently only two of those
properties have a special meaning:
nameThis gives a name to the advice, which remove-function can use to
identify which function to remove. Typically used when function is an
anonymous function.
depthThis specifies how to order the advice, should several pieces of advice be present. By default, the depth is 0. A depth of 100 indicates that this piece of advice should be kept as deep as possible, whereas a depth of −100 indicates that it should stay as the outermost piece. When two pieces of advice specify the same depth, the most recently added one will be outermost.
For :before advice, being outermost means that this advice will
be run first, before any other advice, whereas being innermost means
that it will run right before the original function, with no other
advice run between itself and the original function. Similarly, for
:after advice innermost means that it will run right after the
original function, with no other advice run in between, whereas
outermost means that it will be run right at the end after all other
advice. An innermost :override piece of advice will only
override the original function and other pieces of advice will apply
to it, whereas an outermost :override piece of advice will
override not only the original function but all other advice applied
to it as well.
If function is not interactive, then the combined function will inherit
the interactive spec, if any, of the original function. Else, the combined
function will be interactive and will use the interactive spec of
function. One exception: if the interactive spec of function
is a function (i.e., a lambda expression or an fbound
symbol rather than an expression or a string), then the interactive
spec of the combined function will be a call to that function with
the interactive spec of the original function as sole argument. To
interpret the spec received as argument, use
advice-eval-interactive-spec.
Note: The interactive spec of function will apply to the combined
function and should hence obey the calling convention of the combined function
rather than that of function. In many cases, it makes no difference
since they are identical, but it does matter for :around,
:filter-args, and :filter-return, where function
receives different arguments than the original function stored in
place.
This macro removes function from the function stored in
place. This only works if function was added to place
using add-function.
function is compared with functions added to place using
equal, to try and make it work also with lambda expressions. It is
additionally compared also with the name property of the functions added
to place, which can be more reliable than comparing lambda expressions
using equal.
Return non-nil if advice is already in function-def.
Like for remove-function above, instead of advice being the actual
function, it can also be the name of the piece of advice.
Call the function f for every piece of advice that was added to function-def. f is called with two arguments: the advice function and its properties.
Evaluate the interactive spec just like an interactive call to a function
with such a spec would, and then return the corresponding list of arguments
that was built. E.g., (advice-eval-interactive-spec "r\nP") will
return a list of three elements, containing the boundaries of the region and
the current prefix argument.
For instance, if you want to make the C-x m
(compose-mail) command prompt for a ‘From:’ header, you
could say something like this:
(defun my-compose-mail-advice (&rest _)
"Read From: address interactively."
(interactive
(lambda (spec)
(let* ((user-mail-address
(completing-read "From: "
'("one.address@example.net"
"alternative.address@example.net")))
(from (message-make-from user-full-name
user-mail-address))
(spec (advice-eval-interactive-spec spec)))
;; Put the From header into the OTHER-HEADERS argument.
(push (cons 'From from) (nth 2 spec))
spec)))
;; This body is not used.
nil)
(advice-add 'compose-mail :interactive-only #'my-compose-mail-advice)
A common use of advice is for named functions and macros.
You could just use add-function as in:
(add-function :around (symbol-function 'fun) #'his-tracing-function)
But you should use advice-add and advice-remove for that
instead. This separate set of functions to manipulate pieces of advice applied
to named functions, offers the following extra features compared to
add-function: they know how to deal with macros and autoloaded
functions, they let describe-function preserve the original docstring as
well as document the added advice, and they let you add and remove
pieces of advice before a function is even defined.
advice-add can be useful for altering the behavior of existing calls
to an existing function without having to redefine the whole function.
However, it can be a source of bugs, since existing callers to the function may
assume the old behavior, and work incorrectly when the behavior is changed by
advice. Advice can also cause confusion in debugging, if the person doing the
debugging does not notice or remember that the function has been modified
by advice.
Note that the problems are not due to advice per se, but to the act
of modifying a named function. It is even more problematic to modify
a named function via lower-level primitives like fset,
defalias, or cl-letf. From that point of view, advice
is the better way to modify a named function because it keeps track of
the modifications, so they can be listed and undone.
Modifying a named function should be reserved for the cases where you cannot modify Emacs’s behavior in any other way. If it is possible to do the same thing via a hook, that is preferable (see Hooks). If you simply want to change what a particular key does, it may be better to write a new command, and remap the old command’s key bindings to the new one (see Remapping Commands).
If you are writing code for release, for others to use, try to avoid
including advice in it. If the function you want to advise has no
hook to do the job, please talk with the Emacs developers about adding
a suitable hook. Especially, Emacs’s own source files should not put
advice on functions in Emacs. (There are currently a few exceptions
to this convention, but we aim to correct them.) It is generally
cleaner to create a new hook in foo, and make bar use
the hook, than to have bar put advice in foo.
Special forms (see Special Forms) cannot be advised, however macros can be advised, in much the same way as functions. Of course, this will not affect code that has already been macro-expanded, so you need to make sure the advice is installed before the macro is expanded.
It is possible to advise a primitive (see What Is a Function?), but one should typically not do so, for two reasons. Firstly, some primitives are used by the advice mechanism, and advising them could cause an infinite recursion. Secondly, many primitives are called directly from C, and such calls ignore advice; hence, one ends up in a confusing situation where some calls (occurring from Lisp code) obey the advice and other calls (from C code) do not.
This macro defines a piece of advice and adds it to the function named
symbol. If name is non-nil, the advice is named
symbol@name and installed with the name name; otherwise,
the advice is anonymous. See advice-add for explanation of
other arguments.
Add the advice function to the named function symbol.
where and props have the same meaning as for add-function
(see Primitives to manipulate advices).
Remove the advice function from the named function symbol.
function can also be the name of a piece of advice. When
called interactively, prompt for both an advised function and
the advice to remove.
Return non-nil if the advice function is already in the named
function symbol. function can also be the name of
a piece of advice.
Call function for every piece of advice that was added to the named function symbol. function is called with two arguments: the advice function and its properties.
Here are the different possible values for the where argument of
add-function and advice-add, specifying how the advice
function and the original function should be composed.
:beforeCall function before the old function. Both functions receive the same arguments, and the return value of the composition is the return value of the old function. More specifically, the composition of the two functions behaves like:
(lambda (&rest r) (apply function r) (apply oldfun r))
(add-function :before funvar function) is comparable for
single-function hooks to (add-hook 'hookvar function) for
normal hooks.
:afterCall function after the old function. Both functions receive the same arguments, and the return value of the composition is the return value of the old function. More specifically, the composition of the two functions behaves like:
(lambda (&rest r) (prog1 (apply oldfun r) (apply function r)))
(add-function :after funvar function) is comparable for
single-function hooks to (add-hook 'hookvar function
'append) for normal hooks.
:overrideThis completely replaces the old function with the new one. The old function
can of course be recovered if you later call remove-function.
:aroundCall function instead of the old function, but provide the old function as an extra argument to function. This is the most flexible composition. For example, it lets you call the old function with different arguments, or many times, or within a let-binding, or you can sometimes delegate the work to the old function and sometimes override it completely. More specifically, the composition of the two functions behaves like:
(lambda (&rest r) (apply function oldfun r))
:before-whileCall function before the old function and don’t call the old
function if function returns nil. Both functions receive the
same arguments, and the return value of the composition is the return value of
the old function. More specifically, the composition of the two functions
behaves like:
(lambda (&rest r) (and (apply function r) (apply oldfun r)))
(add-function :before-while funvar function) is comparable
for single-function hooks to (add-hook 'hookvar function)
when hookvar is run via run-hook-with-args-until-failure.
:before-untilCall function before the old function and only call the old function if
function returns nil. More specifically, the composition of the
two functions behaves like:
(lambda (&rest r) (or (apply function r) (apply oldfun r)))
(add-function :before-until funvar function) is comparable
for single-function hooks to (add-hook 'hookvar function)
when hookvar is run via run-hook-with-args-until-success.
:after-whileCall function after the old function and only if the old function
returned non-nil. Both functions receive the same arguments, and the
return value of the composition is the return value of function.
More specifically, the composition of the two functions behaves like:
(lambda (&rest r) (and (apply oldfun r) (apply function r)))
(add-function :after-while funvar function) is comparable
for single-function hooks to (add-hook 'hookvar function
'append) when hookvar is run via
run-hook-with-args-until-failure.
:after-untilCall function after the old function and only if the old function
returned nil. More specifically, the composition of the two functions
behaves like:
(lambda (&rest r) (or (apply oldfun r) (apply function r)))
(add-function :after-until funvar function) is comparable
for single-function hooks to (add-hook 'hookvar function
'append) when hookvar is run via
run-hook-with-args-until-success.
:filter-argsCall function first and use the result (which should be a list) as the new arguments to pass to the old function. More specifically, the composition of the two functions behaves like:
(lambda (&rest r) (apply oldfun (funcall function r)))
:filter-returnCall the old function first and pass the result to function. More specifically, the composition of the two functions behaves like:
(lambda (&rest r) (funcall function (apply oldfun r)))
:interactive-onlyWhile the where option controls how the body of the two functions
are composed, it does not actually affect the way interactive forms are
composed. So, in a sense, this does the opposite of :override:
call only the old function as if no advice was applied. But it still
affects the interactive form like any other where value would: The
interactive form of function, if any, overrides that of
oldfun and if it is a lambda expression, it receives
function’s interactive form as argument.
See see advice-eval-interactive-spec for an example.
A lot of code uses the old defadvice mechanism, which has been made
obsolete by the new advice-add, whose implementation and semantics is
significantly simpler.
An old piece of advice such as:
(defadvice previous-line (before next-line-at-end
(&optional arg try-vscroll))
"Insert an empty line when moving up from the top line."
(if (and next-line-add-newlines (= arg 1)
(save-excursion (beginning-of-line) (bobp)))
(progn
(beginning-of-line)
(newline))))
could be translated in the new advice mechanism into a plain function:
(defun previous-line--next-line-at-end (&optional arg try-vscroll)
"Insert an empty line when moving up from the top line."
(if (and next-line-add-newlines (= arg 1)
(save-excursion (beginning-of-line) (bobp)))
(progn
(beginning-of-line)
(newline))))
Obviously, this does not actually modify previous-line. For that the
old advice needed:
(ad-activate 'previous-line)
whereas the new advice mechanism needs:
(advice-add 'previous-line :before #'previous-line--next-line-at-end)
Note that ad-activate had a global effect: it activated all pieces of
advice enabled for that specified function. If you wanted to only activate or
deactivate a particular piece, you needed to enable or disable
it with ad-enable-advice and ad-disable-advice.
The new mechanism does away with this distinction.
Around advice such as:
(defadvice foo (around foo-around)
"Ignore case in `foo'."
(let ((case-fold-search t))
ad-do-it))
(ad-activate 'foo)
could translate into:
(defun foo--foo-around (orig-fun &rest args)
"Ignore case in `foo'."
(let ((case-fold-search t))
(apply orig-fun args)))
(advice-add 'foo :around #'foo--foo-around)
Regarding the advice’s class, note that the new :before is not
quite equivalent to the old before, because in the old advice you could
modify the function’s arguments (e.g., with ad-set-arg), and that would
affect the argument values seen by the original function, whereas in the new
:before, modifying an argument via setq in the advice has no
effect on the arguments seen by the original function.
When porting before advice which relied on this behavior, you’ll need
to turn it into new :around or :filter-args advice instead.
Similarly old after advice could modify the returned value by
changing ad-return-value, whereas new :after advice cannot, so
when porting such old after advice, you’ll need to turn it into new
:around or :filter-return advice instead.
Not all functions can be reliably advised. The byte compiler may choose to replace a call to a function with a sequence of instructions that doesn’t call the function you were interested in altering.
This usually happens due to one of the three following mechanisms:
byte-compile propertiesIf a function’s symbol has a byte-compile property, that
property will be used instead of the symbol’s function definition.
See Byte-Compilation Functions.
byte-optimize propertiesIf a function’s symbol has a byte-optimize property, the byte
compiler may rewrite the function arguments, or decide to use a
different function altogether.
compiler-macro declare formsA function can have a special compiler-macro declare
form in its definition (see The declare Form) that defines an
expander to call when compiling the function. The expander
could then cause the produced byte-code not to call the original
function.
You can mark a named function as obsolete, meaning that it may be removed at some point in the future. This causes Emacs to warn that the function is obsolete whenever it byte-compiles code containing that function, and whenever it displays the documentation for that function. In all other respects, an obsolete function behaves like any other function.
The easiest way to mark a function as obsolete is to put a
(declare (obsolete …)) form in the function’s
defun definition. See The declare Form. Alternatively, you can
use the make-obsolete function, described below.
A macro (see Macros) can also be marked obsolete with
make-obsolete; this has the same effects as for a function. An
alias for a function or macro can also be marked as obsolete; this
makes the alias itself obsolete, not the function or macro which it
resolves to.
This function marks obsolete-name as obsolete. obsolete-name should be a symbol naming a function or macro, or an alias for a function or macro.
If current-name is a symbol, the warning message says to use
current-name instead of obsolete-name. current-name
does not need to be an alias for obsolete-name; it can be a
different function with similar functionality. current-name can
also be a string, which serves as the warning message. The message
should begin in lower case, and end with a period. It can also be
nil, in which case the warning message provides no additional
details.
The argument when should be a string indicating when the function was first made obsolete—for example, a date or a release number.
This convenience macro marks the function obsolete-name obsolete and also defines it as an alias for the function current-name. It is equivalent to the following:
(defalias obsolete-name current-name doc) (make-obsolete obsolete-name current-name when)
In addition, you can mark a particular calling convention for a function as obsolete:
This function specifies the argument list signature as the correct way to call function. This causes the Emacs byte compiler to issue a warning whenever it comes across an Emacs Lisp program that calls function any other way (however, it will still allow the code to be byte compiled). when should be a string indicating when the variable was first made obsolete (usually a version number string).
For instance, in old versions of Emacs the sit-for function
accepted three arguments, like this
(sit-for seconds milliseconds nodisp)
During a transition period, the function accepted those three arguments, but declared this old calling convention as deprecated like this:
(set-advertised-calling-convention 'sit-for '(seconds &optional nodisp) "22.1")
The alternative to using this function is the
advertised-calling-convention declare spec, see
The declare Form.
An inline function is a function that works just like an ordinary function, except for one thing: when you byte-compile a call to the function (see Byte Compilation), the function’s definition is expanded into the caller.
The simple way to define an inline function, is to write
defsubst instead of defun. The rest of the definition
looks just the same, but using defsubst says to make it inline
for byte compilation.
This macro defines an inline function. Its syntax is exactly the same
as defun (see Defining Functions).
Making a function inline often makes its function calls run faster. But it also has disadvantages. For one thing, it reduces flexibility; if you change the definition of the function, calls already inlined still use the old definition until you recompile them.
Another disadvantage is that making a large function inline can increase the size of compiled code both in files and in memory. Since the speed advantage of inline functions is greatest for small functions, you generally should not make large functions inline.
Also, inline functions do not behave well with respect to debugging,
tracing, and advising (see Advising Emacs Lisp Functions). Since ease of
debugging and the flexibility of redefining functions are important
features of Emacs, you should not make a function inline, even if it’s
small, unless its speed is really crucial, and you’ve timed the code
to verify that using defun actually has performance problems.
After an inline function is defined, its inline expansion can be performed later on in the same file, just like macros.
It’s possible to use defmacro to define a macro to expand
into the same code that an inline function would execute
(see Macros). But the macro would be limited to direct use in
expressions—a macro cannot be called with apply,
mapcar and so on. Also, it takes some work to convert an
ordinary function into a macro. To convert it into an inline function
is easy; just replace defun with defsubst. Since each
argument of an inline function is evaluated exactly once, you needn’t
worry about how many times the body uses the arguments, as you do for
macros.
Alternatively, you can define a function by providing the code which
will inline it as a compiler macro (see The declare Form). The
following macros make this possible.
Define a function name by providing code that does its inlining, as a compiler macro. The function will accept the argument list args and will have the specified body.
If present, doc should be the function’s documentation string
(see Documentation Strings of Functions); declare, if present, should be
a declare form (see The declare Form) specifying the function’s
metadata. In addition to the usual declarations, declare
can include (noinline NOINLINE) when a non-nil
NOINLINE prevents Emacs from inlining the defined function.
Functions defined via define-inline have several advantages
with respect to macros defined by defsubst or defmacro:
mapcar (see Mapping Functions).
cl-defsubst
(see Argument Lists in Common Lisp Extensions for GNU Emacs
Lisp).
Like defmacro, a function inlined with define-inline
inherits the scoping rules, either dynamic or lexical, from the call
site. See Scoping Rules for Variable Bindings.
The following macros should be used in the body of a function defined
by define-inline.
Quote expression for define-inline. This is similar to
the backquote (see Backquote), but quotes code and accepts only
,, not ,@.
This provides a convenient way to ensure that the arguments to an inlined function are evaluated exactly once, as well as to create local variables.
It’s similar to let (see Local Variables): It sets up local
variables as specified by bindings, and then evaluates
body with those bindings in effect.
Each element of bindings should be either a symbol or a list of
the form (var expr); the result is to evaluate
expr and bind var to the result. However, when an element
of bindings is just a symbol var, the result of evaluating
var is re-bound to var (which is quite different from the
way let works).
The tail of bindings can be either nil or a symbol which
should hold a list of arguments, in which case each argument is
evaluated, and the symbol is bound to the resulting list.
Return non-nil if the value of expression is already
known.
Return the value of expression.
Signal an error, formatting args according to format.
Here’s an example of using define-inline:
(define-inline myaccessor (obj)
(inline-letevals (obj)
(inline-quote (if (foo-p ,obj) (aref (cdr ,obj) 3) (aref ,obj 2)))))
This is equivalent to
(defsubst myaccessor (obj) (if (foo-p obj) (aref (cdr obj) 3) (aref obj 2)))
declare Form ¶declare is a special macro which can be used to add meta
properties to a function or macro: for example, marking it as
obsolete, or giving its forms a special TAB indentation
convention in Emacs Lisp mode.
This macro ignores its arguments and evaluates to nil; it has
no run-time effect. However, when a declare form occurs in the
declare argument of a defun or defsubst function
definition (see Defining Functions) or a defmacro macro
definition (see Defining Macros), it appends the properties
specified by specs to the function or macro. This work is
specially performed by defun, defsubst, and
defmacro.
Each element in specs should have the form (property
args…), which should not be quoted. These have the
following effects:
(advertised-calling-convention signature when) ¶This acts like a call to set-advertised-calling-convention
(see Declaring Functions Obsolete); signature specifies the correct
argument list for calling the function or macro, and when should
be a string indicating when the old argument list was first made obsolete.
(debug edebug-form-spec)This is valid for macros only. When stepping through the macro with Edebug, use edebug-form-spec. See Instrumenting Macro Calls.
(doc-string n)This is used when defining a function or macro which itself will be used to define entities like functions, macros, or variables. It indicates that the nth argument, if any, should be considered as a documentation string.
(indent indent-spec)Indent calls to this function or macro according to indent-spec. This is typically used for macros, though it works for functions too. See Indenting Macros.
(autoload-macro value) ¶This is used when defining a macro. If value is ‘expand’,
any calls to the macro which follow an autoload comment will first be
expanded during generation of the autoloads. This declaration is used
as an alternative to hard-coding lists of macros to expand in
loaddefs-generate--make-autoload. See Autoload.
(interactive-only value)Set the function’s interactive-only property to value.
See The interactive-only property.
(obsolete current-name when) ¶Mark the function or macro as obsolete, similar to a call to
make-obsolete (see Declaring Functions Obsolete). current-name
should be a symbol (in which case the warning message says to use that
instead), a string (specifying the warning message), or nil (in
which case the warning message gives no extra details). when
should be a string indicating when the function or macro was first
made obsolete.
(compiler-macro expander) ¶This can only be used for functions, and tells the compiler to use
expander as an optimization function. When encountering a call to the
function, of the form (function args…), the macro
expander will call expander with that form as well as with
args…, and expander can either return a new expression to use
instead of the function call, or it can return just the form unchanged,
to indicate that the function call should be left alone.
When expander is a lambda form it should be written with
a single argument (i.e., be of the form (lambda (arg)
body)) because the function’s formal arguments are
automatically added to the lambda’s list of arguments for you.
(gv-expander expander)Declare expander to be the function to handle calls to the macro (or
function) as a generalized variable, similarly to gv-define-expander.
expander can be a symbol or it can be of the form (lambda
(arg) body) in which case that function will additionally have
access to the macro (or function)’s arguments.
(gv-setter setter)Declare setter to be the function to handle calls to the macro (or
function) as a generalized variable. setter can be a symbol in which
case it will be passed to gv-define-simple-setter, or it can be of the
form (lambda (arg) body) in which case that function will
additionally have access to the macro (or function)’s arguments and it will
be passed to gv-define-setter.
(completion completion-predicate)Declare completion-predicate as a function to determine whether
to include a function’s symbol in the list of functions when asking
for completions in M-x. This predicate function will only be
called when read-extended-command-predicate is customized to
command-completion-default-include-p; by default the value of
read-extended-command-predicate is nil (see execute-extended-command). The predicate
completion-predicate is called with two arguments: the
function’s symbol and the current buffer.
(modes modes)Specify that this command is meant to be applicable only to specified modes. See Specifying Modes For Commands.
(interactive-args arg ...)Specify the arguments that should be stored for repeat-command.
Each arg is on the form argument-name form.
(pure val)If val is non-nil, this function is pure
(see What Is a Function?). This is the same as the pure
property of the function’s symbol (see Standard Symbol Properties).
(side-effect-free val)If val is non-nil, this function is free of side effects,
so the byte compiler can ignore calls whose value is ignored. This is
the same as the side-effect-free property of the function’s
symbol, see Standard Symbol Properties.
(important-return-value val)If val is non-nil, the byte compiler will warn about
calls to this function that do not use the returned value. This is the
same as the important-return-value property of the function’s
symbol, see Standard Symbol Properties.
(speed n)Specify the value of native-comp-speed in effect for native
compilation of this function (see Native-Compilation Variables).
This allows function-level control of the optimization level used for
native code emitted for the function. In particular, if n is
−1, native compilation of the function will emit bytecode
instead of native code for the function.
(safety n)Specify the value of compilation-safety in effect for this
function. This allows function-level control of the safety level used
for the code emitted for the function (see Native-Compilation Variables).
(ftype type &optional function) ¶Declare type to be the type of this function. This type is used
by describe-function for documentation, and by the native
compiler (see Compilation of Lisp to Native Code) for optimizing code generation and
inferring types. Incorrect type declarations may cause crashes in
natively compiled code (see below). Functions with type declarations
are shown by C-h C-f as having a declared type, as opposed
to an inferred type for functions without them.
type is a type specifier (see Type Specifiers) of the
form (function (arg-1-type … arg-n-type) RETURN-TYPE). Argument types can be interleaved with &optional
and &rest to reflect the function’s calling convention
(see Features of Argument Lists).
function if present should be the name of function being defined.
Here’s an example of using ftype inside declare to define
a function positive-p, which takes an argument of type
number and returns a boolean:
(defun positive-p (x)
(declare (ftype (function (number) boolean)))
(when (> x 0)
t))
Similarly, this defines a function cons-or-number that takes a
first argument of type cons or a number, a second optional
argument of type string, and returns one of the symbols
is-cons or is-number:
(defun cons-or-number (x &optional err-msg)
(declare (ftype (function ((or cons number) &optional string)
(member is-cons is-number))))
(if (consp x)
'is-cons
(if (numberp x)
'is-number
(error (or err-msg "Unexpected input")))))
For description of additional types, see Lisp Data Types).
Declaring a function with an incorrect type causes undefined behavior.
If such a function is natively compiled with compilation-safety
set to zero (see compilation-safety), this may result in incorrect
execution or even Emacs crashing when the compiled code is loaded.
Redefining or advising a type-declared function must preserve the
original signature to avoid these issues.
no-font-lock-keywordThis is valid for macros only. Macros with this declaration are highlighted by font-lock (see Font Lock Mode) as normal functions, not specially as macros.
Byte-compiling a file often produces warnings about functions that the compiler doesn’t know about (see Compiler Errors). Sometimes this indicates a real problem, but usually the functions in question are defined in other files which would be loaded if that code is run. For example, byte-compiling simple.el used to warn:
simple.el:8727:1:Warning: the function `shell-mode' is not known to be
defined.
In fact, shell-mode is used only in a function that executes
(require 'shell) before calling shell-mode, so
shell-mode will be defined properly at run-time. When you know
that such a warning does not indicate a real problem, it is good to
suppress the warning. That makes new warnings which might mean real
problems more visible. You do that with declare-function.
All you need to do is add a declare-function statement before the
first use of the function in question:
(declare-function shell-mode "shell" ())
This says that shell-mode is defined in shell.el (the
‘.el’ can be omitted). The compiler takes for granted that that file
really defines the function, and does not check.
The optional third argument specifies the argument list of
shell-mode. In this case, it takes no arguments
(nil is different from not specifying a value). In other
cases, this might be something like (file &optional overwrite).
You don’t have to specify the argument list, but if you do the
byte compiler can check that the calls match the declaration.
Tell the byte compiler to assume that function is defined in the
file file. The optional third argument arglist is either
t, meaning the argument list is unspecified, or a list of
formal parameters in the same style as defun (including the
parentheses). An omitted arglist defaults to t, not
nil; this is atypical behavior for omitted arguments, and it
means that to supply a fourth but not third argument one must specify
t for the third-argument placeholder instead of the usual
nil. The optional fourth argument fileonly
non-nil means check only that file exists, not that it
actually defines function.
To verify that these functions really are declared where
declare-function says they are, use check-declare-file
to check all declare-function calls in one source file, or use
check-declare-directory check all the files in and under a
certain directory.
These commands find the file that ought to contain a function’s
definition using locate-library; if that finds no file, they
expand the definition file name relative to the directory of the file
that contains the declare-function call.
You can also say that a function is a primitive by specifying a file name ending in ‘.c’ or ‘.m’. This is useful only when you call a primitive that is defined only on certain systems. Most primitives are always defined, so they will never give you a warning.
Sometimes a file will optionally use functions from an external package.
If you prefix the filename in the declare-function statement with
‘ext:’, then it will be checked if it is found, otherwise skipped
without error.
There are some function definitions that ‘check-declare’ does not
understand (e.g., defstruct and some other macros). In such cases,
you can pass a non-nil fileonly argument to
declare-function, meaning to only check that the file exists, not
that it actually defines the function. Note that to do this without
having to specify an argument list, you should set the arglist
argument to t (because nil means an empty argument list, as
opposed to an unspecified one).
Some major modes, such as SES, call functions that are stored in user files. (See Simple Emacs Spreadsheet, for more information on SES.) User files sometimes have poor pedigrees—you can get a spreadsheet from someone you’ve just met, or you can get one through email from someone you’ve never met. So it is risky to call a function whose source code is stored in a user file until you have determined that it is safe.
Returns nil if form is a safe Lisp expression, or
returns a list that describes why it might be unsafe. The argument
unsafep-vars is a list of symbols known to have temporary
bindings at this point; it is mainly used for internal recursive
calls. The current buffer is an implicit argument, which provides a
list of buffer-local bindings.
Being quick and simple, unsafep does a very light analysis and
rejects many Lisp expressions that are actually safe. There are no
known cases where unsafep returns nil for an unsafe
expression. However, a safe Lisp expression can return a string
with a display property, containing an associated Lisp
expression to be executed after the string is inserted into a buffer.
This associated expression can be malicious. In order to be safe, you
must delete properties from all strings calculated by user code before
inserting them into buffers.
Here is a table of several functions that do things related to function calling and function definitions. They are documented elsewhere, but we provide cross references here.
applySee Calling Functions.
autoloadSee Autoload.
call-interactivelySee Interactive Call.
called-interactively-pcommandpSee Interactive Call.
documentationevalSee Eval.
funcallSee Calling Functions.
functionSee Anonymous Functions.
ignoreSee Calling Functions.
indirect-functioninteractiveSee Using interactive.
interactive-pmapatomsmapcarSee Mapping Functions.
map-char-tableSee Char-Tables.
mapconcatSee Mapping Functions.
undefinedThis only
works in code using lexical-binding.
This is related to, but different from currying, which transforms a function that takes multiple arguments in such a way that it can be called as a chain of functions, each one with a single argument.
If the number of arguments that func can accept is unlimited,
then the new function will also accept an unlimited number of
arguments, so in that case apply-partially doesn’t reduce the
number of arguments that the new function could accept.
Note that unlike the built-in function, this version accepts any number of arguments.