X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=info%2Flispref.info-16;h=6f8c37e9b6dda8b8311ab62df5efe086c040cb50;hb=dda61a5a3d1f0f3ffe6e0509c14565233ab999bd;hp=5e633047ef24d5250e46ba2c7d8ef336df1dca17;hpb=d8bd7eee3147c839d3c74d1823c139cd54867a75;p=chise%2Fxemacs-chise.git- diff --git a/info/lispref.info-16 b/info/lispref.info-16 index 5e63304..6f8c37e 100644 --- a/info/lispref.info-16 +++ b/info/lispref.info-16 @@ -1,4 +1,4 @@ -This is ../info/lispref.info, produced by makeinfo version 4.0 from +This is ../info/lispref.info, produced by makeinfo version 4.0b from lispref/lispref.texi. INFO-DIR-SECTION XEmacs Editor @@ -50,6 +50,198 @@ 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 @@ -253,9 +445,9 @@ Defining Commands::. 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 - is `nil', that means no default has been specified; then if the - user enters null input, the return value is `nil'. + 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? ") @@ -664,13 +856,13 @@ function `read-passwd'. `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.  File: lispref.info, Node: Minibuffer Misc, Prev: Reading a Password, Up: Minibuffers @@ -740,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 @@ -899,318 +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 -