@c Copyright (C) 1990-1995, 1998-1999, 2001-2012
@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
-@node Functions, Macros, Variables, Top
+@node Functions
@chapter Functions
A Lisp program is composed mainly of Lisp functions. This chapter
@end example
@noindent
-We can call this function by writing it as the @sc{car} of an
-expression, like this:
+We can call this function by passing it to @code{funcall}, like this:
@example
@group
-((lambda (a b c) (+ a b c))
- 1 2 3)
+(funcall (lambda (a b c) (+ a b c))
+ 1 2 3)
@end group
@end example
@example
@group
-((lambda (a b c) (+ a b c))
- 1 (* 2 3) (- 5 4))
+(funcall (lambda (a b c) (+ a b c))
+ 1 (* 2 3) (- 5 4))
@end group
@end example
Here are some examples of argument lists and proper calls:
-@smallexample
-((lambda (n) (1+ n)) ; @r{One required:}
- 1) ; @r{requires exactly one argument.}
+@example
+(funcall (lambda (n) (1+ n)) ; @r{One required:}
+ 1) ; @r{requires exactly one argument.}
@result{} 2
-((lambda (n &optional n1) ; @r{One required and one optional:}
- (if n1 (+ n n1) (1+ n))) ; @r{1 or 2 arguments.}
- 1 2)
+(funcall (lambda (n &optional n1) ; @r{One required and one optional:}
+ (if n1 (+ n n1) (1+ n))) ; @r{1 or 2 arguments.}
+ 1 2)
@result{} 3
-((lambda (n &rest ns) ; @r{One required and one rest:}
- (+ n (apply '+ ns))) ; @r{1 or more arguments.}
- 1 2 3 4 5)
+(funcall (lambda (n &rest ns) ; @r{One required and one rest:}
+ (+ n (apply '+ ns))) ; @r{1 or more arguments.}
+ 1 2 3 4 5)
@result{} 15
-@end smallexample
+@end example
@node Function Documentation
@subsection Documentation Strings of Functions
@end example
@code{defun} stores this lambda expression in the function cell of
-@var{name}. It returns the value @var{name}, but usually we ignore this
-value.
+@var{name}. Its return value is @emph{undefined}.
As described previously, @var{argument-list} is a list of argument
names and may include the keywords @code{&optional} and @code{&rest}.
@example
@group
(defun foo () 5)
- @result{} foo
-@end group
-@group
(foo)
@result{} 5
@end group
@group
(defun bar (a &optional b &rest c)
(list a b c))
- @result{} bar
-@end group
-@group
(bar 1 2 3 4 5)
@result{} (1 2 (3 4 5))
@end group
(forward-word 1)
(backward-char 1)
(capitalize-word 1))
- @result{} capitalize-backwards
@end group
@end example
@anchor{Definition of defalias}
This special form defines the symbol @var{name} as a function, with
definition @var{definition} (which can be any valid Lisp function).
-It returns @var{definition}.
+Its return value is @emph{undefined}.
If @var{docstring} is non-@code{nil}, it becomes the function
documentation of @var{name}. Otherwise, any documentation provided by
result is always a list. The length of the result is the same as the
length of @var{sequence}. For example:
-@smallexample
+@example
@group
(mapcar 'car '((a b) (c d) (e f)))
@result{} (a c e)
(mapcar* 'cons '(a b c) '(1 2 3 4))
@result{} ((a . 1) (b . 2) (c . 3))
@end group
-@end smallexample
+@end example
@end defun
@defun mapc function sequence
kind of sequence except a char-table; that is, a list, a vector, a
bool-vector, or a string.
-@smallexample
+@example
@group
(mapconcat 'symbol-name
'(The cat in the hat)
"")
@result{} "IBM.9111"
@end group
-@end smallexample
+@end example
@end defun
@node Anonymous Functions
@example
@group
(defun bar (n) (+ n 2))
- @result{} bar
-@end group
-@group
(symbol-function 'bar)
@result{} (lambda (n) (+ n 2))
@end group
@example
@group
(defun foo (x) x)
- @result{} foo
-@end group
-@group
(foo 1)
@result{}1
@end group
any anonymous function that you create using the @code{lambda} macro
or the @code{function} special form or the @code{#'} syntax
(@pxref{Anonymous Functions}), is automatically converted into a
-closure.
+@dfn{closure}.
+@cindex 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
In addition, you can mark a certain a particular calling convention
for a function as obsolete:
-@defun set-advertised-calling-convention function signature
+@defun set-advertised-calling-convention function signature when
This function specifies the argument list @var{signature} as the
correct way to call @var{function}. This causes the Emacs byte
compiler to issue a warning whenever it comes across an Emacs Lisp
program that calls @var{function} any other way (however, it will
-still allow the code to be byte compiled).
+still allow the code to be byte compiled). @var{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 @code{sit-for} function
accepted three arguments, like this
-@smallexample
+@example
(sit-for seconds milliseconds nodisp)
-@end smallexample
+@end example
However, calling @code{sit-for} this way is considered obsolete
(@pxref{Waiting}). The old calling convention is deprecated like
this:
-@smallexample
+@example
(set-advertised-calling-convention
- 'sit-for '(seconds &optional nodisp))
-@end smallexample
+ 'sit-for '(seconds &optional nodisp) "22.1")
+@end example
@end defun
@node Inline Functions
defined in other files which would be loaded if that code is run. For
example, byte-compiling @file{fortran.el} used to warn:
-@smallexample
+@example
In end of data:
-fortran.el:2152:1:Warning: the function `gud-find-c-expr' is not known
- to be defined.
-@end smallexample
+fortran.el:2152:1:Warning: the function `gud-find-c-expr' is not
+ known to be defined.
+@end example
In fact, @code{gud-find-c-expr} is only used in the function that
Fortran mode uses for the local value of
All you need to do is add a @code{declare-function} statement before the
first use of the function in question:
-@smallexample
+@example
(declare-function gud-find-c-expr "gud.el" nil)
-@end smallexample
+@end example
This says that @code{gud-find-c-expr} is defined in @file{gud.el} (the
@samp{.el} can be omitted). The compiler takes for granted that that file
HCoop / bpt / emacs.git / blobdiff