X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=info%2Flispref.info-16;h=f7987c8cc8c022b9ddc150d3fe36e890558d00ea;hb=0b6cc849a8a353d01b8e5b001fcc27284d50ded8;hp=cea78a659fba40ab0c260667441943a7be6cc9e6;hpb=376658ea71d16dced8acff36c3e385ac3738d868;p=chise%2Fxemacs-chise.git diff --git a/info/lispref.info-16 b/info/lispref.info-16 index cea78a6..f7987c8 100644 --- a/info/lispref.info-16 +++ b/info/lispref.info-16 @@ -1,4 +1,4 @@ -This is ../info/lispref.info, produced by makeinfo version 3.12s from +This is ../info/lispref.info, produced by makeinfo version 4.0 from lispref/lispref.texi. INFO-DIR-SECTION XEmacs Editor @@ -50,6 +50,316 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +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. + + +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 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 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 ` b ', `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::. + + +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' + + + `minibuffer-complete-word' + + + `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' + + + `minibuffer-complete-word' + + + `minibuffer-complete' + + `C-j' + `minibuffer-complete-and-exit' + + + `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. + + File: lispref.info, Node: High-Level Completion, Next: Reading File Names, Prev: Completion Commands, Up: Completion High-Level Completion Functions @@ -94,13 +404,19 @@ Defining Commands::. ;; The user types `minibuffer.t '. => "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, @@ -123,10 +439,16 @@ Defining Commands::. (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, @@ -160,7 +482,7 @@ a file name. It provides special features including automatic insertion 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 . @@ -181,10 +503,10 @@ of the default directory. `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: @@ -267,8 +589,12 @@ function do all the work. * `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. @@ -419,7 +745,7 @@ dialog boxes instead of minibuffer questions. dialog box or the minibuffer, as appropriate.  -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 ================================ @@ -506,7 +832,40 @@ facilities such as the ability to answer the whole series at once. on.  -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. + + +File: lispref.info, Node: Minibuffer Misc, Prev: Reading a Password, Up: Minibuffers Minibuffer Miscellany ===================== @@ -573,7 +932,7 @@ minibuffers. 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 @@ -600,10 +959,10 @@ than one frame. - 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 @@ -620,8 +979,7 @@ minibuffer. The minibuffer command `next-matching-history-element' 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'.  File: lispref.info, Node: Command Loop, Next: Keymaps, Prev: Minibuffers, Up: Top @@ -733,443 +1091,3 @@ controls the reading of arguments for an interactive call. in various ways. * Interactive Examples:: Examples of how to read interactive arguments. - -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. - - -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. , , and 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 - or . (`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 - or . 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. - - -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 - - -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) -