1 This is ../info/lispref.info, produced by makeinfo version 4.0 from
4 INFO-DIR-SECTION XEmacs Editor
6 * Lispref: (lispref). XEmacs Lisp Reference Manual.
11 GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
21 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
22 Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
23 Copyright (C) 1995, 1996 Ben Wing.
25 Permission is granted to make and distribute verbatim copies of this
26 manual provided the copyright notice and this permission notice are
27 preserved on all copies.
29 Permission is granted to copy and distribute modified versions of
30 this manual under the conditions for verbatim copying, provided that the
31 entire resulting derived work is distributed under the terms of a
32 permission notice identical to this one.
34 Permission is granted to copy and distribute translations of this
35 manual into another language, under the above conditions for modified
36 versions, except that this permission notice may be stated in a
37 translation approved by the Foundation.
39 Permission is granted to copy and distribute modified versions of
40 this manual under the conditions for verbatim copying, provided also
41 that the section entitled "GNU General Public License" is included
42 exactly as in the original, and provided that the entire resulting
43 derived work is distributed under the terms of a permission notice
44 identical to this one.
46 Permission is granted to copy and distribute translations of this
47 manual into another language, under the above conditions for modified
48 versions, except that the section entitled "GNU General Public License"
49 may be included in a translation approved by the Free Software
50 Foundation instead of in the original English.
53 File: lispref.info, Node: Basic Completion, Next: Minibuffer Completion, Up: Completion
55 Basic Completion Functions
56 --------------------------
58 The two functions `try-completion' and `all-completions' have
59 nothing in themselves to do with minibuffers. We describe them in this
60 chapter so as to keep them near the higher-level completion features
61 that do use the minibuffer.
63 - Function: try-completion string collection &optional predicate
64 This function returns the longest common prefix of all possible
65 completions of STRING in COLLECTION. The value of COLLECTION must
66 be an alist, an obarray, or a function that implements a virtual
67 set of strings (see below).
69 Completion compares STRING against each of the permissible
70 completions specified by COLLECTION; if the beginning of the
71 permissible completion equals STRING, it matches. If no
72 permissible completions match, `try-completion' returns `nil'. If
73 only one permissible completion matches, and the match is exact,
74 then `try-completion' returns `t'. Otherwise, the value is the
75 longest initial sequence common to all the permissible completions
78 If COLLECTION is an alist (*note Association Lists::), the CARs of
79 the alist elements form the set of permissible completions.
81 If COLLECTION is an obarray (*note Creating Symbols::), the names
82 of all symbols in the obarray form the set of permissible
83 completions. The global variable `obarray' holds an obarray
84 containing the names of all interned Lisp symbols.
86 Note that the only valid way to make a new obarray is to create it
87 empty and then add symbols to it one by one using `intern'. Also,
88 you cannot intern a given symbol in more than one obarray.
90 If the argument PREDICATE is non-`nil', then it must be a function
91 of one argument. It is used to test each possible match, and the
92 match is accepted only if PREDICATE returns non-`nil'. The
93 argument given to PREDICATE is either a cons cell from the alist
94 (the CAR of which is a string) or else it is a symbol (_not_ a
95 symbol name) from the obarray.
97 You can also use a symbol that is a function as COLLECTION. Then
98 the function is solely responsible for performing completion;
99 `try-completion' returns whatever this function returns. The
100 function is called with three arguments: STRING, PREDICATE and
101 `nil'. (The reason for the third argument is so that the same
102 function can be used in `all-completions' and do the appropriate
103 thing in either case.) *Note Programmed Completion::.
105 In the first of the following examples, the string `foo' is
106 matched by three of the alist CARs. All of the matches begin with
107 the characters `fooba', so that is the result. In the second
108 example, there is only one possible match, and it is exact, so the
113 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)))
116 (try-completion "foo" '(("barfoo" 2) ("foo" 3)))
119 In the following example, numerous symbols begin with the
120 characters `forw', and all of them begin with the word `forward'.
121 In most of the symbols, this is followed with a `-', but not in
122 all, so no more than `forward' can be completed.
124 (try-completion "forw" obarray)
127 Finally, in the following example, only two of the three possible
128 matches pass the predicate `test' (the string `foobaz' is too
129 short). Both of those begin with the string `foobar'.
132 (> (length (car s)) 6))
136 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
140 - Function: all-completions string collection &optional predicate
141 This function returns a list of all possible completions of STRING.
142 The arguments to this function are the same as those of
145 If COLLECTION is a function, it is called with three arguments:
146 STRING, PREDICATE and `t'; then `all-completions' returns whatever
147 the function returns. *Note Programmed Completion::.
149 Here is an example, using the function `test' shown in the example
150 for `try-completion':
153 (> (length (car s)) 6))
158 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
160 => ("foobar1" "foobar2")
162 - Variable: completion-ignore-case
163 If the value of this variable is non-`nil', XEmacs does not
164 consider case significant in completion.
167 File: lispref.info, Node: Minibuffer Completion, Next: Completion Commands, Prev: Basic Completion, Up: Completion
169 Completion and the Minibuffer
170 -----------------------------
172 This section describes the basic interface for reading from the
173 minibuffer with completion.
175 - Function: completing-read prompt collection &optional predicate
176 require-match initial hist default
177 This function reads a string in the minibuffer, assisting the user
178 by providing completion. It activates the minibuffer with prompt
179 PROMPT, which must be a string. If INITIAL is non-`nil',
180 `completing-read' inserts it into the minibuffer as part of the
181 input. Then it allows the user to edit the input, providing
182 several commands to attempt completion.
184 The actual completion is done by passing COLLECTION and PREDICATE
185 to the function `try-completion'. This happens in certain
186 commands bound in the local keymaps used for completion.
188 If REQUIRE-MATCH is `t', the usual minibuffer exit commands won't
189 exit unless the input completes to an element of COLLECTION. If
190 REQUIRE-MATCH is neither `nil' nor `t', then the exit commands
191 won't exit unless the input typed is itself an element of
192 COLLECTION. If REQUIRE-MATCH is `nil', the exit commands work
193 regardless of the input in the minibuffer.
195 However, empty input is always permitted, regardless of the value
196 of REQUIRE-MATCH; in that case, `completing-read' returns DEFAULT.
197 The value of DEFAULT (if non-`nil') is also available to the user
198 through the history commands.
200 The user can exit with null input by typing <RET> with an empty
201 minibuffer. Then `completing-read' returns `""'. This is how the
202 user requests whatever default the command uses for the value being
203 read. The user can return using <RET> in this way regardless of
204 the value of REQUIRE-MATCH, and regardless of whether the empty
205 string is included in COLLECTION.
207 The function `completing-read' works by calling `read-expression'.
208 It uses `minibuffer-local-completion-map' as the keymap if
209 REQUIRE-MATCH is `nil', and uses `minibuffer-local-must-match-map'
210 if REQUIRE-MATCH is non-`nil'. *Note Completion Commands::.
212 The argument HIST specifies which history list variable to use for
213 saving the input and for minibuffer history commands. It defaults
214 to `minibuffer-history'. *Note Minibuffer History::.
216 Completion ignores case when comparing the input against the
217 possible matches, if the built-in variable
218 `completion-ignore-case' is non-`nil'. *Note Basic Completion::.
220 Here's an example of using `completing-read':
224 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
227 ;; After evaluation of the preceding expression,
228 ;; the following appears in the minibuffer:
230 ---------- Buffer: Minibuffer ----------
231 Complete a foo: fo-!-
232 ---------- Buffer: Minibuffer ----------
234 If the user then types `<DEL> <DEL> b <RET>', `completing-read'
237 The `completing-read' function binds three variables to pass
238 information to the commands that actually do completion. These
239 variables are `minibuffer-completion-table',
240 `minibuffer-completion-predicate' and
241 `minibuffer-completion-confirm'. For more information about them,
242 see *Note Completion Commands::.
245 File: lispref.info, Node: Completion Commands, Next: High-Level Completion, Prev: Minibuffer Completion, Up: Completion
247 Minibuffer Commands That Do Completion
248 --------------------------------------
250 This section describes the keymaps, commands and user options used in
251 the minibuffer to do completion.
253 - Variable: minibuffer-local-completion-map
254 `completing-read' uses this value as the local keymap when an
255 exact match of one of the completions is not required. By
256 default, this keymap makes the following bindings:
259 `minibuffer-completion-help'
262 `minibuffer-complete-word'
265 `minibuffer-complete'
267 with other characters bound as in `minibuffer-local-map' (*note
268 Text from Minibuffer::).
270 - Variable: minibuffer-local-must-match-map
271 `completing-read' uses this value as the local keymap when an
272 exact match of one of the completions is required. Therefore, no
273 keys are bound to `exit-minibuffer', the command that exits the
274 minibuffer unconditionally. By default, this keymap makes the
278 `minibuffer-completion-help'
281 `minibuffer-complete-word'
284 `minibuffer-complete'
287 `minibuffer-complete-and-exit'
290 `minibuffer-complete-and-exit'
292 with other characters bound as in `minibuffer-local-map'.
294 - Variable: minibuffer-completion-table
295 The value of this variable is the alist or obarray used for
296 completion in the minibuffer. This is the global variable that
297 contains what `completing-read' passes to `try-completion'. It is
298 used by minibuffer completion commands such as
299 `minibuffer-complete-word'.
301 - Variable: minibuffer-completion-predicate
302 This variable's value is the predicate that `completing-read'
303 passes to `try-completion'. The variable is also used by the other
304 minibuffer completion functions.
306 - Command: minibuffer-complete-word
307 This function completes the minibuffer contents by at most a single
308 word. Even if the minibuffer contents have only one completion,
309 `minibuffer-complete-word' does not add any characters beyond the
310 first character that is not a word constituent. *Note Syntax
313 - Command: minibuffer-complete
314 This function completes the minibuffer contents as far as possible.
316 - Command: minibuffer-complete-and-exit
317 This function completes the minibuffer contents, and exits if
318 confirmation is not required, i.e., if
319 `minibuffer-completion-confirm' is `nil'. If confirmation _is_
320 required, it is given by repeating this command immediately--the
321 command is programmed to work without confirmation when run twice
324 - Variable: minibuffer-completion-confirm
325 When the value of this variable is non-`nil', XEmacs asks for
326 confirmation of a completion before exiting the minibuffer. The
327 function `minibuffer-complete-and-exit' checks the value of this
328 variable before it exits.
330 - Command: minibuffer-completion-help
331 This function creates a list of the possible completions of the
332 current minibuffer contents. It works by calling `all-completions'
333 using the value of the variable `minibuffer-completion-table' as
334 the COLLECTION argument, and the value of
335 `minibuffer-completion-predicate' as the PREDICATE argument. The
336 list of completions is displayed as text in a buffer named
339 - Function: display-completion-list completions &rest cl-keys
340 This function displays COMPLETIONS to the stream in
341 `standard-output', usually a buffer. (*Note Read and Print::, for
342 more information about streams.) The argument COMPLETIONS is
343 normally a list of completions just returned by `all-completions',
344 but it does not have to be. Each element may be a symbol or a
345 string, either of which is simply printed, or a list of two
346 strings, which is printed as if the strings were concatenated.
348 This function is called by `minibuffer-completion-help'. The most
349 common way to use it is together with
350 `with-output-to-temp-buffer', like this:
352 (with-output-to-temp-buffer "*Completions*"
353 (display-completion-list
354 (all-completions (buffer-string) my-alist)))
356 - User Option: completion-auto-help
357 If this variable is non-`nil', the completion commands
358 automatically display a list of possible completions whenever
359 nothing can be completed because the next character is not
363 File: lispref.info, Node: High-Level Completion, Next: Reading File Names, Prev: Completion Commands, Up: Completion
365 High-Level Completion Functions
366 --------------------------------
368 This section describes the higher-level convenient functions for
369 reading certain sorts of names with completion.
371 In most cases, you should not call these functions in the middle of a
372 Lisp function. When possible, do all minibuffer input as part of
373 reading the arguments for a command, in the `interactive' spec. *Note
376 - Function: read-buffer prompt &optional default existing
377 This function reads the name of a buffer and returns it as a
378 string. The argument DEFAULT is the default name to use, the
379 value to return if the user exits with an empty minibuffer. If
380 non-`nil', it should be a string or a buffer. It is mentioned in
381 the prompt, but is not inserted in the minibuffer as initial input.
383 If EXISTING is non-`nil', then the name specified must be that of
384 an existing buffer. The usual commands to exit the minibuffer do
385 not exit if the text is not valid, and <RET> does completion to
386 attempt to find a valid name. (However, DEFAULT is not checked
387 for validity; it is returned, whatever it is, if the user exits
388 with the minibuffer empty.)
390 In the following example, the user enters `minibuffer.t', and then
391 types <RET>. The argument EXISTING is `t', and the only buffer
392 name starting with the given input is `minibuffer.texi', so that
395 (read-buffer "Buffer name? " "foo" t)
396 ;; After evaluation of the preceding expression,
397 ;; the following prompt appears,
398 ;; with an empty minibuffer:
400 ---------- Buffer: Minibuffer ----------
401 Buffer name? (default foo) -!-
402 ---------- Buffer: Minibuffer ----------
404 ;; The user types `minibuffer.t <RET>'.
407 - Function: read-command prompt &optional default-value
408 This function reads the name of a command and returns it as a Lisp
409 symbol. The argument PROMPT is used as in `read-from-minibuffer'.
410 Recall that a command is anything for which `commandp' returns
411 `t', and a command name is a symbol for which `commandp' returns
412 `t'. *Note Interactive Call::.
414 The argument DEFAULT-VALUE specifies what to return if the user
415 enters null input. It can be a symbol or a string; if it is a
416 string, `read-command' interns it before returning it. If DEFAULT
417 is `nil', that means no default has been specified; then if the
418 user enters null input, the return value is `nil'.
420 (read-command "Command name? ")
422 ;; After evaluation of the preceding expression,
423 ;; the following prompt appears with an empty minibuffer:
425 ---------- Buffer: Minibuffer ----------
427 ---------- Buffer: Minibuffer ----------
429 If the user types `forward-c <RET>', then this function returns
432 The `read-command' function is a simplified interface to the
433 function `completing-read'. It uses the variable `obarray' so as
434 to complete in the set of extant Lisp symbols, and it uses the
435 `commandp' predicate so as to accept only command names:
437 (read-command PROMPT)
439 (intern (completing-read PROMPT obarray
442 - Function: read-variable prompt &optional default-value
443 This function reads the name of a user variable and returns it as a
446 The argument DEFAULT-VALUE specifies what to return if the user
447 enters null input. It can be a symbol or a string; if it is a
448 string, `read-variable' interns it before returning it. If
449 DEFAULT-VALUE is `nil', that means no default has been specified;
450 then if the user enters null input, the return value is `nil'.
452 (read-variable "Variable name? ")
454 ;; After evaluation of the preceding expression,
455 ;; the following prompt appears,
456 ;; with an empty minibuffer:
458 ---------- Buffer: Minibuffer ----------
460 ---------- Buffer: Minibuffer ----------
462 If the user then types `fill-p <RET>', `read-variable' returns
465 This function is similar to `read-command', but uses the predicate
466 `user-variable-p' instead of `commandp':
468 (read-variable PROMPT)
471 (completing-read PROMPT obarray
472 'user-variable-p t nil))
475 File: lispref.info, Node: Reading File Names, Next: Programmed Completion, Prev: High-Level Completion, Up: Completion
480 Here is another high-level completion function, designed for reading
481 a file name. It provides special features including automatic insertion
482 of the default directory.
484 - Function: read-file-name prompt &optional directory default existing
486 This function reads a file name in the minibuffer, prompting with
487 PROMPT and providing completion. If DEFAULT is non-`nil', then
488 the function returns DEFAULT if the user just types <RET>.
489 DEFAULT is not checked for validity; it is returned, whatever it
490 is, if the user exits with the minibuffer empty.
492 If EXISTING is non-`nil', then the user must specify the name of
493 an existing file; <RET> performs completion to make the name valid
494 if possible, and then refuses to exit if it is not valid. If the
495 value of EXISTING is neither `nil' nor `t', then <RET> also
496 requires confirmation after completion. If EXISTING is `nil',
497 then the name of a nonexistent file is acceptable.
499 The argument DIRECTORY specifies the directory to use for
500 completion of relative file names. If `insert-default-directory'
501 is non-`nil', DIRECTORY is also inserted in the minibuffer as
502 initial input. It defaults to the current buffer's value of
505 If you specify INITIAL, that is an initial file name to insert in
506 the buffer (after DIRECTORY, if that is inserted). In this case,
507 point goes at the beginning of INITIAL. The default for INITIAL
508 is `nil'--don't insert any file name. To see what INITIAL does,
509 try the command `C-x C-v'.
513 (read-file-name "The file is ")
515 ;; After evaluation of the preceding expression,
516 ;; the following appears in the minibuffer:
518 ---------- Buffer: Minibuffer ----------
519 The file is /gp/gnu/elisp/-!-
520 ---------- Buffer: Minibuffer ----------
522 Typing `manual <TAB>' results in the following:
524 ---------- Buffer: Minibuffer ----------
525 The file is /gp/gnu/elisp/manual.texi-!-
526 ---------- Buffer: Minibuffer ----------
528 If the user types <RET>, `read-file-name' returns the file name as
529 the string `"/gp/gnu/elisp/manual.texi"'.
531 - User Option: insert-default-directory
532 This variable is used by `read-file-name'. Its value controls
533 whether `read-file-name' starts by placing the name of the default
534 directory in the minibuffer, plus the initial file name if any.
535 If the value of this variable is `nil', then `read-file-name' does
536 not place any initial input in the minibuffer (unless you specify
537 initial input with the INITIAL argument). In that case, the
538 default directory is still used for completion of relative file
539 names, but is not displayed.
543 ;; Here the minibuffer starts out with the default directory.
544 (let ((insert-default-directory t))
545 (read-file-name "The file is "))
547 ---------- Buffer: Minibuffer ----------
548 The file is ~lewis/manual/-!-
549 ---------- Buffer: Minibuffer ----------
551 ;; Here the minibuffer is empty and only the prompt
552 ;; appears on its line.
553 (let ((insert-default-directory nil))
554 (read-file-name "The file is "))
556 ---------- Buffer: Minibuffer ----------
558 ---------- Buffer: Minibuffer ----------
561 File: lispref.info, Node: Programmed Completion, Prev: Reading File Names, Up: Completion
563 Programmed Completion
564 ---------------------
566 Sometimes it is not possible to create an alist or an obarray
567 containing all the intended possible completions. In such a case, you
568 can supply your own function to compute the completion of a given
569 string. This is called "programmed completion".
571 To use this feature, pass a symbol with a function definition as the
572 COLLECTION argument to `completing-read'. The function
573 `completing-read' arranges to pass your completion function along to
574 `try-completion' and `all-completions', which will then let your
575 function do all the work.
577 The completion function should accept three arguments:
579 * The string to be completed.
581 * The predicate function to filter possible matches, or `nil' if
582 none. Your function should call the predicate for each possible
583 match, and ignore the possible match if the predicate returns
586 * A flag specifying the type of operation.
588 There are three flag values for three operations:
590 * `nil' specifies `try-completion'. The completion function should
591 return the completion of the specified string, or `t' if the
592 string is a unique and exact match already, or `nil' if the string
593 matches no possibility.
595 If the string is an exact match for one possibility, but also
596 matches other longer possibilities, the function should return the
599 * `t' specifies `all-completions'. The completion function should
600 return a list of all possible completions of the specified string.
602 * `lambda' specifies a test for an exact match. The completion
603 function should return `t' if the specified string is an exact
604 match for some possibility; `nil' otherwise.
606 It would be consistent and clean for completion functions to allow
607 lambda expressions (lists that are functions) as well as function
608 symbols as COLLECTION, but this is impossible. Lists as completion
609 tables are already assigned another meaning--as alists. It would be
610 unreliable to fail to handle an alist normally because it is also a
611 possible function. So you must arrange for any function you wish to
612 use for completion to be encapsulated in a symbol.
614 Emacs uses programmed completion when completing file names. *Note
615 File Name Completion::.
618 File: lispref.info, Node: Yes-or-No Queries, Next: Multiple Queries, Prev: Completion, Up: Minibuffers
623 This section describes functions used to ask the user a yes-or-no
624 question. The function `y-or-n-p' can be answered with a single
625 character; it is useful for questions where an inadvertent wrong answer
626 will not have serious consequences. `yes-or-no-p' is suitable for more
627 momentous questions, since it requires three or four characters to
628 answer. Variations of these functions can be used to ask a yes-or-no
629 question using a dialog box, or optionally using one.
631 If either of these functions is called in a command that was invoked
632 using the mouse, then it uses a dialog box or pop-up menu to ask the
633 question. Otherwise, it uses keyboard input.
635 Strictly speaking, `yes-or-no-p' uses the minibuffer and `y-or-n-p'
636 does not; but it seems best to describe them together.
638 - Function: y-or-n-p prompt
639 This function asks the user a question, expecting input in the echo
640 area. It returns `t' if the user types `y', `nil' if the user
641 types `n'. This function also accepts <SPC> to mean yes and <DEL>
642 to mean no. It accepts `C-]' to mean "quit", like `C-g', because
643 the question might look like a minibuffer and for that reason the
644 user might try to use `C-]' to get out. The answer is a single
645 character, with no <RET> needed to terminate it. Upper and lower
648 "Asking the question" means printing PROMPT in the echo area,
649 followed by the string `(y or n) '. If the input is not one of
650 the expected answers (`y', `n', `<SPC>', `<DEL>', or something
651 that quits), the function responds `Please answer y or n.', and
654 This function does not actually use the minibuffer, since it does
655 not allow editing of the answer. It actually uses the echo area
656 (*note The Echo Area::), which uses the same screen space as the
657 minibuffer. The cursor moves to the echo area while the question
660 The answers and their meanings, even `y' and `n', are not
661 hardwired. The keymap `query-replace-map' specifies them. *Note
662 Search and Replace::.
664 In the following example, the user first types `q', which is
665 invalid. At the next prompt the user types `y'.
667 (y-or-n-p "Do you need a lift? ")
669 ;; After evaluation of the preceding expression,
670 ;; the following prompt appears in the echo area:
672 ---------- Echo area ----------
673 Do you need a lift? (y or n)
674 ---------- Echo area ----------
676 ;; If the user then types `q', the following appears:
678 ---------- Echo area ----------
679 Please answer y or n. Do you need a lift? (y or n)
680 ---------- Echo area ----------
682 ;; When the user types a valid answer,
683 ;; it is displayed after the question:
685 ---------- Echo area ----------
686 Do you need a lift? (y or n) y
687 ---------- Echo area ----------
689 We show successive lines of echo area messages, but only one
690 actually appears on the screen at a time.
692 - Function: yes-or-no-p prompt
693 This function asks the user a question, expecting input in the
694 minibuffer. It returns `t' if the user enters `yes', `nil' if the
695 user types `no'. The user must type <RET> to finalize the
696 response. Upper and lower case are equivalent.
698 `yes-or-no-p' starts by displaying PROMPT in the echo area,
699 followed by `(yes or no) '. The user must type one of the
700 expected responses; otherwise, the function responds `Please answer
701 yes or no.', waits about two seconds and repeats the request.
703 `yes-or-no-p' requires more work from the user than `y-or-n-p' and
704 is appropriate for more crucial decisions.
708 (yes-or-no-p "Do you really want to remove everything? ")
710 ;; After evaluation of the preceding expression,
711 ;; the following prompt appears,
712 ;; with an empty minibuffer:
714 ---------- Buffer: minibuffer ----------
715 Do you really want to remove everything? (yes or no)
716 ---------- Buffer: minibuffer ----------
718 If the user first types `y <RET>', which is invalid because this
719 function demands the entire word `yes', it responds by displaying
720 these prompts, with a brief pause between them:
722 ---------- Buffer: minibuffer ----------
723 Please answer yes or no.
724 Do you really want to remove everything? (yes or no)
725 ---------- Buffer: minibuffer ----------
727 - Function: yes-or-no-p-dialog-box prompt
728 This function asks the user a "y or n" question with a popup dialog
729 box. It returns `t' if the answer is "yes". PROMPT is the string
730 to display to ask the question.
732 The following functions ask a question either in the minibuffer or a
733 dialog box, depending on whether the last user event (which presumably
734 invoked this command) was a keyboard or mouse event. When XEmacs is
735 running on a window system, the functions `y-or-n-p' and `yes-or-no-p'
736 are replaced with the following functions, so that menu items bring up
737 dialog boxes instead of minibuffer questions.
739 - Function: y-or-n-p-maybe-dialog-box prompt
740 This function asks user a "y or n" question, using either a dialog
741 box or the minibuffer, as appropriate.
743 - Function: yes-or-no-p-maybe-dialog-box prompt
744 This function asks user a "yes or no" question, using either a
745 dialog box or the minibuffer, as appropriate.
748 File: lispref.info, Node: Multiple Queries, Next: Reading a Password, Prev: Yes-or-No Queries, Up: Minibuffers
750 Asking Multiple Y-or-N Questions
751 ================================
753 When you have a series of similar questions to ask, such as "Do you
754 want to save this buffer" for each buffer in turn, you should use
755 `map-y-or-n-p' to ask the collection of questions, rather than asking
756 each question individually. This gives the user certain convenient
757 facilities such as the ability to answer the whole series at once.
759 - Function: map-y-or-n-p prompter actor list &optional help
761 This function, new in Emacs 19, asks the user a series of
762 questions, reading a single-character answer in the echo area for
765 The value of LIST specifies the objects to ask questions about.
766 It should be either a list of objects or a generator function. If
767 it is a function, it should expect no arguments, and should return
768 either the next object to ask about, or `nil' meaning stop asking
771 The argument PROMPTER specifies how to ask each question. If
772 PROMPTER is a string, the question text is computed like this:
774 (format PROMPTER OBJECT)
776 where OBJECT is the next object to ask about (as obtained from
779 If not a string, PROMPTER should be a function of one argument
780 (the next object to ask about) and should return the question
781 text. If the value is a string, that is the question to ask the
782 user. The function can also return `t' meaning do act on this
783 object (and don't ask the user), or `nil' meaning ignore this
784 object (and don't ask the user).
786 The argument ACTOR says how to act on the answers that the user
787 gives. It should be a function of one argument, and it is called
788 with each object that the user says yes for. Its argument is
789 always an object obtained from LIST.
791 If the argument HELP is given, it should be a list of this form:
793 (SINGULAR PLURAL ACTION)
795 where SINGULAR is a string containing a singular noun that
796 describes the objects conceptually being acted on, PLURAL is the
797 corresponding plural noun, and ACTION is a transitive verb
798 describing what ACTOR does.
800 If you don't specify HELP, the default is `("object" "objects"
803 Each time a question is asked, the user may enter `y', `Y', or
804 <SPC> to act on that object; `n', `N', or <DEL> to skip that
805 object; `!' to act on all following objects; <ESC> or `q' to exit
806 (skip all following objects); `.' (period) to act on the current
807 object and then exit; or `C-h' to get help. These are the same
808 answers that `query-replace' accepts. The keymap
809 `query-replace-map' defines their meaning for `map-y-or-n-p' as
810 well as for `query-replace'; see *Note Search and Replace::.
812 You can use ACTION-ALIST to specify additional possible answers
813 and what they mean. It is an alist of elements of the form `(CHAR
814 FUNCTION HELP)', each of which defines one additional answer. In
815 this element, CHAR is a character (the answer); FUNCTION is a
816 function of one argument (an object from LIST); HELP is a string.
818 When the user responds with CHAR, `map-y-or-n-p' calls FUNCTION.
819 If it returns non-`nil', the object is considered "acted upon",
820 and `map-y-or-n-p' advances to the next object in LIST. If it
821 returns `nil', the prompt is repeated for the same object.
823 If `map-y-or-n-p' is called in a command that was invoked using the
824 mouse--more precisely, if `last-nonmenu-event' (*note Command Loop
825 Info::) is either `nil' or a list--then it uses a dialog box or
826 pop-up menu to ask the question. In this case, it does not use
827 keyboard input or the echo area. You can force use of the mouse
828 or use of keyboard input by binding `last-nonmenu-event' to a
829 suitable value around the call.
831 The return value of `map-y-or-n-p' is the number of objects acted
835 File: lispref.info, Node: Reading a Password, Next: Minibuffer Misc, Prev: Multiple Queries, Up: Minibuffers
840 To read a password to pass to another program, you can use the
841 function `read-passwd'.
843 - Function: read-passwd prompt &optional confirm default
844 This function reads a password, prompting with PROMPT. It does
845 not echo the password as the user types it; instead, it echoes `.'
846 for each character in the password.
848 The optional argument CONFIRM, if non-`nil', says to read the
849 password twice and insist it must be the same both times. If it
850 isn't the same, the user has to type it over and over until the
851 last two times match.
853 The optional argument DEFAULT specifies the default password to
854 return if the user enters empty input. It is translated to `.'
855 and inserted in the minibuffer. If DEFAULT is `nil', then
856 `read-passwd' returns the null string in that case.
858 - User Option: passwd-invert-frame-when-keyboard-grabbed
859 If non-`nil', swap the foreground and background colors of all
860 faces while reading a password. Default values is `t', unless
861 feature `infodock' is provided.
863 - User Option: passwd-echo
864 This specifies the character echoed when typing a password. When
865 `nil', nothing is echoed.
868 File: lispref.info, Node: Minibuffer Misc, Prev: Reading a Password, Up: Minibuffers
870 Minibuffer Miscellany
871 =====================
873 This section describes some basic functions and variables related to
876 - Command: exit-minibuffer
877 This command exits the active minibuffer. It is normally bound to
878 keys in minibuffer local keymaps.
880 - Command: self-insert-and-exit
881 This command exits the active minibuffer after inserting the last
882 character typed on the keyboard (found in `last-command-char';
883 *note Command Loop Info::).
885 - Command: previous-history-element n
886 This command replaces the minibuffer contents with the value of the
887 Nth previous (older) history element.
889 - Command: next-history-element n
890 This command replaces the minibuffer contents with the value of the
891 Nth more recent history element.
893 - Command: previous-matching-history-element pattern
894 This command replaces the minibuffer contents with the value of the
895 previous (older) history element that matches PATTERN (a regular
898 - Command: next-matching-history-element pattern
899 This command replaces the minibuffer contents with the value of
900 the next (newer) history element that matches PATTERN (a regular
903 - Function: minibuffer-prompt
904 This function returns the prompt string of the currently active
905 minibuffer. If no minibuffer is active, it returns `nil'.
907 - Function: minibuffer-prompt-width
908 This function returns the display width of the prompt string of the
909 currently active minibuffer. If no minibuffer is active, it
912 - Variable: minibuffer-setup-hook
913 This is a normal hook that is run whenever the minibuffer is
914 entered. *Note Hooks::.
916 - Variable: minibuffer-exit-hook
917 This is a normal hook that is run whenever the minibuffer is
918 exited. *Note Hooks::.
920 - Variable: minibuffer-help-form
921 The current value of this variable is used to rebind `help-form'
922 locally inside the minibuffer (*note Help Functions::).
924 - Function: active-minibuffer-window
925 This function returns the currently active minibuffer window, or
926 `nil' if none is currently active.
928 - Function: minibuffer-window &optional frame
929 This function returns the minibuffer window used for frame FRAME.
930 If FRAME is `nil', that stands for the current frame. Note that
931 the minibuffer window used by a frame need not be part of that
932 frame--a frame that has no minibuffer of its own necessarily uses
933 some other frame's minibuffer window.
935 - Function: window-minibuffer-p &optional window
936 This function returns non-`nil' if WINDOW is a minibuffer window.
938 It is not correct to determine whether a given window is a
939 minibuffer by comparing it with the result of `(minibuffer-window)',
940 because there can be more than one minibuffer window if there is more
943 - Function: minibuffer-window-active-p window
944 This function returns non-`nil' if WINDOW, assumed to be a
945 minibuffer window, is currently active.
947 - Variable: minibuffer-scroll-window
948 If the value of this variable is non-`nil', it should be a window
949 object. When the function `scroll-other-window' is called in the
950 minibuffer, it scrolls this window.
952 Finally, some functions and variables deal with recursive minibuffers
953 (*note Recursive Editing::):
955 - Function: minibuffer-depth
956 This function returns the current depth of activations of the
957 minibuffer, a nonnegative integer. If no minibuffers are active,
960 - User Option: enable-recursive-minibuffers
961 If this variable is non-`nil', you can invoke commands (such as
962 `find-file') that use minibuffers even while the minibuffer window
963 is active. Such invocation produces a recursive editing level for
964 a new minibuffer. The outer-level minibuffer is invisible while
965 you are editing the inner one.
967 This variable only affects invoking the minibuffer while the
968 minibuffer window is selected. If you switch windows while in the
969 minibuffer, you can always invoke minibuffer commands while some
970 other window is selected.
972 In FSF Emacs 19, if a command name has a property
973 `enable-recursive-minibuffers' that is non-`nil', then the command can
974 use the minibuffer to read arguments even if it is invoked from the
975 minibuffer. The minibuffer command `next-matching-history-element'
976 (normally `M-s' in the minibuffer) uses this feature.
978 This is not implemented in XEmacs because it is a kludge. If you
979 want to explicitly set the value of `enable-recursive-minibuffers' in
980 this fashion, just use an evaluated interactive spec and bind
981 `enable-recursive-minibuffers' while reading from the minibuffer. See
982 the definition of `next-matching-history-element' in `lisp/minibuf.el'.
985 File: lispref.info, Node: Command Loop, Next: Keymaps, Prev: Minibuffers, Up: Top
990 When you run XEmacs, it enters the "editor command loop" almost
991 immediately. This loop reads events, executes their definitions, and
992 displays the results. In this chapter, we describe how these things
993 are done, and the subroutines that allow Lisp programs to do them.
997 * Command Overview:: How the command loop reads commands.
998 * Defining Commands:: Specifying how a function should read arguments.
999 * Interactive Call:: Calling a command, so that it will read arguments.
1000 * Command Loop Info:: Variables set by the command loop for you to examine.
1001 * Events:: What input looks like when you read it.
1002 * Reading Input:: How to read input events from the keyboard or mouse.
1003 * Waiting:: Waiting for user input or elapsed time.
1004 * Quitting:: How C-g works. How to catch or defer quitting.
1005 * Prefix Command Arguments:: How the commands to set prefix args work.
1006 * Recursive Editing:: Entering a recursive edit,
1007 and why you usually shouldn't.
1008 * Disabling Commands:: How the command loop handles disabled commands.
1009 * Command History:: How the command history is set up, and how accessed.
1010 * Keyboard Macros:: How keyboard macros are implemented.
1013 File: lispref.info, Node: Command Overview, Next: Defining Commands, Up: Command Loop
1015 Command Loop Overview
1016 =====================
1018 The command loop in XEmacs is a standard event loop, reading events
1019 one at a time with `next-event' and handling them with
1020 `dispatch-event'. An event is typically a single user action, such as
1021 a keypress, mouse movement, or menu selection; but they can also be
1022 notifications from the window system, informing XEmacs that (for
1023 example) part of its window was just uncovered and needs to be redrawn.
1024 *Note Events::. Pending events are held in a first-in, first-out list
1025 called the "event queue": events are read from the head of the list,
1026 and newly arriving events are added to the tail. In this way, events
1027 are always processed in the order in which they arrive.
1029 `dispatch-event' does most of the work of handling user actions.
1030 The first thing it must do is put the events together into a key
1031 sequence, which is a sequence of events that translates into a command.
1032 It does this by consulting the active keymaps, which specify what the
1033 valid key sequences are and how to translate them into commands. *Note
1034 Key Lookup::, for information on how this is done. The result of the
1035 translation should be a keyboard macro or an interactively callable
1036 function. If the key is `M-x', then it reads the name of another
1037 command, which it then calls. This is done by the command
1038 `execute-extended-command' (*note Interactive Call::).
1040 To execute a command requires first reading the arguments for it.
1041 This is done by calling `command-execute' (*note Interactive Call::).
1042 For commands written in Lisp, the `interactive' specification says how
1043 to read the arguments. This may use the prefix argument (*note Prefix
1044 Command Arguments::) or may read with prompting in the minibuffer
1045 (*note Minibuffers::). For example, the command `find-file' has an
1046 `interactive' specification which says to read a file name using the
1047 minibuffer. The command's function body does not use the minibuffer;
1048 if you call this command from Lisp code as a function, you must supply
1049 the file name string as an ordinary Lisp function argument.
1051 If the command is a string or vector (i.e., a keyboard macro) then
1052 `execute-kbd-macro' is used to execute it. You can call this function
1053 yourself (*note Keyboard Macros::).
1055 To terminate the execution of a running command, type `C-g'. This
1056 character causes "quitting" (*note Quitting::).
1058 - Variable: pre-command-hook
1059 The editor command loop runs this normal hook before each command.
1060 At that time, `this-command' contains the command that is about to
1061 run, and `last-command' describes the previous command. *Note
1064 - Variable: post-command-hook
1065 The editor command loop runs this normal hook after each command.
1066 (In FSF Emacs, it is also run when the command loop is entered, or
1067 reentered after an error or quit.) At that time, `this-command'
1068 describes the command that just ran, and `last-command' describes
1069 the command before that. *Note Hooks::.
1071 Quitting is suppressed while running `pre-command-hook' and
1072 `post-command-hook'. If an error happens while executing one of these
1073 hooks, it terminates execution of the hook, but that is all it does.
1076 File: lispref.info, Node: Defining Commands, Next: Interactive Call, Prev: Command Overview, Up: Command Loop
1081 A Lisp function becomes a command when its body contains, at top
1082 level, a form that calls the special form `interactive'. This form
1083 does nothing when actually executed, but its presence serves as a flag
1084 to indicate that interactive calling is permitted. Its argument
1085 controls the reading of arguments for an interactive call.
1089 * Using Interactive:: General rules for `interactive'.
1090 * Interactive Codes:: The standard letter-codes for reading arguments
1092 * Interactive Examples:: Examples of how to read interactive arguments.