comparison lispref/commands.texi @ 69014:d356f128459f

(Using Interactive): Put string case before list case.

69013:727fe5204470

@item
It may be omitted or @code{nil}; then the command is called with no
arguments.  This leads quickly to an error if the command requires one
or more arguments.


@item
It may be a Lisp expression that is not a string; then it should be a
form that is evaluated to get a list of arguments to pass to the
command.  Usually this form will call various functions to read input

@smallexample
(interactive
 (let ((string (read-string "Foo: " nil 'my-history)))
   (list (region-beginning) (region-end) string)))
@end smallexample

@item
@cindex argument prompt
It may be a string; then its contents should consist of a code character
followed by a prompt (which some code characters use and some ignore).
The prompt ends either with the end of the string or with a newline.
Here is a simple example:

@smallexample
(interactive "bFrobnicate buffer: ")
@end smallexample

@noindent
The code letter @samp{b} says to read the name of an existing buffer,
with completion.  The buffer name is the sole argument passed to the
command.  The rest of the string is a prompt.

If there is a newline character in the string, it terminates the prompt.
If the string does not end there, then the rest of the string should
contain another code character and prompt, specifying another argument.
You can specify any number of arguments in this way.

@c Emacs 19 feature
The prompt string can use @samp{%} to include previous argument values
(starting with the first argument) in the prompt.  This is done using
@code{format} (@pxref{Formatting Strings}).  For example, here is how
you could read the name of an existing buffer followed by a new name to
give to that buffer:

@smallexample
@group
(interactive "bBuffer to rename: \nsRename buffer %s to: ")
@end group
@end smallexample

@cindex @samp{*} in @code{interactive}
@cindex read-only buffers in interactive
If the first character in the string is @samp{*}, then an error is
signaled if the buffer is read-only.

@cindex @samp{@@} in @code{interactive}
@c Emacs 19 feature
If the first character in the string is @samp{@@}, and if the key
sequence used to invoke the command includes any mouse events, then
the window associated with the first of those events is selected
before the command is run.

You can use @samp{*} and @samp{@@} together; the order does not matter.
Actual reading of arguments is controlled by the rest of the prompt
string (starting with the first character that is not @samp{*} or
@samp{@@}).
@end itemize

@cindex examining the @code{interactive} form
@defun interactive-form function
This function returns the @code{interactive} form of @var{function}.

69014:d356f128459f

@item
It may be omitted or @code{nil}; then the command is called with no
arguments.  This leads quickly to an error if the command requires one
or more arguments.

@item
@cindex argument prompt
It may be a string; then its contents should consist of a code character
followed by a prompt (which some code characters use and some ignore).
The prompt ends either with the end of the string or with a newline.
Here is a simple example:

@smallexample
(interactive "bFrobnicate buffer: ")
@end smallexample

@noindent
The code letter @samp{b} says to read the name of an existing buffer,
with completion.  The buffer name is the sole argument passed to the
command.  The rest of the string is a prompt.

If there is a newline character in the string, it terminates the prompt.
If the string does not end there, then the rest of the string should
contain another code character and prompt, specifying another argument.
You can specify any number of arguments in this way.

@c Emacs 19 feature
The prompt string can use @samp{%} to include previous argument values
(starting with the first argument) in the prompt.  This is done using
@code{format} (@pxref{Formatting Strings}).  For example, here is how
you could read the name of an existing buffer followed by a new name to
give to that buffer:

@smallexample
@group
(interactive "bBuffer to rename: \nsRename buffer %s to: ")
@end group
@end smallexample

@cindex @samp{*} in @code{interactive}
@cindex read-only buffers in interactive
If the first character in the string is @samp{*}, then an error is
signaled if the buffer is read-only.

@cindex @samp{@@} in @code{interactive}
@c Emacs 19 feature
If the first character in the string is @samp{@@}, and if the key
sequence used to invoke the command includes any mouse events, then
the window associated with the first of those events is selected
before the command is run.

You can use @samp{*} and @samp{@@} together; the order does not matter.
Actual reading of arguments is controlled by the rest of the prompt
string (starting with the first character that is not @samp{*} or
@samp{@@}).

@item
It may be a Lisp expression that is not a string; then it should be a
form that is evaluated to get a list of arguments to pass to the
command.  Usually this form will call various functions to read input

@smallexample
(interactive
 (let ((string (read-string "Foo: " nil 'my-history)))
   (list (region-beginning) (region-end) string)))
@end smallexample
@end itemize

@cindex examining the @code{interactive} form
@defun interactive-form function
This function returns the @code{interactive} form of @var{function}.