GNU Emacs Lisp Reference Manual

18.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.

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

`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 raw prefix argument. If the prefix argument is nil, then 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 LFD 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 LFD 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.