elisp: Interactive Codes
20.2.2 Code Characters for ‘interactive’
----------------------------------------
The code character descriptions below contain a number of key words,
defined here as follows:
Completion
Provide completion. <TAB>, <SPC>, and <RET> perform name
completion because the argument is read using ‘completing-read’
(
Completion). ‘?’ displays a list of possible completions.
Existing
Require the name of an existing object. An invalid name is not
accepted; the commands to exit the minibuffer do not exit if the
current input is not valid.
Default
A default value of some sort is used if the user enters no text in
the minibuffer. The default depends on the code character.
No I/O
This code letter computes an argument without reading any input.
Therefore, it does not use a prompt string, and any prompt string
you supply is ignored.
Even though the code letter doesn’t use a prompt string, you must
follow it with a newline if it is not the last code character in
the string.
Prompt
A prompt immediately follows the code character. The prompt ends
either with the end of the string or with a newline.
Special
This code character is meaningful only at the beginning of the
interactive string, and it does not look for a prompt or a newline.
It is a single, isolated character.
Here are the code character descriptions for use with ‘interactive’:
‘*’
Signal an error if the current buffer is read-only. Special.
‘@’
Select the window mentioned in the first mouse event in the key
sequence that invoked this command. Special.
‘^’
If the command was invoked through shift-translation, set the mark
and activate the region temporarily, or extend an already active
region, before the command is run. If the command was invoked
without shift-translation, and the region is temporarily active,
deactivate the region before the command is run. Special.
‘a’
A function name (i.e., a symbol satisfying ‘fboundp’). Existing,
Completion, Prompt.
‘b’
The name of an existing buffer. By default, uses the name of the
current buffer (Buffers). Existing, Completion, Default,
Prompt.
‘B’
A buffer name. The buffer need not exist. By default, uses the
name of a recently used buffer other than the current buffer.
Completion, Default, Prompt.
‘c’
A character. The cursor does not move into the echo area. Prompt.
‘C’
A command name (i.e., a symbol satisfying ‘commandp’). Existing,
Completion, Prompt.
‘d’
The position of point, as an integer (Point). No I/O.
‘D’
A directory name. The default is the current default directory of
the current buffer, ‘default-directory’ (File Name
Expansion). Existing, Completion, Default, Prompt.
‘e’
The first or next non-keyboard event in the key sequence that
invoked the command. More precisely, ‘e’ gets events that are
lists, so you can look at the data in the lists. Input
Events. No I/O.
You use ‘e’ for mouse events and for special system events (
Misc Events). The event list that the command receives depends
on the event. Input Events, which describes the forms of
the list for each event in the corresponding subsections.
You can use ‘e’ more than once in a single command’s interactive
specification. If the key sequence that invoked the command has N
events that are lists, the Nth ‘e’ provides the Nth such event.
Events that are not lists, such as function keys and ASCII
characters, do not count where ‘e’ is concerned.
‘f’
A file name of an existing file (File Names). The default
directory is ‘default-directory’. Existing, Completion, Default,
Prompt.
‘F’
A file name. The file need not exist. Completion, Default,
Prompt.
‘G’
A file name. The file need not exist. If the user enters just a
directory name, then the value is just that directory name, with no
file name within the directory added. Completion, Default, Prompt.
‘i’
An irrelevant argument. This code always supplies ‘nil’ as the
argument’s value. No I/O.
‘k’
A key sequence (Key Sequences). This keeps reading events
until a command (or undefined command) is found in the current key
maps. The key sequence argument is represented as a string or
vector. The cursor does not move into the echo area. Prompt.
If ‘k’ reads a key sequence that ends with a down-event, it also
reads and discards the following up-event. You can get access to
that up-event with the ‘U’ code character.
This kind of input is used by commands such as ‘describe-key’ and
‘global-set-key’.
‘K’
A key sequence, whose definition you intend to change. This works
like ‘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.
‘m’
The position of the mark, as an integer. No I/O.
‘M’
Arbitrary text, read in the minibuffer using the current buffer’s
input method, and returned as a string ((emacs)Input
Methods). Prompt.
‘n’
A number, read with the minibuffer. If the input is not a number,
the user has to try again. ‘n’ never uses the prefix argument.
Prompt.
‘N’
The numeric prefix argument; but if there is no prefix argument,
read a number as with ‘n’. The value is always a number.
Prefix Command Arguments. Prompt.
‘p’
The numeric prefix argument. (Note that this ‘p’ is lower case.)
No I/O.
‘P’
The raw prefix argument. (Note that this ‘P’ is upper case.) No
I/O.
‘r’
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.
‘s’
Arbitrary text, read in the minibuffer and returned as a string
(Text from Minibuffer). Terminate the input with either
‘C-j’ or <RET>. (‘C-q’ may be used to include either of these
characters in the input.) Prompt.
‘S’
An interned symbol whose name is read in the minibuffer. Terminate
the input with either ‘C-j’ or <RET>. Other characters that
normally terminate a symbol (e.g., whitespace, parentheses and
brackets) do not do so here. Prompt.
‘U’
A key sequence or ‘nil’. Can be used after a ‘k’ or ‘K’ argument
to get the up-event that was discarded (if any) after ‘k’ or ‘K’
read a down-event. If no up-event has been discarded, ‘U’ provides
‘nil’ as the argument. No I/O.
‘v’
A variable declared to be a user option (i.e., satisfying the
predicate ‘custom-variable-p’). This reads the variable using
‘read-variable’. Definition of read-variable. Existing,
Completion, Prompt.
‘x’
A Lisp object, specified with its read syntax, terminated with a
‘C-j’ or <RET>. The object is not evaluated. Object from
Minibuffer. Prompt.
‘X’
A Lisp form’s value. ‘X’ reads as ‘x’ does, then evaluates the
form so that its value becomes the argument for the command.
Prompt.
‘z’
A coding system name (a symbol). If the user enters null input,
the argument value is ‘nil’. Coding Systems. Completion,
Existing, Prompt.
‘Z’
A coding system name (a symbol)—but only if this command has a
prefix argument. With no prefix argument, ‘Z’ provides ‘nil’ as
the argument value. Completion, Existing, Prompt.
Info Catalog
elisp: Using Interactive
elisp: Defining Commands
elisp: Interactive Examples