Commit 8421dd35 authored by Chong Yidong's avatar Chong Yidong

(Defining Commands): Clarify introduction.

(Using Interactive): Not that interactive can be put in a symbol
property.
(Interactive Call): Note that a symbol with a non-nil
interactive-form property satisfies commandp.
parent 6e4ff1b6
......@@ -102,12 +102,15 @@ command does.
@cindex functions, making them interactive
@cindex interactive function
A Lisp function becomes a command when its body contains, at top
level, a form that calls the special form @code{interactive}, or if
the function's symbol has an @code{interactive-form} property. This
form does nothing when actually executed, but its presence serves as a
flag to indicate that interactive calling is permitted. Its argument
controls the reading of arguments for an interactive call.
The special form @code{interactive} turns a Lisp function into a
command. The @code{interactive} form must be located at top-level in
the function body (usually as the first form in the body), or in the
@code{interactive-form} property of the function symbol. When the
@code{interactive} form is located in the function body, it does
nothing when actually executed. Its presence serves as a flag, which
tells the Emacs command loop that the function can be called
interactively. The argument of the @code{interactive} form controls
the reading of arguments for an interactive call.
@menu
* Using Interactive:: General rules for @code{interactive}.
......@@ -125,28 +128,33 @@ makes a Lisp function an interactively-callable command, and how to
examine a command's @code{interactive} form.
@defspec interactive arg-descriptor
This special form declares that the function in which it appears is a
command, and that it may therefore be called interactively (via
@kbd{M-x} or by entering a key sequence bound to it). The argument
@var{arg-descriptor} declares how to compute the arguments to the
command when the command is called interactively.
This special form declares that a function is a command, and that it
may therefore be called interactively (via @kbd{M-x} or by entering a
key sequence bound to it). The argument @var{arg-descriptor} declares
how to compute the arguments to the command when the command is called
interactively.
A command may be called from Lisp programs like any other function, but
then the caller supplies the arguments and @var{arg-descriptor} has no
effect.
The @code{interactive} form has its effect because the command loop
(actually, its subroutine @code{call-interactively}) scans through the
function definition looking for it, before calling the function. Once
the function is called, all its body forms including the
@code{interactive} form are executed, but at this time
@code{interactive} simply returns @code{nil} without even evaluating its
argument.
@cindex @code{interactive-form}, function property
An interactive form can be added to a function post-facto via the
@code{interactive-form} property of the function's symbol.
@xref{Symbol Plists}.
The @code{interactive} form must be located at top-level in the
function body, or in the function symbol's @code{interactive-form}
property (@pxref{Symbol Plists}). It has its effect because the
command loop looks for it before calling the function
(@pxref{Interactive Call}). Once the function is called, all its body
forms are executed; at this time, if the @code{interactive} form
occurs within the body, the form simply returns @code{nil} without
even evaluating its argument.
By convention, you should put the @code{interactive} form in the
function body, as the first top-level form. If there is an
@code{interactive} form in both the @code{interactive-form} symbol
property and the function body, the former takes precedence. The
@code{interactive-form} symbol property can be used to add an
interactive form to an existing function, or change how its arguments
are processed interactively, without redefining the function.
@end defspec
There are three possibilities for the argument @var{arg-descriptor}:
......@@ -553,9 +561,9 @@ Put them into three windows, selecting the last one."
@section Interactive Call
@cindex interactive call
After the command loop has translated a key sequence into a command it
invokes that command using the function @code{command-execute}. If the
command is a function, @code{command-execute} calls
After the command loop has translated a key sequence into a command,
it invokes that command using the function @code{command-execute}. If
the command is a function, @code{command-execute} calls
@code{call-interactively}, which reads the arguments and calls the
command. You can also call these functions yourself.
......@@ -563,14 +571,15 @@ command. You can also call these functions yourself.
Returns @code{t} if @var{object} is suitable for calling interactively;
that is, if @var{object} is a command. Otherwise, returns @code{nil}.
The interactively callable objects include strings and vectors (treated
as keyboard macros), lambda expressions that contain a top-level call to
@code{interactive}, byte-code function objects made from such lambda
expressions, autoload objects that are declared as interactive
(non-@code{nil} fourth argument to @code{autoload}), and some of the
primitive functions.
Interactively-callable objects include strings and vectors (which are
treated as keyboard macros), lambda expressions that contain a
top-level @code{interactive} form (@pxref{Using Interactive}),
byte-code function objects made from such lambda expressions, autoload
objects that are declared as interactive (non-@code{nil} fourth
argument to @code{autoload}), and some primitive functions.
A symbol satisfies @code{commandp} if its function definition
A symbol satisfies @code{commandp} if it has a non-@code{nil}
@code{interactive-form} property, or if its function definition
satisfies @code{commandp}. Keys and keymaps are not commands.
Rather, they are used to look up commands (@pxref{Keymaps}).
......
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