elisp: Calling Functions
12.5 Calling Functions
======================
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"’. 
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’.
-- Function: funcall function &rest arguments
‘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’ (
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’.
-- Function: apply function &rest arguments
‘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’ 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)
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 function(1). The result is a new
function that accepts the rest of arguments and calls the original
function with all the arguments combined.
Here’s how to do partial application in Emacs Lisp:
-- Function: apply-partially func &rest args
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’ arguments.
Here’s how we could define the built-in function ‘1+’, if it didn’t
exist, using ‘apply-partially’ and ‘+’, another built-in function:
(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 two different kinds of no-op
function:
-- Function: identity arg
This function returns ARG and has no side effects.
-- Function: ignore &rest args
This function ignores any arguments and returns ‘nil’.
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. Interactive Call.
---------- Footnotes ----------
(1) 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.
Info Catalog
elisp: Defining Functions
elisp: Functions
elisp: Mapping Functions