-This is ../info/lispref.info, produced by makeinfo version 3.12s from
+This is ../info/lispref.info, produced by makeinfo version 4.0b from
lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
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
;; 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,
of the default directory.
- Function: read-file-name prompt &optional directory default existing
- initial
+ 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>.
`default-directory'.
If you specify INITIAL, that is an initial file name to insert in
- the buffer (after with DIRECTORY, if that is inserted). In this
- case, point goes at the beginning of INITIAL. The default for
- INITIAL is `nil'--don't insert any file name. To see what INITIAL
- does, try the command `C-x C-v'.
+ the buffer (after DIRECTORY, if that is inserted). In this case,
+ point goes at the beginning of INITIAL. The default for INITIAL
+ is `nil'--don't insert any file name. To see what INITIAL does,
+ try the command `C-x C-v'.
Here is an example:
* `nil' specifies `try-completion'. The completion function should
return the completion of the specified string, or `t' if the
- string is an exact match already, or `nil' if the string matches no
- possibility.
+ string is a unique and exact match already, or `nil' if the string
+ matches no possibility.
+
+ If the string is an exact match for one possibility, but also
+ matches other longer possibilities, the function should return the
+ string, not `t'.
* `t' specifies `all-completions'. The completion function should
return a list of all possible completions of the specified string.
dialog box or the minibuffer, as appropriate.
\1f
-File: lispref.info, Node: Multiple Queries, Next: Minibuffer Misc, Prev: Yes-or-No Queries, Up: Minibuffers
+File: lispref.info, Node: Multiple Queries, Next: Reading a Password, Prev: Yes-or-No Queries, Up: Minibuffers
Asking Multiple Y-or-N Questions
================================
on.
\1f
-File: lispref.info, Node: Minibuffer Misc, Prev: Multiple Queries, Up: Minibuffers
+File: lispref.info, Node: Reading a Password, Next: Minibuffer Misc, Prev: Multiple Queries, Up: Minibuffers
+
+Reading a Password
+==================
+
+ To read a password to pass to another program, you can use the
+function `read-passwd'.
+
+ - 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.
+
+ The optional argument CONFIRM, if non-`nil', says to read the
+ password twice and insist it must be the same both times. If it
+ isn't the same, the user has to type it over and over until the
+ last two times match.
+
+ The optional argument DEFAULT specifies the default password to
+ return if the user enters empty input. It is translated to `.'
+ and inserted in the minibuffer. If DEFAULT is `nil', then
+ `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.
+
+ - User Option: passwd-echo
+ This specifies the character echoed when typing a password. When
+ `nil', nothing is echoed.
+
+\1f
+File: lispref.info, Node: Minibuffer Misc, Prev: Reading a Password, Up: Minibuffers
Minibuffer Miscellany
=====================
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
- User Option: enable-recursive-minibuffers
If this variable is non-`nil', you can invoke commands (such as
- `find-file') that use minibuffers even while in the minibuffer
- window. Such invocation produces a recursive editing level for a
- new minibuffer. The outer-level minibuffer is invisible while you
- are editing the inner one.
+ `find-file') that use minibuffers even while the minibuffer window
+ is active. Such invocation produces a recursive editing level for
+ a new minibuffer. The outer-level minibuffer is invisible while
+ you are editing the inner one.
This variable only affects invoking the minibuffer while the
minibuffer window is selected. If you switch windows while in the
want to explicitly set the value of `enable-recursive-minibuffers' in
this fashion, just use an evaluated interactive spec and bind
`enable-recursive-minibuffers' while reading from the minibuffer. See
-the definition of `next-matching-history-element' in
-`lisp/prim/minibuf.el'.
+the definition of `next-matching-history-element' in `lisp/minibuf.el'.
\1f
File: lispref.info, Node: Command Loop, Next: Keymaps, Prev: Minibuffers, Up: Top
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