Commit 67bce69d authored by Richard M. Stallman's avatar Richard M. Stallman
Browse files

(What Is a Function): Wording cleanup.

(Function Documentation): Minor cleanup.
Explain purpose of calling convention at end of doc string.
(Function Names): Wording cleanup.
(Calling Functions): Wording cleanup.
Explain better how funcall calls the function.
(Function Cells): Delete example of saving and redefining function.
parent 85831f9a
......@@ -53,7 +53,7 @@ macros are not functions.
@cindex built-in function
A @dfn{primitive} is a function callable from Lisp that is written in C,
such as @code{car} or @code{append}. These functions are also called
@dfn{built-in} functions or @dfn{subrs}. (Special forms are also
@dfn{built-in functions}, or @dfn{subrs}. (Special forms are also
considered primitives.)
Usually the reason we implement a function as a primitive is either
......@@ -412,13 +412,14 @@ are easier to access.
because @code{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.
@emph{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.
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. @emph{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.
You may wonder how the documentation string could be optional, since
there are required components of the function that follow it (the body).
......@@ -438,9 +439,14 @@ text like this:
@noindent
following a blank line, at the beginning of the line, with no newline
following it inside the documentation string. This feature is
particularly useful for macro definitions. The @samp{\} is used to
avoid confusing the Emacs motion commands.
following it inside the documentation string. (The @samp{\} 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.
@node Function Names
@section Naming a Function
......@@ -481,8 +487,8 @@ practice).
We often identify functions with the symbols used to name them. For
example, we often speak of ``the function @code{car}'', not
distinguishing between the symbol @code{car} and the primitive
subr-object that is its function definition. For most purposes, there
is no need to distinguish.
subr-object that is its function definition. For most purposes, the
distinction is not important.
Even so, keep in mind that a function need not have a unique name. While
a given function object @emph{usually} appears in the function cell of only
......@@ -626,13 +632,12 @@ 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 it calls is written in your program. This means that you choose
which function to call, and how many arguments to give it, when you
write 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 @code{funcall}. When you also need to determine at run time
how many arguments to pass, use @code{apply}.
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 @code{funcall}. When you also need to determine at run
time how many arguments to pass, use @code{apply}.
@defun funcall function &rest arguments
@code{funcall} calls @var{function} with @var{arguments}, and returns
......@@ -641,11 +646,12 @@ whatever @var{function} returns.
Since @code{funcall} is a function, all of its arguments, including
@var{function}, are evaluated before @code{funcall} is called. This
means that you can use any expression to obtain the function to be
called. It also means that @code{funcall} does not see the expressions
you write for the @var{arguments}, only their values. These values are
@emph{not} evaluated a second time in the act of calling @var{function};
@code{funcall} enters the normal procedure for calling a function at the
place where the arguments have already been evaluated.
called. It also means that @code{funcall} does not see the
expressions you write for the @var{arguments}, only their values.
These values are @emph{not} evaluated a second time in the act of
calling @var{function}; the operation of @code{funcall} is like the
normal procedure for calling a function, once its arguments have
already been evaluated.
The argument @var{function} must be either a Lisp function or a
primitive function. Special forms and macros are not allowed, because
......@@ -1137,30 +1143,12 @@ Here are examples of these uses:
@end example
@end defun
When writing a function that extends a previously defined function,
the following idiom is sometimes used:
@example
(fset 'old-foo (symbol-function 'foo))
(defun foo ()
"Just like old-foo, except more so."
@group
(old-foo)
(more-so))
@end group
@end example
@noindent
This does not work properly if @code{foo} has been defined to autoload.
In such a case, when @code{foo} calls @code{old-foo}, Lisp attempts
to define @code{old-foo} by loading a file. Since this presumably
defines @code{foo} rather than @code{old-foo}, it does not produce the
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}.
But it is unmodular and unclean, in any case, for a Lisp file to
redefine a function defined elsewhere. It is cleaner to use the advice
facility (@pxref{Advising Functions}).
@code{fset} is sometimes used to save the old definition of a
function before redefining it. That permits the new definition to
invoke the old definition. But it is unmodular and unclean for a Lisp
file to redefine a function defined elsewhere. If you want to modify
a function defined by another package, it is cleaner to use
@code{defadvice} (@pxref{Advising Functions}).
@node Inline Functions
@section Inline Functions
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment