list, which are given local bindings with the values provided.
@xref{Local Variables}.
- The documentation string is an actual string that serves to describe
-the function for the Emacs help facilities. @xref{Function Documentation}.
+ The documentation string is a Lisp string object placed within the
+function definition to describe the function for the Emacs help
+facilities. @xref{Function Documentation}.
The interactive declaration is a list of the form @code{(interactive
@var{code-string})}. This declares how to provide arguments if the
@noindent
This evaluates the arguments @code{1}, @code{(* 2 3)}, and @code{(- 5
-4)} from left to right. Then it applies the lambda expression applied
-to the argument values 1, 6 and 1 to produce the value 8.
+4)} from left to right. Then it applies the lambda expression to the
+argument values 1, 6 and 1 to produce the value 8.
It is not often useful to write a lambda expression as the @sc{car} of
a form in this way. You can get the same result, of making local
accepts three arguments---a string, the start index and the end
index---but the third argument defaults to the @var{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 @code{and}
+accept an indefinite number of arguments, as the functions @code{list}
and @code{+} do.
@cindex optional arguments
be any number of extra actual arguments.
If actual arguments for the optional and rest variables are omitted,
-then they always default to @code{nil}. However, the body of the function
-is free to consider @code{nil} an abbreviation for some other meaningful
-value. This is what @code{substring} does; @code{nil} as the third argument
-means to use the length of the string supplied. There is no way for the
+then they always default to @code{nil}. There is no way for the
function to distinguish between an explicit argument of @code{nil} and
-an omitted argument.
+an omitted argument. However, the body of the function is free to
+consider @code{nil} an abbreviation for some other meaningful value.
+This is what @code{substring} does; @code{nil} as the third argument to
+@code{substring} means to use the length of the string supplied.
@cindex CL note---default optional arg
@quotation
The start of the documentation string is usually indented, 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. @emph{This 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.
+lines of the string so that the text lines up in the program source.
+@emph{This 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.
You may wonder how the documentation string could be optional, since
there are required components of the function that follow it (the body).
@defun defalias name definition
This special form defines the symbol @var{name} as a function, with
-definition @var{definition}. It's best to use this rather than
-@code{fset} when defining a function in a file, because @code{defalias}
-records which file defined the function (@pxref{Unloading}).
+definition @var{definition} (which can be any valid Lisp function).
+It's best to use this rather than @code{fset} when defining a function
+in a file, because @code{defalias} records which file defined the
+function (@pxref{Unloading}), while @code{fset} does not.
@end defun
@node Calling Functions
anything until you @dfn{call} them, i.e., tell them to run. Calling a
function is also known as @dfn{invocation}.
- The most common way of invoking a function is by evaluating a list. For
-example, evaluating the list @code{(concat "a" "b")} calls the function
-@code{concat}. @xref{Evaluation}, for a description of evaluation.
+ The most common way of invoking a function is by evaluating a list.
+For example, evaluating the list @code{(concat "a" "b")} calls the
+function @code{concat} with arguments @code{"a"} and @code{"b"}.
+@xref{Evaluation}, for a description of evaluation.
When you write a list as an expression in your program, the function
name is part of the program. This means that you choose which function
@code{apply} calls @var{function} with @var{arguments}, just like
@code{funcall} but with one difference: the last of @var{arguments} is a
list of arguments to give to @var{function}, rather than a single
-argument. We also say that this list is @dfn{appended} to the other
-arguments.
+argument. We also say that @code{apply} @dfn{spreads} this list so that
+each individual element becomes an argument.
@code{apply} returns the result of calling @var{function}. As with
@code{funcall}, @var{function} must either be a Lisp function or a
@ref{Creating Symbols}.
@defun mapcar function sequence
-@code{mapcar} applies @var{function} to each element of @var{sequence} in
-turn. The results are made into a @code{nil}-terminated list.
+@code{mapcar} applies @var{function} to each element of @var{sequence}
+in turn, and returns a list of the results.
-The argument @var{sequence} may be a list, a vector or a string. The
+The argument @var{sequence} may be a list, a vector, or a string. The
result is always a list. The length of the result is the same as the
length of @var{sequence}.
function cell of the symbol. The functions described here access, test,
and set the function cell of symbols.
+ See also the function @code{indirect-function} in @ref{Function
+Indirection}.
+
@defun symbol-function symbol
@kindex void-function
This returns the object in the function cell of @var{symbol}. If the
@code{void}. The symbols @code{nil} and @code{void} are Lisp objects,
and can be stored into a function cell just as any other object can be
(and they can be valid functions if you define them in turn with
-@code{defun}); but @code{nil} or @code{void} is @emph{an object}. A
-void function cell contains no object whatsoever.
+@code{defun}). A void function cell contains no object whatsoever.
You can test the voidness of a symbol's function definition with
@code{fboundp}. After you have given a symbol a function definition, you
@result{} x
@end group
@group
+(foo 1)
+ @result{}1
+@end group
+@group
(fmakunbound 'foo)
@result{} x
@end group
@item
Giving a symbol a function definition that is not a list and therefore
-cannot be made with @code{defun}. @xref{Classifying Lists}, for an
-example of this usage.
+cannot be made with @code{defun}. For example, you can use @code{fset}
+to give a symbol @code{s1} a function definition which is another symbol
+@code{s2}; then @code{s1} serves as an alias for whatever definition
+@code{s2} presently has.
@item
In constructs for defining or altering functions. If @code{defun}
@result{} "\^u2\^k"
@end group
@end example
+
+See also the related function @code{defalias}, in @ref{Defining
+Functions}.
@end defun
When writing a function that extends a previously defined function,
proper results. The only way to avoid this problem is to make sure the
file is loaded before moving aside the old definition of @code{foo}.
-See also the function @code{indirect-function} in @ref{Function
-Indirection}.
-
@node Inline Functions
@section Inline Functions
@cindex inline functions
body uses the arguments, as you do for macros. (@xref{Argument
Evaluation}.)
-Inline functions can be used and open coded later on in the same file,
+Inline functions can be used and open-coded later on in the same file,
following the definition, just like macros.
Emacs versions prior to 19 did not have inline functions.