-This is Info file ../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref/lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0b from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
Foundation instead of in the original English.
\1f
+File: lispref.info, Node: Basic Completion, Next: Minibuffer Completion, Up: Completion
+
+Basic Completion Functions
+--------------------------
+
+ The two functions `try-completion' and `all-completions' have
+nothing in themselves to do with minibuffers. We describe them in this
+chapter so as to keep them near the higher-level completion features
+that do use the minibuffer.
+
+ - Function: try-completion string collection &optional predicate
+ This function returns the longest common prefix of all possible
+ completions of STRING in COLLECTION. The value of COLLECTION must
+ be an alist, an obarray, or a function that implements a virtual
+ set of strings (see below).
+
+ Completion compares STRING against each of the permissible
+ completions specified by COLLECTION; if the beginning of the
+ permissible completion equals STRING, it matches. If no
+ permissible completions match, `try-completion' returns `nil'. If
+ only one permissible completion matches, and the match is exact,
+ then `try-completion' returns `t'. Otherwise, the value is the
+ longest initial sequence common to all the permissible completions
+ that match.
+
+ If COLLECTION is an alist (*note Association Lists::), the CARs of
+ the alist elements form the set of permissible completions.
+
+ If COLLECTION is an obarray (*note Creating Symbols::), the names
+ of all symbols in the obarray form the set of permissible
+ completions. The global variable `obarray' holds an obarray
+ containing the names of all interned Lisp symbols.
+
+ Note that the only valid way to make a new obarray is to create it
+ empty and then add symbols to it one by one using `intern'. Also,
+ you cannot intern a given symbol in more than one obarray.
+
+ If the argument PREDICATE is non-`nil', then it must be a function
+ of one argument. It is used to test each possible match, and the
+ match is accepted only if PREDICATE returns non-`nil'. The
+ argument given to PREDICATE is either a cons cell from the alist
+ (the CAR of which is a string) or else it is a symbol (_not_ a
+ symbol name) from the obarray.
+
+ You can also use a symbol that is a function as COLLECTION. Then
+ the function is solely responsible for performing completion;
+ `try-completion' returns whatever this function returns. The
+ function is called with three arguments: STRING, PREDICATE and
+ `nil'. (The reason for the third argument is so that the same
+ function can be used in `all-completions' and do the appropriate
+ thing in either case.) *Note Programmed Completion::.
+
+ In the first of the following examples, the string `foo' is
+ matched by three of the alist CARs. All of the matches begin with
+ the characters `fooba', so that is the result. In the second
+ example, there is only one possible match, and it is exact, so the
+ value is `t'.
+
+ (try-completion
+ "foo"
+ '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)))
+ => "fooba"
+
+ (try-completion "foo" '(("barfoo" 2) ("foo" 3)))
+ => t
+
+ In the following example, numerous symbols begin with the
+ characters `forw', and all of them begin with the word `forward'.
+ In most of the symbols, this is followed with a `-', but not in
+ all, so no more than `forward' can be completed.
+
+ (try-completion "forw" obarray)
+ => "forward"
+
+ Finally, in the following example, only two of the three possible
+ matches pass the predicate `test' (the string `foobaz' is too
+ short). Both of those begin with the string `foobar'.
+
+ (defun test (s)
+ (> (length (car s)) 6))
+ => test
+ (try-completion
+ "foo"
+ '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
+ 'test)
+ => "foobar"
+
+ - Function: all-completions string collection &optional predicate
+ This function returns a list of all possible completions of STRING.
+ The arguments to this function are the same as those of
+ `try-completion'.
+
+ If COLLECTION is a function, it is called with three arguments:
+ STRING, PREDICATE and `t'; then `all-completions' returns whatever
+ the function returns. *Note Programmed Completion::.
+
+ Here is an example, using the function `test' shown in the example
+ for `try-completion':
+
+ (defun test (s)
+ (> (length (car s)) 6))
+ => test
+
+ (all-completions
+ "foo"
+ '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
+ 'test)
+ => ("foobar1" "foobar2")
+
+ - Variable: completion-ignore-case
+ If the value of this variable is non-`nil', XEmacs does not
+ consider case significant in completion.
+
+\1f
+File: lispref.info, Node: Minibuffer Completion, Next: Completion Commands, Prev: Basic Completion, Up: Completion
+
+Completion and the Minibuffer
+-----------------------------
+
+ This section describes the basic interface for reading from the
+minibuffer with completion.
+
+ - Function: completing-read prompt collection &optional predicate
+ require-match initial hist default
+ This function reads a string in the minibuffer, assisting the user
+ by providing completion. It activates the minibuffer with prompt
+ PROMPT, which must be a string. If INITIAL is non-`nil',
+ `completing-read' inserts it into the minibuffer as part of the
+ input. Then it allows the user to edit the input, providing
+ several commands to attempt completion.
+
+ The actual completion is done by passing COLLECTION and PREDICATE
+ to the function `try-completion'. This happens in certain
+ commands bound in the local keymaps used for completion.
+
+ If REQUIRE-MATCH is `t', the usual minibuffer exit commands won't
+ exit unless the input completes to an element of COLLECTION. If
+ REQUIRE-MATCH is neither `nil' nor `t', then the exit commands
+ won't exit unless the input typed is itself an element of
+ COLLECTION. If REQUIRE-MATCH is `nil', the exit commands work
+ regardless of the input in the minibuffer.
+
+ However, empty input is always permitted, regardless of the value
+ of REQUIRE-MATCH; in that case, `completing-read' returns DEFAULT.
+ The value of DEFAULT (if non-`nil') is also available to the user
+ through the history commands.
+
+ The user can exit with null input by typing <RET> with an empty
+ minibuffer. Then `completing-read' returns `""'. This is how the
+ user requests whatever default the command uses for the value being
+ read. The user can return using <RET> in this way regardless of
+ the value of REQUIRE-MATCH, and regardless of whether the empty
+ string is included in COLLECTION.
+
+ The function `completing-read' works by calling `read-expression'.
+ It uses `minibuffer-local-completion-map' as the keymap if
+ REQUIRE-MATCH is `nil', and uses `minibuffer-local-must-match-map'
+ if REQUIRE-MATCH is non-`nil'. *Note Completion Commands::.
+
+ The argument HIST specifies which history list variable to use for
+ saving the input and for minibuffer history commands. It defaults
+ to `minibuffer-history'. *Note Minibuffer History::.
+
+ Completion ignores case when comparing the input against the
+ possible matches, if the built-in variable
+ `completion-ignore-case' is non-`nil'. *Note Basic Completion::.
+
+ Here's an example of using `completing-read':
+
+ (completing-read
+ "Complete a foo: "
+ '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
+ nil t "fo")
+
+ ;; After evaluation of the preceding expression,
+ ;; the following appears in the minibuffer:
+
+ ---------- Buffer: Minibuffer ----------
+ Complete a foo: fo-!-
+ ---------- Buffer: Minibuffer ----------
+
+ If the user then types `<DEL> <DEL> b <RET>', `completing-read'
+ returns `barfoo'.
+
+ The `completing-read' function binds three variables to pass
+ information to the commands that actually do completion. These
+ variables are `minibuffer-completion-table',
+ `minibuffer-completion-predicate' and
+ `minibuffer-completion-confirm'. For more information about them,
+ see *Note Completion Commands::.
+
+\1f
+File: lispref.info, Node: Completion Commands, Next: High-Level Completion, Prev: Minibuffer Completion, Up: Completion
+
+Minibuffer Commands That Do Completion
+--------------------------------------
+
+ This section describes the keymaps, commands and user options used in
+the minibuffer to do completion.
+
+ - Variable: minibuffer-local-completion-map
+ `completing-read' uses this value as the local keymap when an
+ exact match of one of the completions is not required. By
+ default, this keymap makes the following bindings:
+
+ `?'
+ `minibuffer-completion-help'
+
+ <SPC>
+ `minibuffer-complete-word'
+
+ <TAB>
+ `minibuffer-complete'
+
+ with other characters bound as in `minibuffer-local-map' (*note
+ Text from Minibuffer::).
+
+ - Variable: minibuffer-local-must-match-map
+ `completing-read' uses this value as the local keymap when an
+ exact match of one of the completions is required. Therefore, no
+ keys are bound to `exit-minibuffer', the command that exits the
+ minibuffer unconditionally. By default, this keymap makes the
+ following bindings:
+
+ `?'
+ `minibuffer-completion-help'
+
+ <SPC>
+ `minibuffer-complete-word'
+
+ <TAB>
+ `minibuffer-complete'
+
+ `C-j'
+ `minibuffer-complete-and-exit'
+
+ <RET>
+ `minibuffer-complete-and-exit'
+
+ with other characters bound as in `minibuffer-local-map'.
+
+ - Variable: minibuffer-completion-table
+ The value of this variable is the alist or obarray used for
+ completion in the minibuffer. This is the global variable that
+ contains what `completing-read' passes to `try-completion'. It is
+ used by minibuffer completion commands such as
+ `minibuffer-complete-word'.
+
+ - Variable: minibuffer-completion-predicate
+ This variable's value is the predicate that `completing-read'
+ passes to `try-completion'. The variable is also used by the other
+ minibuffer completion functions.
+
+ - Command: minibuffer-complete-word
+ This function completes the minibuffer contents by at most a single
+ word. Even if the minibuffer contents have only one completion,
+ `minibuffer-complete-word' does not add any characters beyond the
+ first character that is not a word constituent. *Note Syntax
+ Tables::.
+
+ - Command: minibuffer-complete
+ This function completes the minibuffer contents as far as possible.
+
+ - Command: minibuffer-complete-and-exit
+ This function completes the minibuffer contents, and exits if
+ confirmation is not required, i.e., if
+ `minibuffer-completion-confirm' is `nil'. If confirmation _is_
+ required, it is given by repeating this command immediately--the
+ command is programmed to work without confirmation when run twice
+ in succession.
+
+ - Variable: minibuffer-completion-confirm
+ When the value of this variable is non-`nil', XEmacs asks for
+ confirmation of a completion before exiting the minibuffer. The
+ function `minibuffer-complete-and-exit' checks the value of this
+ variable before it exits.
+
+ - Command: minibuffer-completion-help
+ This function creates a list of the possible completions of the
+ current minibuffer contents. It works by calling `all-completions'
+ using the value of the variable `minibuffer-completion-table' as
+ the COLLECTION argument, and the value of
+ `minibuffer-completion-predicate' as the PREDICATE argument. The
+ list of completions is displayed as text in a buffer named
+ `*Completions*'.
+
+ - Function: display-completion-list completions &rest cl-keys
+ This function displays COMPLETIONS to the stream in
+ `standard-output', usually a buffer. (*Note Read and Print::, for
+ more information about streams.) The argument COMPLETIONS is
+ normally a list of completions just returned by `all-completions',
+ but it does not have to be. Each element may be a symbol or a
+ string, either of which is simply printed, or a list of two
+ strings, which is printed as if the strings were concatenated.
+
+ This function is called by `minibuffer-completion-help'. The most
+ common way to use it is together with
+ `with-output-to-temp-buffer', like this:
+
+ (with-output-to-temp-buffer "*Completions*"
+ (display-completion-list
+ (all-completions (buffer-string) my-alist)))
+
+ - User Option: completion-auto-help
+ If this variable is non-`nil', the completion commands
+ automatically display a list of possible completions whenever
+ nothing can be completed because the next character is not
+ uniquely determined.
+
+\1f
File: lispref.info, Node: High-Level Completion, Next: Reading File Names, Prev: Completion Commands, Up: Completion
High-Level Completion Functions
reading the arguments for a command, in the `interactive' spec. *Note
Defining Commands::.
- - Function: read-buffer PROMPT &optional DEFAULT EXISTING
+ - Function: read-buffer prompt &optional default existing
This function reads the name of a buffer and returns it as a
string. The argument DEFAULT is the default name to use, the
value to return if the user exits with an empty minibuffer. If
;; The user types `minibuffer.t <RET>'.
=> "minibuffer.texi"
- - Function: read-command PROMPT
+ - Function: read-command prompt &optional default-value
This function reads the name of a command and returns it as a Lisp
symbol. The argument PROMPT is used as in `read-from-minibuffer'.
Recall that a command is anything for which `commandp' returns
`t', and a command name is a symbol for which `commandp' returns
`t'. *Note Interactive Call::.
+ The argument DEFAULT-VALUE specifies what to return if the user
+ enters null input. It can be a symbol or a string; if it is a
+ string, `read-command' interns it before returning it. If DEFAULT
+ is `nil', that means no default has been specified; then if the
+ user enters null input, the return value is `nil'.
+
(read-command "Command name? ")
;; After evaluation of the preceding expression,
(intern (completing-read PROMPT obarray
'commandp t nil))
- - Function: read-variable PROMPT
+ - Function: read-variable prompt &optional default-value
This function reads the name of a user variable and returns it as a
symbol.
+ The argument DEFAULT-VALUE specifies what to return if the user
+ enters null input. It can be a symbol or a string; if it is a
+ string, `read-variable' interns it before returning it. If
+ DEFAULT-VALUE is `nil', that means no default has been specified;
+ then if the user enters null input, the return value is `nil'.
+
(read-variable "Variable name? ")
;; After evaluation of the preceding expression,
a file name. It provides special features including automatic insertion
of the default directory.
- - Function: read-file-name PROMPT &optional DIRECTORY DEFAULT EXISTING
- INITIAL
+ - Function: read-file-name prompt &optional directory default existing
+ initial history
This function reads a file name in the minibuffer, prompting with
PROMPT and providing completion. If DEFAULT is non-`nil', then
the function returns DEFAULT if the user just types <RET>.
Strictly speaking, `yes-or-no-p' uses the minibuffer and `y-or-n-p'
does not; but it seems best to describe them together.
- - Function: y-or-n-p PROMPT
+ - Function: y-or-n-p prompt
This function asks the user a question, expecting input in the echo
area. It returns `t' if the user types `y', `nil' if the user
types `n'. This function also accepts <SPC> to mean yes and <DEL>
This function does not actually use the minibuffer, since it does
not allow editing of the answer. It actually uses the echo area
- (*note The Echo Area::.), which uses the same screen space as the
+ (*note The Echo Area::), which uses the same screen space as the
minibuffer. The cursor moves to the echo area while the question
is being asked.
;; After evaluation of the preceding expression,
;; the following prompt appears in the echo area:
-
+
---------- Echo area ----------
Do you need a lift? (y or n)
---------- Echo area ----------
;; If the user then types `q', the following appears:
+
---------- Echo area ----------
Please answer y or n. Do you need a lift? (y or n)
---------- Echo area ----------
;; When the user types a valid answer,
;; it is displayed after the question:
+
---------- Echo area ----------
Do you need a lift? (y or n) y
---------- Echo area ----------
We show successive lines of echo area messages, but only one
actually appears on the screen at a time.
- - Function: yes-or-no-p PROMPT
+ - Function: yes-or-no-p prompt
This function asks the user a question, expecting input in the
minibuffer. It returns `t' if the user enters `yes', `nil' if the
user types `no'. The user must type <RET> to finalize the
;; After evaluation of the preceding expression,
;; the following prompt appears,
;; with an empty minibuffer:
-
+
---------- Buffer: minibuffer ----------
Do you really want to remove everything? (yes or no)
---------- Buffer: minibuffer ----------
Do you really want to remove everything? (yes or no)
---------- Buffer: minibuffer ----------
- - Function: yes-or-no-p-dialog-box PROMPT
+ - Function: yes-or-no-p-dialog-box prompt
This function asks the user a "y or n" question with a popup dialog
box. It returns `t' if the answer is "yes". PROMPT is the string
to display to ask the question.
are replaced with the following functions, so that menu items bring up
dialog boxes instead of minibuffer questions.
- - Function: y-or-n-p-maybe-dialog-box PROMPT
+ - Function: y-or-n-p-maybe-dialog-box prompt
This function asks user a "y or n" question, using either a dialog
box or the minibuffer, as appropriate.
- - Function: yes-or-no-p-maybe-dialog-box PROMPT
+ - Function: yes-or-no-p-maybe-dialog-box prompt
This function asks user a "yes or no" question, using either a
dialog box or the minibuffer, as appropriate.
each question individually. This gives the user certain convenient
facilities such as the ability to answer the whole series at once.
- - Function: map-y-or-n-p PROMPTER ACTOR LIST &optional HELP
- ACTION-ALIST
+ - Function: map-y-or-n-p prompter actor list &optional help
+ action-alist
This function, new in Emacs 19, asks the user a series of
questions, reading a single-character answer in the echo area for
each one.
If `map-y-or-n-p' is called in a command that was invoked using the
mouse--more precisely, if `last-nonmenu-event' (*note Command Loop
- Info::.) is either `nil' or a list--then it uses a dialog box or
+ Info::) is either `nil' or a list--then it uses a dialog box or
pop-up menu to ask the question. In this case, it does not use
keyboard input or the echo area. You can force use of the mouse
or use of keyboard input by binding `last-nonmenu-event' to a
To read a password to pass to another program, you can use the
function `read-passwd'.
- - Function: read-passwd PROMPT &optional CONFIRM DEFAULT
+ - Function: read-passwd prompt &optional confirm default
This function reads a password, prompting with PROMPT. It does
not echo the password as the user types it; instead, it echoes `.'
for each character in the password.
`read-passwd' returns the null string in that case.
- User Option: passwd-invert-frame-when-keyboard-grabbed
- If non-nil swap the foreground and background colors of all faces
- while reading a password. Default values is `t' unless feature
- `infodock' is provided.
+ If non-`nil', swap the foreground and background colors of all
+ faces while reading a password. Default values is `t', unless
+ feature `infodock' is provided.
- User Option: passwd-echo
This specifies the character echoed when typing a password. When
- nil, nothing is echoed.
+ `nil', nothing is echoed.
\1f
File: lispref.info, Node: Minibuffer Misc, Prev: Reading a Password, Up: Minibuffers
- Command: self-insert-and-exit
This command exits the active minibuffer after inserting the last
character typed on the keyboard (found in `last-command-char';
- *note Command Loop Info::.).
+ *note Command Loop Info::).
- - Command: previous-history-element N
+ - Command: previous-history-element n
This command replaces the minibuffer contents with the value of the
Nth previous (older) history element.
- - Command: next-history-element N
+ - Command: next-history-element n
This command replaces the minibuffer contents with the value of the
Nth more recent history element.
- - Command: previous-matching-history-element PATTERN
+ - Command: previous-matching-history-element pattern
This command replaces the minibuffer contents with the value of the
previous (older) history element that matches PATTERN (a regular
expression).
- - Command: next-matching-history-element PATTERN
+ - Command: next-matching-history-element pattern
This command replaces the minibuffer contents with the value of
the next (newer) history element that matches PATTERN (a regular
expression).
- Variable: minibuffer-help-form
The current value of this variable is used to rebind `help-form'
- locally inside the minibuffer (*note Help Functions::.).
+ locally inside the minibuffer (*note Help Functions::).
- Function: active-minibuffer-window
This function returns the currently active minibuffer window, or
`nil' if none is currently active.
- - Function: minibuffer-window &optional FRAME
+ - Function: minibuffer-window &optional frame
This function returns the minibuffer window used for frame FRAME.
If FRAME is `nil', that stands for the current frame. Note that
the minibuffer window used by a frame need not be part of that
frame--a frame that has no minibuffer of its own necessarily uses
some other frame's minibuffer window.
- - Function: window-minibuffer-p WINDOW
+ - Function: window-minibuffer-p &optional window
This function returns non-`nil' if WINDOW is a minibuffer window.
It is not correct to determine whether a given window is a
because there can be more than one minibuffer window if there is more
than one frame.
- - Function: minibuffer-window-active-p WINDOW
+ - Function: minibuffer-window-active-p window
This function returns non-`nil' if WINDOW, assumed to be a
minibuffer window, is currently active.
minibuffer, it scrolls this window.
Finally, some functions and variables deal with recursive minibuffers
-(*note Recursive Editing::.):
+(*note Recursive Editing::):
- Function: minibuffer-depth
This function returns the current depth of activations of the
* Events:: What input looks like when you read it.
* Reading Input:: How to read input events from the keyboard or mouse.
* Waiting:: Waiting for user input or elapsed time.
-* Quitting:: How `C-g' works. How to catch or defer quitting.
+* Quitting:: How C-g works. How to catch or defer quitting.
* Prefix Command Arguments:: How the commands to set prefix args work.
* Recursive Editing:: Entering a recursive edit,
and why you usually shouldn't.
translation should be a keyboard macro or an interactively callable
function. If the key is `M-x', then it reads the name of another
command, which it then calls. This is done by the command
-`execute-extended-command' (*note Interactive Call::.).
+`execute-extended-command' (*note Interactive Call::).
To execute a command requires first reading the arguments for it.
-This is done by calling `command-execute' (*note Interactive Call::.).
+This is done by calling `command-execute' (*note Interactive Call::).
For commands written in Lisp, the `interactive' specification says how
to read the arguments. This may use the prefix argument (*note Prefix
-Command Arguments::.) or may read with prompting in the minibuffer
-(*note Minibuffers::.). For example, the command `find-file' has an
+Command Arguments::) or may read with prompting in the minibuffer
+(*note Minibuffers::). For example, the command `find-file' has an
`interactive' specification which says to read a file name using the
minibuffer. The command's function body does not use the minibuffer;
if you call this command from Lisp code as a function, you must supply
If the command is a string or vector (i.e., a keyboard macro) then
`execute-kbd-macro' is used to execute it. You can call this function
-yourself (*note Keyboard Macros::.).
+yourself (*note Keyboard Macros::).
To terminate the execution of a running command, type `C-g'. This
-character causes "quitting" (*note Quitting::.).
+character causes "quitting" (*note Quitting::).
- Variable: pre-command-hook
The editor command loop runs this normal hook before each command.
in various ways.
* Interactive Examples:: Examples of how to read interactive arguments.
-\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)
-
projects / chise / xemacs-chise.git- / blobdiff