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 File Name Expansion). 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.

`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 (see 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 (see 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. 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.

`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 user-variable-p). This reads the variable using read-variable. See 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. See 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. 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.