1 This is Info file ../../info/lispref.info, produced by Makeinfo version
2 1.68 from the input file 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 with DIRECTORY, if that is inserted). In this
185 case, point goes at the beginning of INITIAL. The default for
186 INITIAL is `nil'--don't insert any file name. To see what INITIAL
187 does, 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 an exact match already, or `nil' if the string matches no
273 * `t' specifies `all-completions'. The completion function should
274 return a list of all possible completions of the specified string.
276 * `lambda' specifies a test for an exact match. The completion
277 function should return `t' if the specified string is an exact
278 match for some possibility; `nil' otherwise.
280 It would be consistent and clean for completion functions to allow
281 lambda expressions (lists that are functions) as well as function
282 symbols as COLLECTION, but this is impossible. Lists as completion
283 tables are already assigned another meaning--as alists. It would be
284 unreliable to fail to handle an alist normally because it is also a
285 possible function. So you must arrange for any function you wish to
286 use for completion to be encapsulated in a symbol.
288 Emacs uses programmed completion when completing file names. *Note
289 File Name Completion::.
292 File: lispref.info, Node: Yes-or-No Queries, Next: Multiple Queries, Prev: Completion, Up: Minibuffers
297 This section describes functions used to ask the user a yes-or-no
298 question. The function `y-or-n-p' can be answered with a single
299 character; it is useful for questions where an inadvertent wrong answer
300 will not have serious consequences. `yes-or-no-p' is suitable for more
301 momentous questions, since it requires three or four characters to
302 answer. Variations of these functions can be used to ask a yes-or-no
303 question using a dialog box, or optionally using one.
305 If either of these functions is called in a command that was invoked
306 using the mouse, then it uses a dialog box or pop-up menu to ask the
307 question. Otherwise, it uses keyboard input.
309 Strictly speaking, `yes-or-no-p' uses the minibuffer and `y-or-n-p'
310 does not; but it seems best to describe them together.
312 - Function: y-or-n-p PROMPT
313 This function asks the user a question, expecting input in the echo
314 area. It returns `t' if the user types `y', `nil' if the user
315 types `n'. This function also accepts <SPC> to mean yes and <DEL>
316 to mean no. It accepts `C-]' to mean "quit", like `C-g', because
317 the question might look like a minibuffer and for that reason the
318 user might try to use `C-]' to get out. The answer is a single
319 character, with no <RET> needed to terminate it. Upper and lower
322 "Asking the question" means printing PROMPT in the echo area,
323 followed by the string `(y or n) '. If the input is not one of
324 the expected answers (`y', `n', `<SPC>', `<DEL>', or something
325 that quits), the function responds `Please answer y or n.', and
328 This function does not actually use the minibuffer, since it does
329 not allow editing of the answer. It actually uses the echo area
330 (*note The Echo Area::.), which uses the same screen space as the
331 minibuffer. The cursor moves to the echo area while the question
334 The answers and their meanings, even `y' and `n', are not
335 hardwired. The keymap `query-replace-map' specifies them. *Note
336 Search and Replace::.
338 In the following example, the user first types `q', which is
339 invalid. At the next prompt the user types `y'.
341 (y-or-n-p "Do you need a lift? ")
343 ;; After evaluation of the preceding expression,
344 ;; the following prompt appears in the echo area:
346 ---------- Echo area ----------
347 Do you need a lift? (y or n)
348 ---------- Echo area ----------
350 ;; If the user then types `q', the following appears:
351 ---------- Echo area ----------
352 Please answer y or n. Do you need a lift? (y or n)
353 ---------- Echo area ----------
355 ;; When the user types a valid answer,
356 ;; it is displayed after the question:
357 ---------- Echo area ----------
358 Do you need a lift? (y or n) y
359 ---------- Echo area ----------
361 We show successive lines of echo area messages, but only one
362 actually appears on the screen at a time.
364 - Function: yes-or-no-p PROMPT
365 This function asks the user a question, expecting input in the
366 minibuffer. It returns `t' if the user enters `yes', `nil' if the
367 user types `no'. The user must type <RET> to finalize the
368 response. Upper and lower case are equivalent.
370 `yes-or-no-p' starts by displaying PROMPT in the echo area,
371 followed by `(yes or no) '. The user must type one of the
372 expected responses; otherwise, the function responds `Please answer
373 yes or no.', waits about two seconds and repeats the request.
375 `yes-or-no-p' requires more work from the user than `y-or-n-p' and
376 is appropriate for more crucial decisions.
380 (yes-or-no-p "Do you really want to remove everything? ")
382 ;; After evaluation of the preceding expression,
383 ;; the following prompt appears,
384 ;; with an empty minibuffer:
386 ---------- Buffer: minibuffer ----------
387 Do you really want to remove everything? (yes or no)
388 ---------- Buffer: minibuffer ----------
390 If the user first types `y <RET>', which is invalid because this
391 function demands the entire word `yes', it responds by displaying
392 these prompts, with a brief pause between them:
394 ---------- Buffer: minibuffer ----------
395 Please answer yes or no.
396 Do you really want to remove everything? (yes or no)
397 ---------- Buffer: minibuffer ----------
399 - Function: yes-or-no-p-dialog-box PROMPT
400 This function asks the user a "y or n" question with a popup dialog
401 box. It returns `t' if the answer is "yes". PROMPT is the string
402 to display to ask the question.
404 The following functions ask a question either in the minibuffer or a
405 dialog box, depending on whether the last user event (which presumably
406 invoked this command) was a keyboard or mouse event. When XEmacs is
407 running on a window system, the functions `y-or-n-p' and `yes-or-no-p'
408 are replaced with the following functions, so that menu items bring up
409 dialog boxes instead of minibuffer questions.
411 - Function: y-or-n-p-maybe-dialog-box PROMPT
412 This function asks user a "y or n" question, using either a dialog
413 box or the minibuffer, as appropriate.
415 - Function: yes-or-no-p-maybe-dialog-box PROMPT
416 This function asks user a "yes or no" question, using either a
417 dialog box or the minibuffer, as appropriate.
420 File: lispref.info, Node: Multiple Queries, Next: Minibuffer Misc, Prev: Yes-or-No Queries, Up: Minibuffers
422 Asking Multiple Y-or-N Questions
423 ================================
425 When you have a series of similar questions to ask, such as "Do you
426 want to save this buffer" for each buffer in turn, you should use
427 `map-y-or-n-p' to ask the collection of questions, rather than asking
428 each question individually. This gives the user certain convenient
429 facilities such as the ability to answer the whole series at once.
431 - Function: map-y-or-n-p PROMPTER ACTOR LIST &optional HELP
433 This function, new in Emacs 19, asks the user a series of
434 questions, reading a single-character answer in the echo area for
437 The value of LIST specifies the objects to ask questions about.
438 It should be either a list of objects or a generator function. If
439 it is a function, it should expect no arguments, and should return
440 either the next object to ask about, or `nil' meaning stop asking
443 The argument PROMPTER specifies how to ask each question. If
444 PROMPTER is a string, the question text is computed like this:
446 (format PROMPTER OBJECT)
448 where OBJECT is the next object to ask about (as obtained from
451 If not a string, PROMPTER should be a function of one argument
452 (the next object to ask about) and should return the question
453 text. If the value is a string, that is the question to ask the
454 user. The function can also return `t' meaning do act on this
455 object (and don't ask the user), or `nil' meaning ignore this
456 object (and don't ask the user).
458 The argument ACTOR says how to act on the answers that the user
459 gives. It should be a function of one argument, and it is called
460 with each object that the user says yes for. Its argument is
461 always an object obtained from LIST.
463 If the argument HELP is given, it should be a list of this form:
465 (SINGULAR PLURAL ACTION)
467 where SINGULAR is a string containing a singular noun that
468 describes the objects conceptually being acted on, PLURAL is the
469 corresponding plural noun, and ACTION is a transitive verb
470 describing what ACTOR does.
472 If you don't specify HELP, the default is `("object" "objects"
475 Each time a question is asked, the user may enter `y', `Y', or
476 <SPC> to act on that object; `n', `N', or <DEL> to skip that
477 object; `!' to act on all following objects; <ESC> or `q' to exit
478 (skip all following objects); `.' (period) to act on the current
479 object and then exit; or `C-h' to get help. These are the same
480 answers that `query-replace' accepts. The keymap
481 `query-replace-map' defines their meaning for `map-y-or-n-p' as
482 well as for `query-replace'; see *Note Search and Replace::.
484 You can use ACTION-ALIST to specify additional possible answers
485 and what they mean. It is an alist of elements of the form `(CHAR
486 FUNCTION HELP)', each of which defines one additional answer. In
487 this element, CHAR is a character (the answer); FUNCTION is a
488 function of one argument (an object from LIST); HELP is a string.
490 When the user responds with CHAR, `map-y-or-n-p' calls FUNCTION.
491 If it returns non-`nil', the object is considered "acted upon",
492 and `map-y-or-n-p' advances to the next object in LIST. If it
493 returns `nil', the prompt is repeated for the same object.
495 If `map-y-or-n-p' is called in a command that was invoked using the
496 mouse--more precisely, if `last-nonmenu-event' (*note Command Loop
497 Info::.) is either `nil' or a list--then it uses a dialog box or
498 pop-up menu to ask the question. In this case, it does not use
499 keyboard input or the echo area. You can force use of the mouse
500 or use of keyboard input by binding `last-nonmenu-event' to a
501 suitable value around the call.
503 The return value of `map-y-or-n-p' is the number of objects acted
507 File: lispref.info, Node: Minibuffer Misc, Prev: Multiple Queries, Up: Minibuffers
509 Minibuffer Miscellany
510 =====================
512 This section describes some basic functions and variables related to
515 - Command: exit-minibuffer
516 This command exits the active minibuffer. It is normally bound to
517 keys in minibuffer local keymaps.
519 - Command: self-insert-and-exit
520 This command exits the active minibuffer after inserting the last
521 character typed on the keyboard (found in `last-command-char';
522 *note Command Loop Info::.).
524 - Command: previous-history-element N
525 This command replaces the minibuffer contents with the value of the
526 Nth previous (older) history element.
528 - Command: next-history-element N
529 This command replaces the minibuffer contents with the value of the
530 Nth more recent history element.
532 - Command: previous-matching-history-element PATTERN
533 This command replaces the minibuffer contents with the value of the
534 previous (older) history element that matches PATTERN (a regular
537 - Command: next-matching-history-element PATTERN
538 This command replaces the minibuffer contents with the value of
539 the next (newer) history element that matches PATTERN (a regular
542 - Function: minibuffer-prompt
543 This function returns the prompt string of the currently active
544 minibuffer. If no minibuffer is active, it returns `nil'.
546 - Function: minibuffer-prompt-width
547 This function returns the display width of the prompt string of the
548 currently active minibuffer. If no minibuffer is active, it
551 - Variable: minibuffer-setup-hook
552 This is a normal hook that is run whenever the minibuffer is
553 entered. *Note Hooks::.
555 - Variable: minibuffer-exit-hook
556 This is a normal hook that is run whenever the minibuffer is
557 exited. *Note Hooks::.
559 - Variable: minibuffer-help-form
560 The current value of this variable is used to rebind `help-form'
561 locally inside the minibuffer (*note Help Functions::.).
563 - Function: active-minibuffer-window
564 This function returns the currently active minibuffer window, or
565 `nil' if none is currently active.
567 - Function: minibuffer-window &optional FRAME
568 This function returns the minibuffer window used for frame FRAME.
569 If FRAME is `nil', that stands for the current frame. Note that
570 the minibuffer window used by a frame need not be part of that
571 frame--a frame that has no minibuffer of its own necessarily uses
572 some other frame's minibuffer window.
574 - Function: window-minibuffer-p WINDOW
575 This function returns non-`nil' if WINDOW is a minibuffer window.
577 It is not correct to determine whether a given window is a
578 minibuffer by comparing it with the result of `(minibuffer-window)',
579 because there can be more than one minibuffer window if there is more
582 - Function: minibuffer-window-active-p WINDOW
583 This function returns non-`nil' if WINDOW, assumed to be a
584 minibuffer window, is currently active.
586 - Variable: minibuffer-scroll-window
587 If the value of this variable is non-`nil', it should be a window
588 object. When the function `scroll-other-window' is called in the
589 minibuffer, it scrolls this window.
591 Finally, some functions and variables deal with recursive minibuffers
592 (*note Recursive Editing::.):
594 - Function: minibuffer-depth
595 This function returns the current depth of activations of the
596 minibuffer, a nonnegative integer. If no minibuffers are active,
599 - User Option: enable-recursive-minibuffers
600 If this variable is non-`nil', you can invoke commands (such as
601 `find-file') that use minibuffers even while in the minibuffer
602 window. Such invocation produces a recursive editing level for a
603 new minibuffer. The outer-level minibuffer is invisible while you
604 are editing the inner one.
606 This variable only affects invoking the minibuffer while the
607 minibuffer window is selected. If you switch windows while in the
608 minibuffer, you can always invoke minibuffer commands while some
609 other window is selected.
611 In FSF Emacs 19, if a command name has a property
612 `enable-recursive-minibuffers' that is non-`nil', then the command can
613 use the minibuffer to read arguments even if it is invoked from the
614 minibuffer. The minibuffer command `next-matching-history-element'
615 (normally `M-s' in the minibuffer) uses this feature.
617 This is not implemented in XEmacs because it is a kludge. If you
618 want to explicitly set the value of `enable-recursive-minibuffers' in
619 this fashion, just use an evaluated interactive spec and bind
620 `enable-recursive-minibuffers' while reading from the minibuffer. See
621 the definition of `next-matching-history-element' in
622 `lisp/prim/minibuf.el'.
625 File: lispref.info, Node: Command Loop, Next: Keymaps, Prev: Minibuffers, Up: Top
630 When you run XEmacs, it enters the "editor command loop" almost
631 immediately. This loop reads events, executes their definitions, and
632 displays the results. In this chapter, we describe how these things
633 are done, and the subroutines that allow Lisp programs to do them.
637 * Command Overview:: How the command loop reads commands.
638 * Defining Commands:: Specifying how a function should read arguments.
639 * Interactive Call:: Calling a command, so that it will read arguments.
640 * Command Loop Info:: Variables set by the command loop for you to examine.
641 * Events:: What input looks like when you read it.
642 * Reading Input:: How to read input events from the keyboard or mouse.
643 * Waiting:: Waiting for user input or elapsed time.
644 * Quitting:: How `C-g' works. How to catch or defer quitting.
645 * Prefix Command Arguments:: How the commands to set prefix args work.
646 * Recursive Editing:: Entering a recursive edit,
647 and why you usually shouldn't.
648 * Disabling Commands:: How the command loop handles disabled commands.
649 * Command History:: How the command history is set up, and how accessed.
650 * Keyboard Macros:: How keyboard macros are implemented.
653 File: lispref.info, Node: Command Overview, Next: Defining Commands, Up: Command Loop
655 Command Loop Overview
656 =====================
658 The command loop in XEmacs is a standard event loop, reading events
659 one at a time with `next-event' and handling them with
660 `dispatch-event'. An event is typically a single user action, such as
661 a keypress, mouse movement, or menu selection; but they can also be
662 notifications from the window system, informing XEmacs that (for
663 example) part of its window was just uncovered and needs to be redrawn.
664 *Note Events::. Pending events are held in a first-in, first-out list
665 called the "event queue": events are read from the head of the list,
666 and newly arriving events are added to the tail. In this way, events
667 are always processed in the order in which they arrive.
669 `dispatch-event' does most of the work of handling user actions.
670 The first thing it must do is put the events together into a key
671 sequence, which is a sequence of events that translates into a command.
672 It does this by consulting the active keymaps, which specify what the
673 valid key sequences are and how to translate them into commands. *Note
674 Key Lookup::, for information on how this is done. The result of the
675 translation should be a keyboard macro or an interactively callable
676 function. If the key is `M-x', then it reads the name of another
677 command, which it then calls. This is done by the command
678 `execute-extended-command' (*note Interactive Call::.).
680 To execute a command requires first reading the arguments for it.
681 This is done by calling `command-execute' (*note Interactive Call::.).
682 For commands written in Lisp, the `interactive' specification says how
683 to read the arguments. This may use the prefix argument (*note Prefix
684 Command Arguments::.) or may read with prompting in the minibuffer
685 (*note Minibuffers::.). For example, the command `find-file' has an
686 `interactive' specification which says to read a file name using the
687 minibuffer. The command's function body does not use the minibuffer;
688 if you call this command from Lisp code as a function, you must supply
689 the file name string as an ordinary Lisp function argument.
691 If the command is a string or vector (i.e., a keyboard macro) then
692 `execute-kbd-macro' is used to execute it. You can call this function
693 yourself (*note Keyboard Macros::.).
695 To terminate the execution of a running command, type `C-g'. This
696 character causes "quitting" (*note Quitting::.).
698 - Variable: pre-command-hook
699 The editor command loop runs this normal hook before each command.
700 At that time, `this-command' contains the command that is about to
701 run, and `last-command' describes the previous command. *Note
704 - Variable: post-command-hook
705 The editor command loop runs this normal hook after each command.
706 (In FSF Emacs, it is also run when the command loop is entered, or
707 reentered after an error or quit.) At that time, `this-command'
708 describes the command that just ran, and `last-command' describes
709 the command before that. *Note Hooks::.
711 Quitting is suppressed while running `pre-command-hook' and
712 `post-command-hook'. If an error happens while executing one of these
713 hooks, it terminates execution of the hook, but that is all it does.
716 File: lispref.info, Node: Defining Commands, Next: Interactive Call, Prev: Command Overview, Up: Command Loop
721 A Lisp function becomes a command when its body contains, at top
722 level, a form that calls the special form `interactive'. This form
723 does nothing when actually executed, but its presence serves as a flag
724 to indicate that interactive calling is permitted. Its argument
725 controls the reading of arguments for an interactive call.
729 * Using Interactive:: General rules for `interactive'.
730 * Interactive Codes:: The standard letter-codes for reading arguments
732 * Interactive Examples:: Examples of how to read interactive arguments.
735 File: lispref.info, Node: Using Interactive, Next: Interactive Codes, Up: Defining Commands
740 This section describes how to write the `interactive' form that
741 makes a Lisp function an interactively-callable command.
743 - Special Form: interactive ARG-DESCRIPTOR
744 This special form declares that the function in which it appears
745 is a command, and that it may therefore be called interactively
746 (via `M-x' or by entering a key sequence bound to it). The
747 argument ARG-DESCRIPTOR declares how to compute the arguments to
748 the command when the command is called interactively.
750 A command may be called from Lisp programs like any other
751 function, but then the caller supplies the arguments and
752 ARG-DESCRIPTOR has no effect.
754 The `interactive' form has its effect because the command loop
755 (actually, its subroutine `call-interactively') scans through the
756 function definition looking for it, before calling the function.
757 Once the function is called, all its body forms including the
758 `interactive' form are executed, but at this time `interactive'
759 simply returns `nil' without even evaluating its argument.
761 There are three possibilities for the argument ARG-DESCRIPTOR:
763 * It may be omitted or `nil'; then the command is called with no
764 arguments. This leads quickly to an error if the command requires
765 one or more arguments.
767 * It may be a Lisp expression that is not a string; then it should
768 be a form that is evaluated to get a list of arguments to pass to
771 If this expression reads keyboard input (this includes using the
772 minibuffer), keep in mind that the integer value of point or the
773 mark before reading input may be incorrect after reading input.
774 This is because the current buffer may be receiving subprocess
775 output; if subprocess output arrives while the command is waiting
776 for input, it could relocate point and the mark.
778 Here's an example of what *not* to do:
781 (list (region-beginning) (region-end)
782 (read-string "Foo: " nil 'my-history)))
784 Here's how to avoid the problem, by examining point and the mark
785 only after reading the keyboard input:
788 (let ((string (read-string "Foo: " nil 'my-history)))
789 (list (region-beginning) (region-end) string)))
791 * It may be a string; then its contents should consist of a code
792 character followed by a prompt (which some code characters use and
793 some ignore). The prompt ends either with the end of the string
794 or with a newline. Here is a simple example:
796 (interactive "bFrobnicate buffer: ")
798 The code letter `b' says to read the name of an existing buffer,
799 with completion. The buffer name is the sole argument passed to
800 the command. The rest of the string is a prompt.
802 If there is a newline character in the string, it terminates the
803 prompt. If the string does not end there, then the rest of the
804 string should contain another code character and prompt,
805 specifying another argument. You can specify any number of
806 arguments in this way.
808 The prompt string can use `%' to include previous argument values
809 (starting with the first argument) in the prompt. This is done
810 using `format' (*note Formatting Strings::.). For example, here
811 is how you could read the name of an existing buffer followed by a
812 new name to give to that buffer:
814 (interactive "bBuffer to rename: \nsRename buffer %s to: ")
816 If the first character in the string is `*', then an error is
817 signaled if the buffer is read-only.
819 If the first character in the string is `@', and if the key
820 sequence used to invoke the command includes any mouse events, then
821 the window associated with the first of those events is selected
822 before the command is run.
824 If the first character in the string is `_', then this command will
825 not cause the region to be deactivated when it completes; that is,
826 `zmacs-region-stays' will be set to `t' when the command exits
829 You can use `*', `@', and `_' together; the order does not matter.
830 Actual reading of arguments is controlled by the rest of the
831 prompt string (starting with the first character that is not `*',
834 - Function: function-interactive FUNCTION
835 This function retrieves the interactive specification of FUNCTION,
836 which may be any funcallable object. The specification will be
837 returned as the list of the symbol `interactive' and the specs. If
838 FUNCTION is not interactive, `nil' will be returned.
841 File: lispref.info, Node: Interactive Codes, Next: Interactive Examples, Prev: Using Interactive, Up: Defining Commands
843 Code Characters for `interactive'
844 ---------------------------------
846 The code character descriptions below contain a number of key words,
847 defined here as follows:
850 Provide completion. <TAB>, <SPC>, and <RET> perform name
851 completion because the argument is read using `completing-read'
852 (*note Completion::.). `?' displays a list of possible
856 Require the name of an existing object. An invalid name is not
857 accepted; the commands to exit the minibuffer do not exit if the
858 current input is not valid.
861 A default value of some sort is used if the user enters no text in
862 the minibuffer. The default depends on the code character.
865 This code letter computes an argument without reading any input.
866 Therefore, it does not use a prompt string, and any prompt string
867 you supply is ignored.
869 Even though the code letter doesn't use a prompt string, you must
870 follow it with a newline if it is not the last code character in
874 A prompt immediately follows the code character. The prompt ends
875 either with the end of the string or with a newline.
878 This code character is meaningful only at the beginning of the
879 interactive string, and it does not look for a prompt or a newline.
880 It is a single, isolated character.
882 Here are the code character descriptions for use with `interactive':
885 Signal an error if the current buffer is read-only. Special.
888 Select the window mentioned in the first mouse event in the key
889 sequence that invoked this command. Special.
892 Do not cause the region to be deactivated when this command
896 A function name (i.e., a symbol satisfying `fboundp'). Existing,
900 The name of an existing buffer. By default, uses the name of the
901 current buffer (*note Buffers::.). Existing, Completion, Default,
905 A buffer name. The buffer need not exist. By default, uses the
906 name of a recently used buffer other than the current buffer.
907 Completion, Default, Prompt.
910 A character. The cursor does not move into the echo area. Prompt.
913 A command name (i.e., a symbol satisfying `commandp'). Existing,
917 The position of point, as an integer (*note Point::.). No I/O.
920 A directory name. The default is the current default directory of
921 the current buffer, `default-directory' (*note System
922 Environment::.). Existing, Completion, Default, Prompt.
925 The last mouse-button or misc-user event in the key sequence that
926 invoked the command. No I/O.
928 You can use `e' more than once in a single command's interactive
929 specification. If the key sequence that invoked the command has N
930 mouse-button or misc-user events, the Nth `e' provides the Nth
934 A file name of an existing file (*note File Names::.). The default
935 directory is `default-directory'. Existing, Completion, Default,
939 A file name. The file need not exist. Completion, Default,
943 A key sequence (*note Keymap Terminology::.). This keeps reading
944 events until a command (or undefined command) is found in the
945 current key maps. The key sequence argument is represented as a
946 vector of events. The cursor does not move into the echo area.
949 This kind of input is used by commands such as `describe-key' and
953 A key sequence, whose definition you intend to change. This works
954 like `k', except that it suppresses, for the last input event in
955 the key sequence, the conversions that are normally used (when
956 necessary) to convert an undefined key into a defined one.
959 The position of the mark, as an integer. No I/O.
962 A number read with the minibuffer. If the input is not a number,
963 the user is asked to try again. The prefix argument, if any, is
967 The raw prefix argument. If the prefix argument is `nil', then
968 read a number as with `n'. Requires a number. *Note Prefix
969 Command Arguments::. Prompt.
972 The numeric prefix argument. (Note that this `p' is lower case.)
976 The raw prefix argument. (Note that this `P' is upper case.) No
980 Point and the mark, as two numeric arguments, smallest first.
981 This is the only code letter that specifies two successive
982 arguments rather than one. No I/O.
985 Arbitrary text, read in the minibuffer and returned as a string
986 (*note Text from Minibuffer::.). Terminate the input with either
987 <LFD> or <RET>. (`C-q' may be used to include either of these
988 characters in the input.) Prompt.
991 An interned symbol whose name is read in the minibuffer. Any
992 whitespace character terminates the input. (Use `C-q' to include
993 whitespace in the string.) Other characters that normally
994 terminate a symbol (e.g., parentheses and brackets) do not do so
998 A variable declared to be a user option (i.e., satisfying the
999 predicate `user-variable-p'). *Note High-Level Completion::.
1000 Existing, Completion, Prompt.
1003 A Lisp object, specified with its read syntax, terminated with a
1004 <LFD> or <RET>. The object is not evaluated. *Note Object from
1005 Minibuffer::. Prompt.
1008 A Lisp form is read as with `x', but then evaluated so that its
1009 value becomes the argument for the command. Prompt.
1012 File: lispref.info, Node: Interactive Examples, Prev: Interactive Codes, Up: Defining Commands
1014 Examples of Using `interactive'
1015 -------------------------------
1017 Here are some examples of `interactive':
1019 (defun foo1 () ; `foo1' takes no arguments,
1020 (interactive) ; just moves forward two words.
1024 (defun foo2 (n) ; `foo2' takes one argument,
1025 (interactive "p") ; which is the numeric prefix.
1026 (forward-word (* 2 n)))
1029 (defun foo3 (n) ; `foo3' takes one argument,
1030 (interactive "nCount:") ; which is read with the Minibuffer.
1031 (forward-word (* 2 n)))
1034 (defun three-b (b1 b2 b3)
1035 "Select three existing buffers.
1036 Put them into three windows, selecting the last one."
1037 (interactive "bBuffer1:\nbBuffer2:\nbBuffer3:")
1038 (delete-other-windows)
1039 (split-window (selected-window) 8)
1040 (switch-to-buffer b1)
1042 (split-window (selected-window) 8)
1043 (switch-to-buffer b2)
1045 (switch-to-buffer b3))
1047 (three-b "*scratch*" "declarations.texi" "*mail*")
1051 File: lispref.info, Node: Interactive Call, Next: Command Loop Info, Prev: Defining Commands, Up: Command Loop
1056 After the command loop has translated a key sequence into a
1057 definition, it invokes that definition using the function
1058 `command-execute'. If the definition is a function that is a command,
1059 `command-execute' calls `call-interactively', which reads the arguments
1060 and calls the command. You can also call these functions yourself.
1062 - Function: commandp OBJECT
1063 Returns `t' if OBJECT is suitable for calling interactively; that
1064 is, if OBJECT is a command. Otherwise, returns `nil'.
1066 The interactively callable objects include strings and vectors
1067 (treated as keyboard macros), lambda expressions that contain a
1068 top-level call to `interactive', compiled-function objects made
1069 from such lambda expressions, autoload objects that are declared
1070 as interactive (non-`nil' fourth argument to `autoload'), and some
1071 of the primitive functions.
1073 A symbol is `commandp' if its function definition is `commandp'.
1075 Keys and keymaps are not commands. Rather, they are used to look
1076 up commands (*note Keymaps::.).
1078 See `documentation' in *Note Accessing Documentation::, for a
1079 realistic example of using `commandp'.
1081 - Function: call-interactively COMMAND &optional RECORD-FLAG
1082 This function calls the interactively callable function COMMAND,
1083 reading arguments according to its interactive calling
1084 specifications. An error is signaled if COMMAND is not a function
1085 or if it cannot be called interactively (i.e., is not a command).
1086 Note that keyboard macros (strings and vectors) are not accepted,
1087 even though they are considered commands, because they are not
1090 If RECORD-FLAG is the symbol `lambda', the interactive calling
1091 arguments for `command' are read and returned as a list, but the
1092 function is not called on them.
1094 If RECORD-FLAG is `t', then this command and its arguments are
1095 unconditionally added to the list `command-history'. Otherwise,
1096 the command is added only if it uses the minibuffer to read an
1097 argument. *Note Command History::.
1099 - Function: command-execute COMMAND &optional RECORD-FLAG
1100 This function executes COMMAND as an editing command. The
1101 argument COMMAND must satisfy the `commandp' predicate; i.e., it
1102 must be an interactively callable function or a keyboard macro.
1104 A string or vector as COMMAND is executed with
1105 `execute-kbd-macro'. A function is passed to
1106 `call-interactively', along with the optional RECORD-FLAG.
1108 A symbol is handled by using its function definition in its place.
1109 A symbol with an `autoload' definition counts as a command if it
1110 was declared to stand for an interactively callable function.
1111 Such a definition is handled by loading the specified library and
1112 then rechecking the definition of the symbol.
1114 - Command: execute-extended-command PREFIX-ARGUMENT
1115 This function reads a command name from the minibuffer using
1116 `completing-read' (*note Completion::.). Then it uses
1117 `command-execute' to call the specified command. Whatever that
1118 command returns becomes the value of `execute-extended-command'.
1120 If the command asks for a prefix argument, it receives the value
1121 PREFIX-ARGUMENT. If `execute-extended-command' is called
1122 interactively, the current raw prefix argument is used for
1123 PREFIX-ARGUMENT, and thus passed on to whatever command is run.
1125 `execute-extended-command' is the normal definition of `M-x', so
1126 it uses the string `M-x ' as a prompt. (It would be better to
1127 take the prompt from the events used to invoke
1128 `execute-extended-command', but that is painful to implement.) A
1129 description of the value of the prefix argument, if any, also
1130 becomes part of the prompt.
1132 (execute-extended-command 1)
1133 ---------- Buffer: Minibuffer ----------
1134 1 M-x forward-word RET
1135 ---------- Buffer: Minibuffer ----------
1138 - Function: interactive-p
1139 This function returns `t' if the containing function (the one that
1140 called `interactive-p') was called interactively, with the function
1141 `call-interactively'. (It makes no difference whether
1142 `call-interactively' was called from Lisp or directly from the
1143 editor command loop.) If the containing function was called by
1144 Lisp evaluation (or with `apply' or `funcall'), then it was not
1145 called interactively.
1147 The most common use of `interactive-p' is for deciding whether to
1148 print an informative message. As a special exception,
1149 `interactive-p' returns `nil' whenever a keyboard macro is being
1150 run. This is to suppress the informative messages and speed
1151 execution of the macro.
1157 (and (interactive-p)
1163 (setq foobar (list (foo) (interactive-p))))
1170 ;; This does not print anything.