@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2004
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003,
+@c 2004, 2005, 2006 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/commands
@node Command Loop, Keymaps, Minibuffers, Top
arguments. This leads quickly to an error if the command requires one
or more arguments.
-@item
-It may be a Lisp expression that is not a string; then it should be a
-form that is evaluated to get a list of arguments to pass to the
-command.
-@cindex argument evaluation form
-
-If this expression reads keyboard input (this includes using the
-minibuffer), keep in mind that the integer value of point or the mark
-before reading input may be incorrect after reading input. This is
-because the current buffer may be receiving subprocess output;
-if subprocess output arrives while the command is waiting for input,
-it could relocate point and the mark.
-
-Here's an example of what @emph{not} to do:
-
-@smallexample
-(interactive
- (list (region-beginning) (region-end)
- (read-string "Foo: " nil 'my-history)))
-@end smallexample
-
-@noindent
-Here's how to avoid the problem, by examining point and the mark only
-after reading the keyboard input:
-
-@smallexample
-(interactive
- (let ((string (read-string "Foo: " nil 'my-history)))
- (list (region-beginning) (region-end) string)))
-@end smallexample
-
@item
@cindex argument prompt
It may be a string; then its contents should consist of a code character
Actual reading of arguments is controlled by the rest of the prompt
string (starting with the first character that is not @samp{*} or
@samp{@@}).
+
+@item
+It may be a Lisp expression that is not a string; then it should be a
+form that is evaluated to get a list of arguments to pass to the
+command. Usually this form will call various functions to read input
+from the user, most often through the minibuffer (@pxref{Minibuffers})
+or directly from the keyboard (@pxref{Reading Input}).
+@cindex argument evaluation form
+
+Providing point or the mark as an argument value is also common, but
+if you do this @emph{and} read input (whether using the minibuffer or
+not), be sure to get the integer values of point or the mark after
+reading. The current buffer may be receiving subprocess output; if
+subprocess output arrives while the command is waiting for input, it
+could relocate point and the mark.
+
+Here's an example of what @emph{not} to do:
+
+@smallexample
+(interactive
+ (list (region-beginning) (region-end)
+ (read-string "Foo: " nil 'my-history)))
+@end smallexample
+
+@noindent
+Here's how to avoid the problem, by examining point and the mark after
+reading the keyboard input:
+
+@smallexample
+(interactive
+ (let ((string (read-string "Foo: " nil 'my-history)))
+ (list (region-beginning) (region-end) string)))
+@end smallexample
@end itemize
@cindex examining the @code{interactive} form
maps. The key sequence argument is represented as a string or vector.
The cursor does not move into the echo area. Prompt.
-If the key sequence is a down-event, the following up-event is discarded,
-but can be read via the @code{U} code character.
+If @samp{k} reads a key sequence that ends with a down-event, it also
+reads and discards the following up-event. You can get access to that
+up-event with the @samp{U} code character.
This kind of input is used by commands such as @code{describe-key} and
@code{global-set-key}.
parentheses and brackets) do not do so here. Prompt.
@item U
-A key sequence or @code{nil}. May be used after a @code{k} or @code{K}
-argument to get the up-event that was discarded in case the key
-sequence read for that argument was a down-event. No I/O.
+A key sequence or @code{nil}. Can be used after a @samp{k} or
+@samp{K} argument to get the up-event that was discarded (if any)
+after @samp{k} or @samp{K} read a down-event. If no up-event has been
+discarded, @samp{U} provides @code{nil} as the argument. No I/O.
@item v
A variable declared to be a user option (i.e., satisfying the
@item X
@cindex evaluated expression argument
-A Lisp form is read as with @kbd{x}, but then evaluated so that its
-value becomes the argument for the command. Prompt.
+A Lisp form's value. @samp{X} reads as @samp{x} does, then evaluates
+the form so that its value becomes the argument for the command.
+Prompt.
@item z
A coding system name (a symbol). If the user enters null input, the
@defun posn-area position
Return the window area recorded in @var{position}. It returns @code{nil}
when the event occurred in the text area of the window; otherwise, it
-is a symbol identifying the area in which the the event occurred.
+is a symbol identifying the area in which the event occurred.
@end defun
@defun posn-point position
events---characters, symbols, and lists. The elements of the string or
vector are the events in the key sequence.
+Reading a key sequence includes translating the events in various
+ways. @xref{Translating Input}.
+
The argument @var{prompt} is either a string to be displayed in the
echo area as a prompt, or @code{nil}, meaning not to display a prompt.
The argument @var{continue-echo}, if non-@code{nil}, means to echo
after another. It should be @code{nil} if the caller will read just
one key sequence.
-In the example below, the prompt @samp{?} is displayed in the echo area,
-and the user types @kbd{C-x C-f}.
+In the following example, Emacs displays the prompt @samp{?} in the
+echo area, and then the user types @kbd{C-x C-f}.
@example
(read-key-sequence "?")
and key sequences read from keyboard macros being executed.
@end defvar
-@defvar num-nonmacro-input-events
-This variable holds the total number of input events received so far
-from the terminal---not counting those generated by keyboard macros.
-@end defvar
-
@node Reading One Event
@subsection Reading One Event
@cindex reading a single event
gets a character. The arguments work as in @code{read-event}.
@end defun
+@defvar num-nonmacro-input-events
+This variable holds the total number of input events received so far
+from the terminal---not counting those generated by keyboard macros.
+@end defvar
+
@node Invoking the Input Method
@subsection Invoking the Input Method
Emacs version 18.
@end defvar
-@defmac while-no-input body...
-This construct runs the @var{body} forms and returns the value
-of the last one---but only if no input arrives. If any input
-arrives during the execution of the @var{body} forms, it aborts
-them (working much like a quit), and the @code{while-no-input}
-form returns @code{nil}.
+@defmac while-no-input body@dots{}
+This construct runs the @var{body} forms and returns the value of the
+last one---but only if no input arrives. If any input arrives during
+the execution of the @var{body} forms, it aborts them (working much
+like a quit). The @code{while-no-input} form returns @code{nil} if
+aborted by a real quit, and returns @code{t} if aborted by arrival of
+other input.
If a part of @var{body} binds @code{inhibit-quit} to non-@code{nil},
arrival of input during those parts won't cause an abort until
the end of that part.
+
+If you want to be able to distingish all possible values computed
+by @var{body} from both kinds of abort conditions, write the code
+like this:
+
+@example
+(while-no-input
+ (list
+ (progn . @var{body})))
+@end example
@end defmac
@defun discard-input
non-@code{nil}, then @code{quit-flag} has no special effect.
@end defvar
-@defmac with-local-quit forms@dots{}
-This macro executes @var{forms} in sequence, but allows quitting, at
+@defmac with-local-quit body@dots{}
+This macro executes @var{body} forms in sequence, but allows quitting, at
least locally, within @var{body} even if @code{inhibit-quit} was
non-@code{nil} outside this construct. It returns the value of the
-last form in @var{forms}, unless exited by quitting, in which case
+last form in @var{body}, unless exited by quitting, in which case
it returns @code{nil}.
If @code{inhibit-quit} is @code{nil} on entry to @code{with-local-quit},
-it only executes the @var{forms}, and setting @code{quit-flag} causes
+it only executes the @var{body}, and setting @code{quit-flag} causes
a normal quit. However, if @code{inhibit-quit} is non-@code{nil} so
that ordinary quitting is delayed, a non-@code{nil} @code{quit-flag}
triggers a special kind of local quit. This ends the execution of
-@var{forms} and exits the @code{with-local-quit} form with
+@var{body} and exits the @code{with-local-quit} body with
@code{quit-flag} still non-@code{nil}, so that another (ordinary) quit
will happen as soon as that is allowed. If @code{quit-flag} is
-already non-@code{nil} at the beginning of @var{forms}, the local quit
-happens immediately and they don't execute at all.
+already non-@code{nil} at the beginning of @var{body}, the local quit
+happens immediately and the body doesn't execute at all.
This macro is mainly useful in functions that can be called from
-timers, @code{pre-command-hook}, @code{post-command-hook} and other
-places where @code{inhibit-quit} is normally bound to @code{t}.
+timers, process filters, process sentinels, @code{pre-command-hook},
+@code{post-command-hook}, and other places where @code{inhibit-quit} is
+normally bound to @code{t}.
@end defmac
@deffn Command keyboard-quit
commands.
Normally, commands specify which representation to use for the prefix
-argument, either numeric or raw, in the @code{interactive} declaration.
+argument, either numeric or raw, in the @code{interactive} specification.
(@xref{Using Interactive}.) Alternatively, functions may look at the
value of the prefix argument directly in the variable
@code{current-prefix-arg}, but this is less clean.