diff options
Diffstat (limited to 'doc/lispref/commands.texi')
| -rw-r--r-- | doc/lispref/commands.texi | 134 |
1 files changed, 125 insertions, 9 deletions
diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi index 3a2c7d019ef..6d450998673 100644 --- a/doc/lispref/commands.texi +++ b/doc/lispref/commands.texi @@ -144,6 +144,7 @@ commands by adding the @code{interactive} form to them. * Interactive Codes:: The standard letter-codes for reading arguments in various ways. * Interactive Examples:: Examples of how to read interactive arguments. +* Command Modes:: Specifying that commands are for a specific mode. * Generic Commands:: Select among command alternatives. @end menu @@ -156,7 +157,7 @@ commands by adding the @code{interactive} form to them. makes a Lisp function an interactively-callable command, and how to examine a command's @code{interactive} form. -@defspec interactive arg-descriptor +@defspec interactive &optional arg-descriptor &rest modes 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 @@ -177,6 +178,10 @@ 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. +The @var{modes} list allows specifying which modes the command is +meant to be used in. See @ref{Command Modes} for more details about +the effect of specifying @var{modes}, and when to use it. + 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 @@ -449,10 +454,13 @@ This kind of input is used by commands such as @code{describe-key} and @code{global-set-key}. @item K -A key sequence, whose definition you intend to change. This works like -@samp{k}, except that it suppresses, for the last input event in the key -sequence, the conversions that are normally used (when necessary) to -convert an undefined key into a defined one. +A key sequence on a form that can be used as input to functions like +@code{define-key}. This works like @samp{k}, except that it +suppresses, for the last input event in the key sequence, the +conversions that are normally used (when necessary) to convert an +undefined key into a defined one (@pxref{Key Sequence Input}), so this +form is usually used when prompting for a new key sequence that is to +be bound to a command. @item m @cindex marker argument @@ -488,7 +496,10 @@ I/O. Point and the mark, as two numeric arguments, smallest first. This is the only code letter that specifies two successive arguments rather than one. This will signal an error if the mark is not set in the buffer -which is current when the command is invoked. No I/O. +which is current when the command is invoked. If Transient Mark mode +is turned on (@pxref{The Mark}) --- as it is by default --- and user +option @code{mark-even-if-inactive} is @code{nil}, Emacs will signal +an error even if the mark @emph{is} set, but is inactive. No I/O. @item s Arbitrary text, read in the minibuffer and returned as a string @@ -588,6 +599,80 @@ Put them into three windows, selecting the last one." @end group @end example +@node Command Modes +@subsection Specifying Modes For Commands +@cindex commands, mode-specific +@cindex commands, specify as mode-specific +@cindex mode-specific commands + +Many commands in Emacs are general, and not tied to any specific mode. +For instance, @kbd{M-x kill-region} can be used in pretty much any +mode that has editable text, and commands that display information +(like @kbd{M-x list-buffers}) can be used in pretty much any context. + +Many other commands, however, are specifically tied to a mode, and +make no sense outside of that context. For instance, @code{M-x +dired-diff} will just signal an error if used outside of a Dired +buffer. + +Emacs therefore has a mechanism for specifying what mode (or modes) a +command ``belongs'' to: + +@lisp +(defun dired-diff (...) + ... + (interactive "p" dired-mode) + ...) +@end lisp + +This will mark the command as applicable to @code{dired-mode} only (or +any modes that are derived from @code{dired-mode}). Any number of +modes can be added to the @code{interactive} form. + +@vindex read-extended-command-predicate +Specifying modes may affect completion in @kbd{M-x}, depending on the +value of @code{read-extended-command-predicate}. + +For instance, when using the +@code{command-completion-default-include-p} predicate, @kbd{M-x} won't +list commands that have been marked as being applicable to a specific +mode (unless you are in a buffer that uses that mode, of course). +This goes for both major and minor modes. + +Marking commands this way will also make @kbd{C-h m} list these +commands (if they aren't bound to any keys). + +If using this extended @code{interactive} form isn't convenient +(because the code is supposed to work in older versions of Emacs that +don't support the extended @code{interactive} form), the following +equivalent declaration (@pxref{Declare Form}) can be used instead: + +@lisp +(declare (modes dired-mode)) +@end lisp + +Which commands to tag with modes is to some degree a matter of taste, +but commands that clearly do not work outside of the mode should be +tagged. This includes commands that will signal an error if called +from somewhere else, but also commands that are destructive when +called from an unexpected mode. (This usually includes most of the +commands that are written for special (i.e., non-editing) modes.) + +Some commands may be harmless, and ``work'' when called from other +modes, but should still be tagged with a mode if they don't actually +make much sense to use elsewhere. For instance, many special modes +have commands to exit the buffer bound to @kbd{q}, and may not do +anything but issue a message like "Goodbye from this mode" and then +call @code{kill-buffer}. This command will ``work'' from any mode, +but it is highly unlikely that anybody would actually want to use the +command outside the context of this special mode. + +Many modes have a set of different commands that start the mode in +different ways (e.g., @code{eww-open-in-new-buffer} and +@code{eww-open-file}). Commands like that should never be tagged as +mode-specific, as they can be issued by the user from pretty much any +context. + @node Generic Commands @subsection Select among Command Alternatives @cindex generic commands @@ -756,6 +841,29 @@ part of the prompt. @result{} t @end group @end example + +@vindex read-extended-command-predicate +@findex command-completion-default-include-p +This command heeds the @code{read-extended-command-predicate} +variable, which can filter out commands that are not applicable to the +current major mode (or enabled minor modes). By default, the value of +this variable is @code{nil}, and no commands are filtered out. +However, customizing it to invoke the function +@code{command-completion-default-include-p} will perform +mode-dependent filtering. @code{read-extended-command-predicate} can +be any predicate function; it will be called with two parameters: the +command's symbol and the current buffer. If should return +non-@code{nil} if the command is to be included when completing in +that buffer. +@end deffn + +@deffn Command execute-extended-command-for-buffer prefix-argument +This is like @code{execute-extended-command}, but limits the commands +offered for completion to those commands that are of particular +relevance to the current major mode (and enabled minor modes). This +includes commands that are tagged with the modes (@pxref{Using +Interactive}), and also commands that are bound to locally active +keymaps. @end deffn @node Distinguish Interactive @@ -3276,6 +3384,12 @@ nil)}. This is the same thing that quitting does. (See @code{signal} in @ref{Errors}.) @end deffn + To quit without aborting a keyboard macro definition or execution, +you can signal the @code{minibuffer-quit} condition. This has almost +the same effect as the @code{quit} condition except that the error +handling in the command loop handles it without exiting keyboard macro +definition or execution. + You can specify a character other than @kbd{C-g} to use for quitting. See the function @code{set-input-mode} in @ref{Input Modes}. @@ -3460,12 +3574,14 @@ commands. @code{recursive-edit}. This function contains the command loop; it also contains a call to @code{catch} with tag @code{exit}, which makes it possible to exit the recursive editing level by throwing to @code{exit} -(@pxref{Catch and Throw}). If you throw a value other than @code{t}, -then @code{recursive-edit} returns normally to the function that called -it. The command @kbd{C-M-c} (@code{exit-recursive-edit}) does this. +(@pxref{Catch and Throw}). If you throw a @code{nil} value, then +@code{recursive-edit} returns normally to the function that called it. +The command @kbd{C-M-c} (@code{exit-recursive-edit}) does this. Throwing a @code{t} value causes @code{recursive-edit} to quit, so that control returns to the command loop one level up. This is called @dfn{aborting}, and is done by @kbd{C-]} (@code{abort-recursive-edit}). +You can also throw a function value. In that case, +@code{recursive-edit} will call it without arguments before returning. Most applications should not use recursive editing, except as part of using the minibuffer. Usually it is more convenient for the user if you |