-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
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
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? ")
`read-passwd' returns the null string in that case.
- User Option: passwd-invert-frame-when-keyboard-grabbed
- If non-nil swap the foreground and background colors of all faces
- while reading a password. Default values is `t' unless feature
- `infodock' is provided.
+ If non-`nil', swap the foreground and background colors of all
+ faces while reading a password. Default values is `t', unless
+ feature `infodock' is provided.
- User Option: passwd-echo
This specifies the character echoed when typing a password. When
- nil, nothing is echoed.
+ `nil', nothing is echoed.
\1f
File: lispref.info, Node: Minibuffer Misc, Prev: Reading a Password, Up: Minibuffers
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
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
-
projects / chise / xemacs-chise.git- / blobdiff