1
2
3
4
5
6
7
8
9
10
11
12
13
14
|
<h4 class="subsection">Specifying Modes For Commands</h4> <p>Many commands in Emacs are general, and not tied to any specific mode. For instance, <kbd>M-x kill-region</kbd> can be used in pretty much any mode that has editable text, and commands that display information (like <kbd>M-x list-buffers</kbd>) can be used in pretty much any context. </p> <p>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</code> will just signal an error if used outside of a Dired buffer. </p> <p>Emacs therefore has a mechanism for specifying what mode (or modes) a command “belongs” to: </p> <div class="lisp"> <pre class="lisp">(defun dired-diff (...)
...
(interactive "p" dired-mode)
...)
</pre>
</div> <p>This will mark the command as applicable to <code>dired-mode</code> only (or any modes that are derived from <code>dired-mode</code>). Any number of modes can be added to the <code>interactive</code> form. </p> <p>Specifying modes affects command completion in <kbd>M-S-x</kbd> (<code>execute-extended-command-for-buffer</code>, see <a href="interactive-call">Interactive Call</a>). It may also affect completion in <kbd>M-x</kbd>, depending on the value of <code>read-extended-command-predicate</code>. </p> <p>For instance, when using the <code>command-completion-default-include-p</code> predicate as the value of <code>read-extended-command-predicate</code>, <kbd>M-x</kbd> 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. (By contrast, <kbd>M-S-x</kbd> always omits inapplicable commands from the completion candidates.) </p> <p>By default, <code>read-extended-command-predicate</code> is <code>nil</code>, and completion in <kbd>M-x</kbd> lists all the commands that match what the user has typed, whether those commands are or aren’t marked as applicable to the current buffer’s mode. </p> <p>Marking commands to be applicable to a mode will also make <kbd>C-h m</kbd> list these commands (if they aren’t bound to any keys). </p> <p>If using this extended <code>interactive</code> form isn’t convenient (because the code is supposed to work in older versions of Emacs that don’t support the extended <code>interactive</code> form), the following equivalent declaration (see <a href="declare-form">Declare Form</a>) can be used instead: </p> <div class="lisp"> <pre class="lisp">(declare (modes dired-mode))
</pre>
</div> <p>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.) </p> <p>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</kbd>, and may not do anything but issue a message like "Goodbye from this mode" and then call <code>kill-buffer</code>. 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. </p> <p>Many modes have a set of different commands that start the mode in different ways (e.g., <code>eww-open-in-new-buffer</code> and <code>eww-open-file</code>). Commands like that should never be tagged as mode-specific, as they can be issued by the user from pretty much any context. </p> <p>Note that specifying command modes is not supported in native-compiled functions in Emacs 28.1 (but this is fixed in later Emacs versions). This means that <code>read-extended-command-predicate</code> isn’t supported in native-compile builds, either. </p><div class="_attribution">
<p class="_attribution-p">
Copyright © 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br>
<a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Command-Modes.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Command-Modes.html</a>
</p>
</div>
|
