Next: , Previous: Using Interactive, Up: Defining Commands

21.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 (see 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.
‘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 (see 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 (see Point). No I/O.
‘D’
A directory name. The default is the current default directory of the current buffer, default-directory (see System Environment). Existing, Completion, Default, Prompt.
‘e’
The first or next mouse 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. See Input Events. No I/O.

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 (see File Names). The default directory is default-directory. Existing, Completion, Default, Prompt.
‘F’
A file name. The file need not exist. Completion, Default, Prompt.
‘i’
An irrelevant argument. This code always supplies nil as the argument's value. No I/O.
‘k’
A key sequence (see Keymap Terminology). 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.

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 (see Input Methods). Prompt.
‘n’
A number read with the minibuffer. If the input is not a number, the user is asked to try again. The prefix argument, if any, is not used. Prompt.
‘N’
The numeric prefix argument; but if there is no prefix argument, read a number as with n. Requires a number. See 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. No I/O.
‘s’
Arbitrary text, read in the minibuffer and returned as a string (see 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. Any whitespace character terminates the input. (Use C-q to include whitespace in the string.) Other characters that normally terminate a symbol (e.g., parentheses and brackets) do not do so here. Prompt.
‘v’
A variable declared to be a user option (i.e., satisfying the predicate user-variable-p). See High-Level Completion. Existing, Completion, Prompt.
‘x’
A Lisp object, specified with its read syntax, terminated with a C-j or <RET>. The object is not evaluated. See Object from Minibuffer. Prompt.
‘X’
A Lisp form is read as with x, but then evaluated 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. See 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.