1 This is Info file ../info/lispref.info, produced by Makeinfo version
2 1.68 from the input file lispref/lispref.texi.
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: High-Level Completion, Next: Reading File Names, Prev: Completion Commands, Up: Completion
55 High-Level Completion Functions
56 --------------------------------
58 This section describes the higher-level convenient functions for
59 reading certain sorts of names with completion.
61 In most cases, you should not call these functions in the middle of a
62 Lisp function. When possible, do all minibuffer input as part of
63 reading the arguments for a command, in the `interactive' spec. *Note
66 - Function: read-buffer PROMPT &optional DEFAULT EXISTING
67 This function reads the name of a buffer and returns it as a
68 string. The argument DEFAULT is the default name to use, the
69 value to return if the user exits with an empty minibuffer. If
70 non-`nil', it should be a string or a buffer. It is mentioned in
71 the prompt, but is not inserted in the minibuffer as initial input.
73 If EXISTING is non-`nil', then the name specified must be that of
74 an existing buffer. The usual commands to exit the minibuffer do
75 not exit if the text is not valid, and <RET> does completion to
76 attempt to find a valid name. (However, DEFAULT is not checked
77 for validity; it is returned, whatever it is, if the user exits
78 with the minibuffer empty.)
80 In the following example, the user enters `minibuffer.t', and then
81 types <RET>. The argument EXISTING is `t', and the only buffer
82 name starting with the given input is `minibuffer.texi', so that
85 (read-buffer "Buffer name? " "foo" t)
86 ;; After evaluation of the preceding expression,
87 ;; the following prompt appears,
88 ;; with an empty minibuffer:
90 ---------- Buffer: Minibuffer ----------
91 Buffer name? (default foo) -!-
92 ---------- Buffer: Minibuffer ----------
94 ;; The user types `minibuffer.t <RET>'.
97 - Function: read-command PROMPT
98 This function reads the name of a command and returns it as a Lisp
99 symbol. The argument PROMPT is used as in `read-from-minibuffer'.
100 Recall that a command is anything for which `commandp' returns
101 `t', and a command name is a symbol for which `commandp' returns
102 `t'. *Note Interactive Call::.
104 (read-command "Command name? ")
106 ;; After evaluation of the preceding expression,
107 ;; the following prompt appears with an empty minibuffer:
109 ---------- Buffer: Minibuffer ----------
111 ---------- Buffer: Minibuffer ----------
113 If the user types `forward-c <RET>', then this function returns
116 The `read-command' function is a simplified interface to the
117 function `completing-read'. It uses the variable `obarray' so as
118 to complete in the set of extant Lisp symbols, and it uses the
119 `commandp' predicate so as to accept only command names:
121 (read-command PROMPT)
123 (intern (completing-read PROMPT obarray
126 - Function: read-variable PROMPT
127 This function reads the name of a user variable and returns it as a
130 (read-variable "Variable name? ")
132 ;; After evaluation of the preceding expression,
133 ;; the following prompt appears,
134 ;; with an empty minibuffer:
136 ---------- Buffer: Minibuffer ----------
138 ---------- Buffer: Minibuffer ----------
140 If the user then types `fill-p <RET>', `read-variable' returns
143 This function is similar to `read-command', but uses the predicate
144 `user-variable-p' instead of `commandp':
146 (read-variable PROMPT)
149 (completing-read PROMPT obarray
150 'user-variable-p t nil))
153 File: lispref.info, Node: Reading File Names, Next: Programmed Completion, Prev: High-Level Completion, Up: Completion
158 Here is another high-level completion function, designed for reading
159 a file name. It provides special features including automatic insertion
160 of the default directory.
162 - Function: read-file-name PROMPT &optional DIRECTORY DEFAULT EXISTING
164 This function reads a file name in the minibuffer, prompting with
165 PROMPT and providing completion. If DEFAULT is non-`nil', then
166 the function returns DEFAULT if the user just types <RET>.
167 DEFAULT is not checked for validity; it is returned, whatever it
168 is, if the user exits with the minibuffer empty.
170 If EXISTING is non-`nil', then the user must specify the name of
171 an existing file; <RET> performs completion to make the name valid
172 if possible, and then refuses to exit if it is not valid. If the
173 value of EXISTING is neither `nil' nor `t', then <RET> also
174 requires confirmation after completion. If EXISTING is `nil',
175 then the name of a nonexistent file is acceptable.
177 The argument DIRECTORY specifies the directory to use for
178 completion of relative file names. If `insert-default-directory'
179 is non-`nil', DIRECTORY is also inserted in the minibuffer as
180 initial input. It defaults to the current buffer's value of
183 If you specify INITIAL, that is an initial file name to insert in
184 the buffer (after DIRECTORY, if that is inserted). In this case,
185 point goes at the beginning of INITIAL. The default for INITIAL
186 is `nil'--don't insert any file name. To see what INITIAL does,
187 try the command `C-x C-v'.
191 (read-file-name "The file is ")
193 ;; After evaluation of the preceding expression,
194 ;; the following appears in the minibuffer:
196 ---------- Buffer: Minibuffer ----------
197 The file is /gp/gnu/elisp/-!-
198 ---------- Buffer: Minibuffer ----------
200 Typing `manual <TAB>' results in the following:
202 ---------- Buffer: Minibuffer ----------
203 The file is /gp/gnu/elisp/manual.texi-!-
204 ---------- Buffer: Minibuffer ----------
206 If the user types <RET>, `read-file-name' returns the file name as
207 the string `"/gp/gnu/elisp/manual.texi"'.
209 - User Option: insert-default-directory
210 This variable is used by `read-file-name'. Its value controls
211 whether `read-file-name' starts by placing the name of the default
212 directory in the minibuffer, plus the initial file name if any.
213 If the value of this variable is `nil', then `read-file-name' does
214 not place any initial input in the minibuffer (unless you specify
215 initial input with the INITIAL argument). In that case, the
216 default directory is still used for completion of relative file
217 names, but is not displayed.
221 ;; Here the minibuffer starts out with the default directory.
222 (let ((insert-default-directory t))
223 (read-file-name "The file is "))
225 ---------- Buffer: Minibuffer ----------
226 The file is ~lewis/manual/-!-
227 ---------- Buffer: Minibuffer ----------
229 ;; Here the minibuffer is empty and only the prompt
230 ;; appears on its line.
231 (let ((insert-default-directory nil))
232 (read-file-name "The file is "))
234 ---------- Buffer: Minibuffer ----------
236 ---------- Buffer: Minibuffer ----------
239 File: lispref.info, Node: Programmed Completion, Prev: Reading File Names, Up: Completion
241 Programmed Completion
242 ---------------------
244 Sometimes it is not possible to create an alist or an obarray
245 containing all the intended possible completions. In such a case, you
246 can supply your own function to compute the completion of a given
247 string. This is called "programmed completion".
249 To use this feature, pass a symbol with a function definition as the
250 COLLECTION argument to `completing-read'. The function
251 `completing-read' arranges to pass your completion function along to
252 `try-completion' and `all-completions', which will then let your
253 function do all the work.
255 The completion function should accept three arguments:
257 * The string to be completed.
259 * The predicate function to filter possible matches, or `nil' if
260 none. Your function should call the predicate for each possible
261 match, and ignore the possible match if the predicate returns
264 * A flag specifying the type of operation.
266 There are three flag values for three operations:
268 * `nil' specifies `try-completion'. The completion function should
269 return the completion of the specified string, or `t' if the
270 string is a unique and exact match already, or `nil' if the string
271 matches no possibility.
273 If the string is an exact match for one possibility, but also
274 matches other longer possibilities, the function should return the
277 * `t' specifies `all-completions'. The completion function should
278 return a list of all possible completions of the specified string.
280 * `lambda' specifies a test for an exact match. The completion
281 function should return `t' if the specified string is an exact
282 match for some possibility; `nil' otherwise.
284 It would be consistent and clean for completion functions to allow
285 lambda expressions (lists that are functions) as well as function
286 symbols as COLLECTION, but this is impossible. Lists as completion
287 tables are already assigned another meaning--as alists. It would be
288 unreliable to fail to handle an alist normally because it is also a
289 possible function. So you must arrange for any function you wish to
290 use for completion to be encapsulated in a symbol.
292 Emacs uses programmed completion when completing file names. *Note
293 File Name Completion::.
296 File: lispref.info, Node: Yes-or-No Queries, Next: Multiple Queries, Prev: Completion, Up: Minibuffers
301 This section describes functions used to ask the user a yes-or-no
302 question. The function `y-or-n-p' can be answered with a single
303 character; it is useful for questions where an inadvertent wrong answer
304 will not have serious consequences. `yes-or-no-p' is suitable for more
305 momentous questions, since it requires three or four characters to
306 answer. Variations of these functions can be used to ask a yes-or-no
307 question using a dialog box, or optionally using one.
309 If either of these functions is called in a command that was invoked
310 using the mouse, then it uses a dialog box or pop-up menu to ask the
311 question. Otherwise, it uses keyboard input.
313 Strictly speaking, `yes-or-no-p' uses the minibuffer and `y-or-n-p'
314 does not; but it seems best to describe them together.
316 - Function: y-or-n-p PROMPT
317 This function asks the user a question, expecting input in the echo
318 area. It returns `t' if the user types `y', `nil' if the user
319 types `n'. This function also accepts <SPC> to mean yes and <DEL>
320 to mean no. It accepts `C-]' to mean "quit", like `C-g', because
321 the question might look like a minibuffer and for that reason the
322 user might try to use `C-]' to get out. The answer is a single
323 character, with no <RET> needed to terminate it. Upper and lower
326 "Asking the question" means printing PROMPT in the echo area,
327 followed by the string `(y or n) '. If the input is not one of
328 the expected answers (`y', `n', `<SPC>', `<DEL>', or something
329 that quits), the function responds `Please answer y or n.', and
332 This function does not actually use the minibuffer, since it does
333 not allow editing of the answer. It actually uses the echo area
334 (*note The Echo Area::.), which uses the same screen space as the
335 minibuffer. The cursor moves to the echo area while the question
338 The answers and their meanings, even `y' and `n', are not
339 hardwired. The keymap `query-replace-map' specifies them. *Note
340 Search and Replace::.
342 In the following example, the user first types `q', which is
343 invalid. At the next prompt the user types `y'.
345 (y-or-n-p "Do you need a lift? ")
347 ;; After evaluation of the preceding expression,
348 ;; the following prompt appears in the echo area:
350 ---------- Echo area ----------
351 Do you need a lift? (y or n)
352 ---------- Echo area ----------
354 ;; If the user then types `q', the following appears:
355 ---------- Echo area ----------
356 Please answer y or n. Do you need a lift? (y or n)
357 ---------- Echo area ----------
359 ;; When the user types a valid answer,
360 ;; it is displayed after the question:
361 ---------- Echo area ----------
362 Do you need a lift? (y or n) y
363 ---------- Echo area ----------
365 We show successive lines of echo area messages, but only one
366 actually appears on the screen at a time.
368 - Function: yes-or-no-p PROMPT
369 This function asks the user a question, expecting input in the
370 minibuffer. It returns `t' if the user enters `yes', `nil' if the
371 user types `no'. The user must type <RET> to finalize the
372 response. Upper and lower case are equivalent.
374 `yes-or-no-p' starts by displaying PROMPT in the echo area,
375 followed by `(yes or no) '. The user must type one of the
376 expected responses; otherwise, the function responds `Please answer
377 yes or no.', waits about two seconds and repeats the request.
379 `yes-or-no-p' requires more work from the user than `y-or-n-p' and
380 is appropriate for more crucial decisions.
384 (yes-or-no-p "Do you really want to remove everything? ")
386 ;; After evaluation of the preceding expression,
387 ;; the following prompt appears,
388 ;; with an empty minibuffer:
390 ---------- Buffer: minibuffer ----------
391 Do you really want to remove everything? (yes or no)
392 ---------- Buffer: minibuffer ----------
394 If the user first types `y <RET>', which is invalid because this
395 function demands the entire word `yes', it responds by displaying
396 these prompts, with a brief pause between them:
398 ---------- Buffer: minibuffer ----------
399 Please answer yes or no.
400 Do you really want to remove everything? (yes or no)
401 ---------- Buffer: minibuffer ----------
403 - Function: yes-or-no-p-dialog-box PROMPT
404 This function asks the user a "y or n" question with a popup dialog
405 box. It returns `t' if the answer is "yes". PROMPT is the string
406 to display to ask the question.
408 The following functions ask a question either in the minibuffer or a
409 dialog box, depending on whether the last user event (which presumably
410 invoked this command) was a keyboard or mouse event. When XEmacs is
411 running on a window system, the functions `y-or-n-p' and `yes-or-no-p'
412 are replaced with the following functions, so that menu items bring up
413 dialog boxes instead of minibuffer questions.
415 - Function: y-or-n-p-maybe-dialog-box PROMPT
416 This function asks user a "y or n" question, using either a dialog
417 box or the minibuffer, as appropriate.
419 - Function: yes-or-no-p-maybe-dialog-box PROMPT
420 This function asks user a "yes or no" question, using either a
421 dialog box or the minibuffer, as appropriate.
424 File: lispref.info, Node: Multiple Queries, Next: Reading a Password, Prev: Yes-or-No Queries, Up: Minibuffers
426 Asking Multiple Y-or-N Questions
427 ================================
429 When you have a series of similar questions to ask, such as "Do you
430 want to save this buffer" for each buffer in turn, you should use
431 `map-y-or-n-p' to ask the collection of questions, rather than asking
432 each question individually. This gives the user certain convenient
433 facilities such as the ability to answer the whole series at once.
435 - Function: map-y-or-n-p PROMPTER ACTOR LIST &optional HELP
437 This function, new in Emacs 19, asks the user a series of
438 questions, reading a single-character answer in the echo area for
441 The value of LIST specifies the objects to ask questions about.
442 It should be either a list of objects or a generator function. If
443 it is a function, it should expect no arguments, and should return
444 either the next object to ask about, or `nil' meaning stop asking
447 The argument PROMPTER specifies how to ask each question. If
448 PROMPTER is a string, the question text is computed like this:
450 (format PROMPTER OBJECT)
452 where OBJECT is the next object to ask about (as obtained from
455 If not a string, PROMPTER should be a function of one argument
456 (the next object to ask about) and should return the question
457 text. If the value is a string, that is the question to ask the
458 user. The function can also return `t' meaning do act on this
459 object (and don't ask the user), or `nil' meaning ignore this
460 object (and don't ask the user).
462 The argument ACTOR says how to act on the answers that the user
463 gives. It should be a function of one argument, and it is called
464 with each object that the user says yes for. Its argument is
465 always an object obtained from LIST.
467 If the argument HELP is given, it should be a list of this form:
469 (SINGULAR PLURAL ACTION)
471 where SINGULAR is a string containing a singular noun that
472 describes the objects conceptually being acted on, PLURAL is the
473 corresponding plural noun, and ACTION is a transitive verb
474 describing what ACTOR does.
476 If you don't specify HELP, the default is `("object" "objects"
479 Each time a question is asked, the user may enter `y', `Y', or
480 <SPC> to act on that object; `n', `N', or <DEL> to skip that
481 object; `!' to act on all following objects; <ESC> or `q' to exit
482 (skip all following objects); `.' (period) to act on the current
483 object and then exit; or `C-h' to get help. These are the same
484 answers that `query-replace' accepts. The keymap
485 `query-replace-map' defines their meaning for `map-y-or-n-p' as
486 well as for `query-replace'; see *Note Search and Replace::.
488 You can use ACTION-ALIST to specify additional possible answers
489 and what they mean. It is an alist of elements of the form `(CHAR
490 FUNCTION HELP)', each of which defines one additional answer. In
491 this element, CHAR is a character (the answer); FUNCTION is a
492 function of one argument (an object from LIST); HELP is a string.
494 When the user responds with CHAR, `map-y-or-n-p' calls FUNCTION.
495 If it returns non-`nil', the object is considered "acted upon",
496 and `map-y-or-n-p' advances to the next object in LIST. If it
497 returns `nil', the prompt is repeated for the same object.
499 If `map-y-or-n-p' is called in a command that was invoked using the
500 mouse--more precisely, if `last-nonmenu-event' (*note Command Loop
501 Info::.) is either `nil' or a list--then it uses a dialog box or
502 pop-up menu to ask the question. In this case, it does not use
503 keyboard input or the echo area. You can force use of the mouse
504 or use of keyboard input by binding `last-nonmenu-event' to a
505 suitable value around the call.
507 The return value of `map-y-or-n-p' is the number of objects acted
511 File: lispref.info, Node: Reading a Password, Next: Minibuffer Misc, Prev: Multiple Queries, Up: Minibuffers
516 To read a password to pass to another program, you can use the
517 function `read-passwd'.
519 - Function: read-passwd PROMPT &optional CONFIRM DEFAULT
520 This function reads a password, prompting with PROMPT. It does
521 not echo the password as the user types it; instead, it echoes `.'
522 for each character in the password.
524 The optional argument CONFIRM, if non-`nil', says to read the
525 password twice and insist it must be the same both times. If it
526 isn't the same, the user has to type it over and over until the
527 last two times match.
529 The optional argument DEFAULT specifies the default password to
530 return if the user enters empty input. It is translated to `.'
531 and inserted in the minibuffer. If DEFAULT is `nil', then
532 `read-passwd' returns the null string in that case.
534 - User Option: passwd-invert-frame-when-keyboard-grabbed
535 If non-nil swap the foreground and background colors of all faces
536 while reading a password. Default values is `t' unless feature
537 `infodock' is provided.
539 - User Option: passwd-echo
540 This specifies the character echoed when typing a password. When
541 nil, nothing is echoed.
544 File: lispref.info, Node: Minibuffer Misc, Prev: Reading a Password, Up: Minibuffers
546 Minibuffer Miscellany
547 =====================
549 This section describes some basic functions and variables related to
552 - Command: exit-minibuffer
553 This command exits the active minibuffer. It is normally bound to
554 keys in minibuffer local keymaps.
556 - Command: self-insert-and-exit
557 This command exits the active minibuffer after inserting the last
558 character typed on the keyboard (found in `last-command-char';
559 *note Command Loop Info::.).
561 - Command: previous-history-element N
562 This command replaces the minibuffer contents with the value of the
563 Nth previous (older) history element.
565 - Command: next-history-element N
566 This command replaces the minibuffer contents with the value of the
567 Nth more recent history element.
569 - Command: previous-matching-history-element PATTERN
570 This command replaces the minibuffer contents with the value of the
571 previous (older) history element that matches PATTERN (a regular
574 - Command: next-matching-history-element PATTERN
575 This command replaces the minibuffer contents with the value of
576 the next (newer) history element that matches PATTERN (a regular
579 - Function: minibuffer-prompt
580 This function returns the prompt string of the currently active
581 minibuffer. If no minibuffer is active, it returns `nil'.
583 - Function: minibuffer-prompt-width
584 This function returns the display width of the prompt string of the
585 currently active minibuffer. If no minibuffer is active, it
588 - Variable: minibuffer-setup-hook
589 This is a normal hook that is run whenever the minibuffer is
590 entered. *Note Hooks::.
592 - Variable: minibuffer-exit-hook
593 This is a normal hook that is run whenever the minibuffer is
594 exited. *Note Hooks::.
596 - Variable: minibuffer-help-form
597 The current value of this variable is used to rebind `help-form'
598 locally inside the minibuffer (*note Help Functions::.).
600 - Function: active-minibuffer-window
601 This function returns the currently active minibuffer window, or
602 `nil' if none is currently active.
604 - Function: minibuffer-window &optional FRAME
605 This function returns the minibuffer window used for frame FRAME.
606 If FRAME is `nil', that stands for the current frame. Note that
607 the minibuffer window used by a frame need not be part of that
608 frame--a frame that has no minibuffer of its own necessarily uses
609 some other frame's minibuffer window.
611 - Function: window-minibuffer-p WINDOW
612 This function returns non-`nil' if WINDOW is a minibuffer window.
614 It is not correct to determine whether a given window is a
615 minibuffer by comparing it with the result of `(minibuffer-window)',
616 because there can be more than one minibuffer window if there is more
619 - Function: minibuffer-window-active-p WINDOW
620 This function returns non-`nil' if WINDOW, assumed to be a
621 minibuffer window, is currently active.
623 - Variable: minibuffer-scroll-window
624 If the value of this variable is non-`nil', it should be a window
625 object. When the function `scroll-other-window' is called in the
626 minibuffer, it scrolls this window.
628 Finally, some functions and variables deal with recursive minibuffers
629 (*note Recursive Editing::.):
631 - Function: minibuffer-depth
632 This function returns the current depth of activations of the
633 minibuffer, a nonnegative integer. If no minibuffers are active,
636 - User Option: enable-recursive-minibuffers
637 If this variable is non-`nil', you can invoke commands (such as
638 `find-file') that use minibuffers even while the minibuffer window
639 is active. Such invocation produces a recursive editing level for
640 a new minibuffer. The outer-level minibuffer is invisible while
641 you are editing the inner one.
643 This variable only affects invoking the minibuffer while the
644 minibuffer window is selected. If you switch windows while in the
645 minibuffer, you can always invoke minibuffer commands while some
646 other window is selected.
648 In FSF Emacs 19, if a command name has a property
649 `enable-recursive-minibuffers' that is non-`nil', then the command can
650 use the minibuffer to read arguments even if it is invoked from the
651 minibuffer. The minibuffer command `next-matching-history-element'
652 (normally `M-s' in the minibuffer) uses this feature.
654 This is not implemented in XEmacs because it is a kludge. If you
655 want to explicitly set the value of `enable-recursive-minibuffers' in
656 this fashion, just use an evaluated interactive spec and bind
657 `enable-recursive-minibuffers' while reading from the minibuffer. See
658 the definition of `next-matching-history-element' in `lisp/minibuf.el'.
661 File: lispref.info, Node: Command Loop, Next: Keymaps, Prev: Minibuffers, Up: Top
666 When you run XEmacs, it enters the "editor command loop" almost
667 immediately. This loop reads events, executes their definitions, and
668 displays the results. In this chapter, we describe how these things
669 are done, and the subroutines that allow Lisp programs to do them.
673 * Command Overview:: How the command loop reads commands.
674 * Defining Commands:: Specifying how a function should read arguments.
675 * Interactive Call:: Calling a command, so that it will read arguments.
676 * Command Loop Info:: Variables set by the command loop for you to examine.
677 * Events:: What input looks like when you read it.
678 * Reading Input:: How to read input events from the keyboard or mouse.
679 * Waiting:: Waiting for user input or elapsed time.
680 * Quitting:: How `C-g' works. How to catch or defer quitting.
681 * Prefix Command Arguments:: How the commands to set prefix args work.
682 * Recursive Editing:: Entering a recursive edit,
683 and why you usually shouldn't.
684 * Disabling Commands:: How the command loop handles disabled commands.
685 * Command History:: How the command history is set up, and how accessed.
686 * Keyboard Macros:: How keyboard macros are implemented.
689 File: lispref.info, Node: Command Overview, Next: Defining Commands, Up: Command Loop
691 Command Loop Overview
692 =====================
694 The command loop in XEmacs is a standard event loop, reading events
695 one at a time with `next-event' and handling them with
696 `dispatch-event'. An event is typically a single user action, such as
697 a keypress, mouse movement, or menu selection; but they can also be
698 notifications from the window system, informing XEmacs that (for
699 example) part of its window was just uncovered and needs to be redrawn.
700 *Note Events::. Pending events are held in a first-in, first-out list
701 called the "event queue": events are read from the head of the list,
702 and newly arriving events are added to the tail. In this way, events
703 are always processed in the order in which they arrive.
705 `dispatch-event' does most of the work of handling user actions.
706 The first thing it must do is put the events together into a key
707 sequence, which is a sequence of events that translates into a command.
708 It does this by consulting the active keymaps, which specify what the
709 valid key sequences are and how to translate them into commands. *Note
710 Key Lookup::, for information on how this is done. The result of the
711 translation should be a keyboard macro or an interactively callable
712 function. If the key is `M-x', then it reads the name of another
713 command, which it then calls. This is done by the command
714 `execute-extended-command' (*note Interactive Call::.).
716 To execute a command requires first reading the arguments for it.
717 This is done by calling `command-execute' (*note Interactive Call::.).
718 For commands written in Lisp, the `interactive' specification says how
719 to read the arguments. This may use the prefix argument (*note Prefix
720 Command Arguments::.) or may read with prompting in the minibuffer
721 (*note Minibuffers::.). For example, the command `find-file' has an
722 `interactive' specification which says to read a file name using the
723 minibuffer. The command's function body does not use the minibuffer;
724 if you call this command from Lisp code as a function, you must supply
725 the file name string as an ordinary Lisp function argument.
727 If the command is a string or vector (i.e., a keyboard macro) then
728 `execute-kbd-macro' is used to execute it. You can call this function
729 yourself (*note Keyboard Macros::.).
731 To terminate the execution of a running command, type `C-g'. This
732 character causes "quitting" (*note Quitting::.).
734 - Variable: pre-command-hook
735 The editor command loop runs this normal hook before each command.
736 At that time, `this-command' contains the command that is about to
737 run, and `last-command' describes the previous command. *Note
740 - Variable: post-command-hook
741 The editor command loop runs this normal hook after each command.
742 (In FSF Emacs, it is also run when the command loop is entered, or
743 reentered after an error or quit.) At that time, `this-command'
744 describes the command that just ran, and `last-command' describes
745 the command before that. *Note Hooks::.
747 Quitting is suppressed while running `pre-command-hook' and
748 `post-command-hook'. If an error happens while executing one of these
749 hooks, it terminates execution of the hook, but that is all it does.
752 File: lispref.info, Node: Defining Commands, Next: Interactive Call, Prev: Command Overview, Up: Command Loop
757 A Lisp function becomes a command when its body contains, at top
758 level, a form that calls the special form `interactive'. This form
759 does nothing when actually executed, but its presence serves as a flag
760 to indicate that interactive calling is permitted. Its argument
761 controls the reading of arguments for an interactive call.
765 * Using Interactive:: General rules for `interactive'.
766 * Interactive Codes:: The standard letter-codes for reading arguments
768 * Interactive Examples:: Examples of how to read interactive arguments.
771 File: lispref.info, Node: Using Interactive, Next: Interactive Codes, Up: Defining Commands
776 This section describes how to write the `interactive' form that
777 makes a Lisp function an interactively-callable command.
779 - Special Form: interactive ARG-DESCRIPTOR
780 This special form declares that the function in which it appears
781 is a command, and that it may therefore be called interactively
782 (via `M-x' or by entering a key sequence bound to it). The
783 argument ARG-DESCRIPTOR declares how to compute the arguments to
784 the command when the command is called interactively.
786 A command may be called from Lisp programs like any other
787 function, but then the caller supplies the arguments and
788 ARG-DESCRIPTOR has no effect.
790 The `interactive' form has its effect because the command loop
791 (actually, its subroutine `call-interactively') scans through the
792 function definition looking for it, before calling the function.
793 Once the function is called, all its body forms including the
794 `interactive' form are executed, but at this time `interactive'
795 simply returns `nil' without even evaluating its argument.
797 There are three possibilities for the argument ARG-DESCRIPTOR:
799 * It may be omitted or `nil'; then the command is called with no
800 arguments. This leads quickly to an error if the command requires
801 one or more arguments.
803 * It may be a Lisp expression that is not a string; then it should
804 be a form that is evaluated to get a list of arguments to pass to
807 If this expression reads keyboard input (this includes using the
808 minibuffer), keep in mind that the integer value of point or the
809 mark before reading input may be incorrect after reading input.
810 This is because the current buffer may be receiving subprocess
811 output; if subprocess output arrives while the command is waiting
812 for input, it could relocate point and the mark.
814 Here's an example of what *not* to do:
817 (list (region-beginning) (region-end)
818 (read-string "Foo: " nil 'my-history)))
820 Here's how to avoid the problem, by examining point and the mark
821 only after reading the keyboard input:
824 (let ((string (read-string "Foo: " nil 'my-history)))
825 (list (region-beginning) (region-end) string)))
827 * It may be a string; then its contents should consist of a code
828 character followed by a prompt (which some code characters use and
829 some ignore). The prompt ends either with the end of the string
830 or with a newline. Here is a simple example:
832 (interactive "bFrobnicate buffer: ")
834 The code letter `b' says to read the name of an existing buffer,
835 with completion. The buffer name is the sole argument passed to
836 the command. The rest of the string is a prompt.
838 If there is a newline character in the string, it terminates the
839 prompt. If the string does not end there, then the rest of the
840 string should contain another code character and prompt,
841 specifying another argument. You can specify any number of
842 arguments in this way.
844 The prompt string can use `%' to include previous argument values
845 (starting with the first argument) in the prompt. This is done
846 using `format' (*note Formatting Strings::.). For example, here
847 is how you could read the name of an existing buffer followed by a
848 new name to give to that buffer:
850 (interactive "bBuffer to rename: \nsRename buffer %s to: ")
852 If the first character in the string is `*', then an error is
853 signaled if the buffer is read-only.
855 If the first character in the string is `@', and if the key
856 sequence used to invoke the command includes any mouse events, then
857 the window associated with the first of those events is selected
858 before the command is run.
860 If the first character in the string is `_', then this command will
861 not cause the region to be deactivated when it completes; that is,
862 `zmacs-region-stays' will be set to `t' when the command exits
865 You can use `*', `@', and `_' together; the order does not matter.
866 Actual reading of arguments is controlled by the rest of the
867 prompt string (starting with the first character that is not `*',
870 - Function: function-interactive FUNCTION
871 This function retrieves the interactive specification of FUNCTION,
872 which may be any funcallable object. The specification will be
873 returned as the list of the symbol `interactive' and the specs. If
874 FUNCTION is not interactive, `nil' will be returned.
877 File: lispref.info, Node: Interactive Codes, Next: Interactive Examples, Prev: Using Interactive, Up: Defining Commands
879 Code Characters for `interactive'
880 ---------------------------------
882 The code character descriptions below contain a number of key words,
883 defined here as follows:
886 Provide completion. <TAB>, <SPC>, and <RET> perform name
887 completion because the argument is read using `completing-read'
888 (*note Completion::.). `?' displays a list of possible
892 Require the name of an existing object. An invalid name is not
893 accepted; the commands to exit the minibuffer do not exit if the
894 current input is not valid.
897 A default value of some sort is used if the user enters no text in
898 the minibuffer. The default depends on the code character.
901 This code letter computes an argument without reading any input.
902 Therefore, it does not use a prompt string, and any prompt string
903 you supply is ignored.
905 Even though the code letter doesn't use a prompt string, you must
906 follow it with a newline if it is not the last code character in
910 A prompt immediately follows the code character. The prompt ends
911 either with the end of the string or with a newline.
914 This code character is meaningful only at the beginning of the
915 interactive string, and it does not look for a prompt or a newline.
916 It is a single, isolated character.
918 Here are the code character descriptions for use with `interactive':
921 Signal an error if the current buffer is read-only. Special.
924 Select the window mentioned in the first mouse event in the key
925 sequence that invoked this command. Special.
928 Do not cause the region to be deactivated when this command
932 A function name (i.e., a symbol satisfying `fboundp'). Existing,
936 The name of an existing buffer. By default, uses the name of the
937 current buffer (*note Buffers::.). Existing, Completion, Default,
941 A buffer name. The buffer need not exist. By default, uses the
942 name of a recently used buffer other than the current buffer.
943 Completion, Default, Prompt.
946 A character. The cursor does not move into the echo area. Prompt.
949 A command name (i.e., a symbol satisfying `commandp'). Existing,
953 The position of point, as an integer (*note Point::.). No I/O.
956 A directory name. The default is the current default directory of
957 the current buffer, `default-directory' (*note System
958 Environment::.). Existing, Completion, Default, Prompt.
961 The last mouse-button or misc-user event in the key sequence that
962 invoked the command. No I/O.
964 You can use `e' more than once in a single command's interactive
965 specification. If the key sequence that invoked the command has N
966 mouse-button or misc-user events, the Nth `e' provides the Nth
970 A file name of an existing file (*note File Names::.). The default
971 directory is `default-directory'. Existing, Completion, Default,
975 A file name. The file need not exist. Completion, Default,
979 A key sequence (*note Keymap Terminology::.). This keeps reading
980 events until a command (or undefined command) is found in the
981 current key maps. The key sequence argument is represented as a
982 vector of events. The cursor does not move into the echo area.
985 This kind of input is used by commands such as `describe-key' and
989 A key sequence, whose definition you intend to change. This works
990 like `k', except that it suppresses, for the last input event in
991 the key sequence, the conversions that are normally used (when
992 necessary) to convert an undefined key into a defined one.
995 The position of the mark, as an integer. No I/O.
998 A number read with the minibuffer. If the input is not a number,
999 the user is asked to try again. The prefix argument, if any, is
1003 The raw prefix argument. If the prefix argument is `nil', then
1004 read a number as with `n'. Requires a number. *Note Prefix
1005 Command Arguments::. Prompt.
1008 The numeric prefix argument. (Note that this `p' is lower case.)
1012 The raw prefix argument. (Note that this `P' is upper case.) No
1016 Point and the mark, as two numeric arguments, smallest first.
1017 This is the only code letter that specifies two successive
1018 arguments rather than one. No I/O.
1021 Arbitrary text, read in the minibuffer and returned as a string
1022 (*note Text from Minibuffer::.). Terminate the input with either
1023 <LFD> or <RET>. (`C-q' may be used to include either of these
1024 characters in the input.) Prompt.
1027 An interned symbol whose name is read in the minibuffer. Any
1028 whitespace character terminates the input. (Use `C-q' to include
1029 whitespace in the string.) Other characters that normally
1030 terminate a symbol (e.g., parentheses and brackets) do not do so
1034 A variable declared to be a user option (i.e., satisfying the
1035 predicate `user-variable-p'). *Note High-Level Completion::.
1036 Existing, Completion, Prompt.
1039 A Lisp object, specified with its read syntax, terminated with a
1040 <LFD> or <RET>. The object is not evaluated. *Note Object from
1041 Minibuffer::. Prompt.
1044 A Lisp form is read as with `x', but then evaluated so that its
1045 value becomes the argument for the command. Prompt.
1048 File: lispref.info, Node: Interactive Examples, Prev: Interactive Codes, Up: Defining Commands
1050 Examples of Using `interactive'
1051 -------------------------------
1053 Here are some examples of `interactive':
1055 (defun foo1 () ; `foo1' takes no arguments,
1056 (interactive) ; just moves forward two words.
1060 (defun foo2 (n) ; `foo2' takes one argument,
1061 (interactive "p") ; which is the numeric prefix.
1062 (forward-word (* 2 n)))
1065 (defun foo3 (n) ; `foo3' takes one argument,
1066 (interactive "nCount:") ; which is read with the Minibuffer.
1067 (forward-word (* 2 n)))
1070 (defun three-b (b1 b2 b3)
1071 "Select three existing buffers.
1072 Put them into three windows, selecting the last one."
1073 (interactive "bBuffer1:\nbBuffer2:\nbBuffer3:")
1074 (delete-other-windows)
1075 (split-window (selected-window) 8)
1076 (switch-to-buffer b1)
1078 (split-window (selected-window) 8)
1079 (switch-to-buffer b2)
1081 (switch-to-buffer b3))
1083 (three-b "*scratch*" "declarations.texi" "*mail*")
1087 File: lispref.info, Node: Interactive Call, Next: Command Loop Info, Prev: Defining Commands, Up: Command Loop
1092 After the command loop has translated a key sequence into a
1093 definition, it invokes that definition using the function
1094 `command-execute'. If the definition is a function that is a command,
1095 `command-execute' calls `call-interactively', which reads the arguments
1096 and calls the command. You can also call these functions yourself.
1098 - Function: commandp OBJECT
1099 Returns `t' if OBJECT is suitable for calling interactively; that
1100 is, if OBJECT is a command. Otherwise, returns `nil'.
1102 The interactively callable objects include strings and vectors
1103 (treated as keyboard macros), lambda expressions that contain a
1104 top-level call to `interactive', compiled-function objects made
1105 from such lambda expressions, autoload objects that are declared
1106 as interactive (non-`nil' fourth argument to `autoload'), and some
1107 of the primitive functions.
1109 A symbol is `commandp' if its function definition is `commandp'.
1111 Keys and keymaps are not commands. Rather, they are used to look
1112 up commands (*note Keymaps::.).
1114 See `documentation' in *Note Accessing Documentation::, for a
1115 realistic example of using `commandp'.
1117 - Function: call-interactively COMMAND &optional RECORD-FLAG
1118 This function calls the interactively callable function COMMAND,
1119 reading arguments according to its interactive calling
1120 specifications. An error is signaled if COMMAND is not a function
1121 or if it cannot be called interactively (i.e., is not a command).
1122 Note that keyboard macros (strings and vectors) are not accepted,
1123 even though they are considered commands, because they are not
1126 If RECORD-FLAG is the symbol `lambda', the interactive calling
1127 arguments for `command' are read and returned as a list, but the
1128 function is not called on them.
1130 If RECORD-FLAG is `t', then this command and its arguments are
1131 unconditionally added to the list `command-history'. Otherwise,
1132 the command is added only if it uses the minibuffer to read an
1133 argument. *Note Command History::.
1135 - Function: command-execute COMMAND &optional RECORD-FLAG
1136 This function executes COMMAND as an editing command. The
1137 argument COMMAND must satisfy the `commandp' predicate; i.e., it
1138 must be an interactively callable function or a keyboard macro.
1140 A string or vector as COMMAND is executed with
1141 `execute-kbd-macro'. A function is passed to
1142 `call-interactively', along with the optional RECORD-FLAG.
1144 A symbol is handled by using its function definition in its place.
1145 A symbol with an `autoload' definition counts as a command if it
1146 was declared to stand for an interactively callable function.
1147 Such a definition is handled by loading the specified library and
1148 then rechecking the definition of the symbol.
1150 - Command: execute-extended-command PREFIX-ARGUMENT
1151 This function reads a command name from the minibuffer using
1152 `completing-read' (*note Completion::.). Then it uses
1153 `command-execute' to call the specified command. Whatever that
1154 command returns becomes the value of `execute-extended-command'.
1156 If the command asks for a prefix argument, it receives the value
1157 PREFIX-ARGUMENT. If `execute-extended-command' is called
1158 interactively, the current raw prefix argument is used for
1159 PREFIX-ARGUMENT, and thus passed on to whatever command is run.
1161 `execute-extended-command' is the normal definition of `M-x', so
1162 it uses the string `M-x ' as a prompt. (It would be better to
1163 take the prompt from the events used to invoke
1164 `execute-extended-command', but that is painful to implement.) A
1165 description of the value of the prefix argument, if any, also
1166 becomes part of the prompt.
1168 (execute-extended-command 1)
1169 ---------- Buffer: Minibuffer ----------
1170 1 M-x forward-word RET
1171 ---------- Buffer: Minibuffer ----------
1174 - Function: interactive-p
1175 This function returns `t' if the containing function (the one that
1176 called `interactive-p') was called interactively, with the function
1177 `call-interactively'. (It makes no difference whether
1178 `call-interactively' was called from Lisp or directly from the
1179 editor command loop.) If the containing function was called by
1180 Lisp evaluation (or with `apply' or `funcall'), then it was not
1181 called interactively.
1183 The most common use of `interactive-p' is for deciding whether to
1184 print an informative message. As a special exception,
1185 `interactive-p' returns `nil' whenever a keyboard macro is being
1186 run. This is to suppress the informative messages and speed
1187 execution of the macro.
1193 (and (interactive-p)
1199 (setq foobar (list (foo) (interactive-p))))
1206 ;; This does not print anything.