From 8421dd353c3df878e25efc4159d12b2f83be1933 Mon Sep 17 00:00:00 2001 From: Chong Yidong Date: Tue, 24 Mar 2009 17:08:49 +0000 Subject: [PATCH] (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. --- doc/lispref/commands.texi | 73 ++++++++++++++++++++++----------------- 1 file changed, 41 insertions(+), 32 deletions(-) diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi index 270f3924298..e767574cecf 100644 --- a/doc/lispref/commands.texi +++ b/doc/lispref/commands.texi @@ -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}). -- 2.39.5