-\1f
-File: lispref.info, Node: Using Interactive, Next: Interactive Codes, Up: Defining Commands
-
-Using `interactive'
--------------------
-
- This section describes how to write the `interactive' form that
-makes a Lisp function an interactively-callable command.
-
- - Special Form: interactive arg-descriptor
- This special form declares that the function in which it appears
- is a command, and that it may therefore be called interactively
- (via `M-x' or by entering a key sequence bound to it). The
- argument ARG-DESCRIPTOR declares how to compute the arguments to
- the command when the command is called interactively.
-
- A command may be called from Lisp programs like any other
- function, but then the caller supplies the arguments and
- ARG-DESCRIPTOR has no effect.
-
- The `interactive' form has its effect because the command loop
- (actually, its subroutine `call-interactively') scans through the
- function definition looking for it, before calling the function.
- Once the function is called, all its body forms including the
- `interactive' form are executed, but at this time `interactive'
- simply returns `nil' without even evaluating its argument.
-
- There are three possibilities for the argument ARG-DESCRIPTOR:
-
- * It may be omitted or `nil'; then the command is called with no
- arguments. This leads quickly to an error if the command requires
- one or more arguments.
-
- * 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.
-
- If this expression reads keyboard input (this includes using the
- minibuffer), keep in mind that the integer value of point or the
- mark before reading input may be incorrect after reading input.
- This is because the current buffer may be receiving subprocess
- output; if subprocess output arrives while the command is waiting
- for input, it could relocate point and the mark.
-
- Here's an example of what _not_ to do:
-
- (interactive
- (list (region-beginning) (region-end)
- (read-string "Foo: " nil 'my-history)))
-
- Here's how to avoid the problem, by examining point and the mark
- only after reading the keyboard input:
-
- (interactive
- (let ((string (read-string "Foo: " nil 'my-history)))
- (list (region-beginning) (region-end) string)))
-
- * 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:
-
- (interactive "bFrobnicate buffer: ")
-
- The code letter `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.
-
- The prompt string can use `%' to include previous argument values
- (starting with the first argument) in the prompt. This is done
- using `format' (*note 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:
-
- (interactive "bBuffer to rename: \nsRename buffer %s to: ")
-
- If the first character in the string is `*', then an error is
- signaled if the buffer is read-only.
-
- If the first character in the string is `@', 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.
-
- If the first character in the string is `_', then this command will
- not cause the region to be deactivated when it completes; that is,
- `zmacs-region-stays' will be set to `t' when the command exits
- successfully.
-
- You can use `*', `@', and `_' 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 `*',
- `@', or `_').
-
- - Function: function-interactive function
- This function retrieves the interactive specification of FUNCTION,
- which may be any funcallable object. The specification will be
- returned as the list of the symbol `interactive' and the specs. If
- FUNCTION is not interactive, `nil' will be returned.
-
-\1f
-File: lispref.info, Node: Interactive Codes, Next: Interactive Examples, Prev: Using Interactive, Up: Defining Commands
-
-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'
- (*note 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.
-
-`_'
- Do not cause the region to be deactivated when this command
- completes. 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 (*note 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 (*note Point::). No I/O.
-
-`D'
- A directory name. The default is the current default directory of
- the current buffer, `default-directory' (*note System
- Environment::). Existing, Completion, Default, Prompt.
-
-`e'
- The last mouse-button or misc-user event in the key sequence that
- invoked the command. 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
- mouse-button or misc-user events, the Nth `e' provides the Nth
- such event.
-
-`f'
- A file name of an existing file (*note 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 (*note 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
- vector of events. 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. *Note 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
- (*note 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'). *Note 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. *Note 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.
-
-\1f
-File: lispref.info, Node: Interactive Examples, Prev: Interactive Codes, Up: Defining Commands
-
-Examples of Using `interactive'
--------------------------------
-
- Here are some examples of `interactive':
-
- (defun foo1 () ; `foo1' takes no arguments,
- (interactive) ; just moves forward two words.
- (forward-word 2))
- => foo1
-
- (defun foo2 (n) ; `foo2' takes one argument,
- (interactive "p") ; which is the numeric prefix.
- (forward-word (* 2 n)))
- => foo2
-
- (defun foo3 (n) ; `foo3' takes one argument,
- (interactive "nCount:") ; which is read with the Minibuffer.
- (forward-word (* 2 n)))
- => foo3
-
- (defun three-b (b1 b2 b3)
- "Select three existing buffers.
- Put them into three windows, selecting the last one."
- (interactive "bBuffer1:\nbBuffer2:\nbBuffer3:")
- (delete-other-windows)
- (split-window (selected-window) 8)
- (switch-to-buffer b1)
- (other-window 1)
- (split-window (selected-window) 8)
- (switch-to-buffer b2)
- (other-window 1)
- (switch-to-buffer b3))
- => three-b
- (three-b "*scratch*" "declarations.texi" "*mail*")
- => nil
-
-\1f
-File: lispref.info, Node: Interactive Call, Next: Command Loop Info, Prev: Defining Commands, Up: Command Loop
-
-Interactive Call
-================
-
- After the command loop has translated a key sequence into a
-definition, it invokes that definition using the function
-`command-execute'. If the definition is a function that is a command,
-`command-execute' calls `call-interactively', which reads the arguments
-and calls the command. You can also call these functions yourself.
-
- - Function: commandp object
- Returns `t' if OBJECT is suitable for calling interactively; that
- is, if OBJECT is a command. Otherwise, returns `nil'.
-
- The interactively callable objects include strings and vectors
- (treated as keyboard macros), lambda expressions that contain a
- top-level call to `interactive', compiled-function objects made
- from such lambda expressions, autoload objects that are declared
- as interactive (non-`nil' fourth argument to `autoload'), and some
- of the primitive functions.
-
- A symbol is `commandp' if its function definition is `commandp'.
-
- Keys and keymaps are not commands. Rather, they are used to look
- up commands (*note Keymaps::).
-
- See `documentation' in *Note Accessing Documentation::, for a
- realistic example of using `commandp'.
-
- - Function: call-interactively command &optional record-flag
- This function calls the interactively callable function COMMAND,
- reading arguments according to its interactive calling
- specifications. An error is signaled if COMMAND is not a function
- or if it cannot be called interactively (i.e., is not a command).
- Note that keyboard macros (strings and vectors) are not accepted,
- even though they are considered commands, because they are not
- functions.
-
- If RECORD-FLAG is the symbol `lambda', the interactive calling
- arguments for `command' are read and returned as a list, but the
- function is not called on them.
-
- If RECORD-FLAG is `t', then this command and its arguments are
- unconditionally added to the list `command-history'. Otherwise,
- the command is added only if it uses the minibuffer to read an
- argument. *Note Command History::.
-
- - Function: command-execute command &optional record-flag
- This function executes COMMAND as an editing command. The
- argument COMMAND must satisfy the `commandp' predicate; i.e., it
- must be an interactively callable function or a keyboard macro.
-
- A string or vector as COMMAND is executed with
- `execute-kbd-macro'. A function is passed to
- `call-interactively', along with the optional RECORD-FLAG.
-
- A symbol is handled by using its function definition in its place.
- A symbol with an `autoload' definition counts as a command if it
- was declared to stand for an interactively callable function.
- Such a definition is handled by loading the specified library and
- then rechecking the definition of the symbol.
-
- - Command: execute-extended-command prefix-argument
- This function reads a command name from the minibuffer using
- `completing-read' (*note Completion::). Then it uses
- `command-execute' to call the specified command. Whatever that
- command returns becomes the value of `execute-extended-command'.
-
- If the command asks for a prefix argument, it receives the value
- PREFIX-ARGUMENT. If `execute-extended-command' is called
- interactively, the current raw prefix argument is used for
- PREFIX-ARGUMENT, and thus passed on to whatever command is run.
-
- `execute-extended-command' is the normal definition of `M-x', so
- it uses the string `M-x ' as a prompt. (It would be better to
- take the prompt from the events used to invoke
- `execute-extended-command', but that is painful to implement.) A
- description of the value of the prefix argument, if any, also
- becomes part of the prompt.
-
- (execute-extended-command 1)
- ---------- Buffer: Minibuffer ----------
- 1 M-x forward-word RET
- ---------- Buffer: Minibuffer ----------
- => t
-
- - Function: interactive-p
- This function returns `t' if the containing function (the one that
- called `interactive-p') was called interactively, with the function
- `call-interactively'. (It makes no difference whether
- `call-interactively' was called from Lisp or directly from the
- editor command loop.) If the containing function was called by
- Lisp evaluation (or with `apply' or `funcall'), then it was not
- called interactively.
-
- The most common use of `interactive-p' is for deciding whether to
- print an informative message. As a special exception,
- `interactive-p' returns `nil' whenever a keyboard macro is being
- run. This is to suppress the informative messages and speed
- execution of the macro.
-
- For example:
-
- (defun foo ()
- (interactive)
- (and (interactive-p)
- (message "foo")))
- => foo
-
- (defun bar ()
- (interactive)
- (setq foobar (list (foo) (interactive-p))))
- => bar
-
- ;; Type `M-x foo'.
- -| foo
-
- ;; Type `M-x bar'.
- ;; This does not print anything.
-
- foobar
- => (nil t)
-