@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2014 Free Software
+@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Command Loop
@chapter Command Loop
Lisp code, you must supply the file name string as an ordinary Lisp
function argument.
- If the command is a keyboard macro (i.e.@: a string or vector),
+ If the command is a keyboard macro (i.e., a string or vector),
Emacs executes it using @code{execute-kbd-macro} (@pxref{Keyboard
Macros}).
The special form @code{interactive} turns a Lisp function into a
command. The @code{interactive} form must be located at top-level in
-the function body (usually as the first form in the body), or in the
-@code{interactive-form} property of the function symbol. When the
-@code{interactive} form is located in the function body, it does
-nothing when actually executed. Its presence serves as a flag, which
-tells the Emacs command loop that the function can be called
-interactively. The argument of the @code{interactive} form controls
-the reading of arguments for an interactive call.
+the function body, usually as the first form in the body; this applies
+to both lambda expressions (@pxref{Lambda Expressions}) and
+@code{defun} forms (@pxref{Defining Functions}). This form does
+nothing during the actual execution of the function; its presence
+serves as a flag, telling the Emacs command loop that the function can
+be called interactively. The argument of the @code{interactive} form
+specifies how the arguments for an interactive call should be read.
+
+@cindex @code{interactive-form} property
+ Alternatively, an @code{interactive} form may be specified in a
+function symbol's @code{interactive-form} property. A non-@code{nil}
+value for this property takes precedence over any @code{interactive}
+form in the function body itself. This feature is seldom used.
+
+@cindex @code{interactive-only} property
+ Sometimes, a function is only intended to be called interactively,
+never directly from Lisp. In that case, give the function a
+non-@code{nil} @code{interactive-only} property. This causes the
+byte compiler to warn if the command is called from Lisp. The value
+of the property can be: a string, which the byte-compiler will
+use directly in its warning (it should end with a period,
+and not start with a capital, e.g. ``use @dots{} instead.''); @code{t};
+any other symbol, which should be an alternative function to use in
+Lisp code.
@menu
* Using Interactive:: General rules for @code{interactive}.
* Interactive Codes:: The standard letter-codes for reading arguments
in various ways.
* Interactive Examples:: Examples of how to read interactive arguments.
+* Generic Commands:: Select among command alternatives.
@end menu
@node Using Interactive
then the caller supplies the arguments and @var{arg-descriptor} has no
effect.
-@cindex @code{interactive-form}, function property
+@cindex @code{interactive-form}, symbol property
The @code{interactive} form must be located at top-level in the
function body, or in the function symbol's @code{interactive-form}
-property (@pxref{Symbol Plists}). It has its effect because the
+property (@pxref{Symbol Properties}). It has its effect because the
command loop looks for it before calling the function
(@pxref{Interactive Call}). Once the function is called, all its body
forms are executed; at this time, if the @code{interactive} form
these characters in the input.) Prompt.
@item S
-An interned symbol whose name is read in the minibuffer. Any whitespace
-character terminates the input. (Use @kbd{C-q} to include whitespace in
-the string.) Other characters that normally terminate a symbol (e.g.,
-parentheses and brackets) do not do so here. Prompt.
+An interned symbol whose name is read in the minibuffer. Terminate
+the input with either @kbd{C-j} or @key{RET}. Other characters that
+normally terminate a symbol (e.g., whitespace, parentheses and
+brackets) do not do so here. Prompt.
@item U
A key sequence or @code{nil}. Can be used after a @samp{k} or
@end group
@end example
+@node Generic Commands
+@subsection Select among Command Alternatives
+@cindex generic commands
+@cindex alternatives, defining
+
+The macro @code{define-alternatives} can be used to define
+@dfn{generic commands}. Generic commands are interactive functions
+whose implementation can be selected among several alternatives, as a
+matter of user preference.
+
+@defmac define-alternatives command &rest customizations
+Define the new command `COMMAND'.
+
+The argument `COMMAND' should be a symbol.
+
+When a user runs @kbd{M-x COMMAND @key{RET}} for the first time, Emacs
+will prompt for which alternative to use and record the selected
+command as a custom variable.
+
+Running @kbd{C-u M-x COMMAND @key{RET}} prompts again for an
+alternative and overwrites the previous choice.
+
+The variable @code{COMMAND-alternatives} contains an alist
+(@pxref{Association Lists}) with alternative implementations of
+`COMMAND'. @code{define-alternatives} does not have any effect until
+this variable is set.
+
+If @var{customizations} is non-@var{nil}, it should be composed of
+alternating @code{defcustom} keywords and values to add to the
+declaration of @code{COMMAND-alternatives} (typically :group and
+:version).
+@end defmac
+
@node Interactive Call
@section Interactive Call
@cindex interactive call
@node Accessing Mouse
@subsection Accessing Mouse Events
@cindex mouse events, data in
+@cindex keyboard events, data in
This section describes convenient functions for accessing the data in
-a mouse button or motion event.
+a mouse button or motion event. Keyboard event data can be accessed
+using the same functions, but data elements that aren't applicable to
+keyboard events are zero or @code{nil}.
The following two functions return a mouse position list
(@pxref{Click Events}), specifying the position of a mouse event.
@code{read-char}, and @code{read-char-exclusive}.
@defun read-event &optional prompt inherit-input-method seconds
-This function reads and returns the next event of command input, waiting
-if necessary until an event is available. Events can come directly from
-the user or from a keyboard macro.
+This function reads and returns the next event of command input,
+waiting if necessary until an event is available.
+
+The returned event may come directly from the user, or from a keyboard
+macro. It is not decoded by the keyboard's input coding system
+(@pxref{Terminal I/O Encoding}).
If the optional argument @var{prompt} is non-@code{nil}, it should be a
string to display in the echo area as a prompt. Otherwise,
If @var{seconds} is non-@code{nil}, it should be a number specifying
the maximum time to wait for input, in seconds. If no input arrives
within that time, @code{read-event} stops waiting and returns
-@code{nil}. A floating-point value for @var{seconds} means to wait
+@code{nil}. A floating point @var{seconds} means to wait
for a fractional number of seconds. Some systems support only a whole
number of seconds; on these systems, @var{seconds} is rounded down.
If @var{seconds} is @code{nil}, @code{read-event} waits as long as
@defun read-char &optional prompt inherit-input-method seconds
This function reads and returns a character of command input. If the
-user generates an event which is not a character (i.e. a mouse click or
+user generates an event which is not a character (i.e., a mouse click or
function key event), @code{read-char} signals an error. The arguments
work as in @code{read-event}.
@cindex control characters, reading
@cindex nonprinting characters, reading
This function is like @code{read-char}, except that if the first
-character read is an octal digit (0-7), it reads any number of octal
+character read is an octal digit (0--7), it reads any number of octal
digits (but stopping if a non-octal digit is found), and returns the
character represented by that numeric character code. If the
character that terminates the sequence of octal digits is @key{RET},
most recently unread will be reread first.
Events read from this list are not normally added to the current
-command's key sequence (as returned by e.g. @code{this-command-keys}),
+command's key sequence (as returned by, e.g., @code{this-command-keys}),
as the events will already have been added once as they were read for
the first time. An element of the form @code{(@code{t} . @var{event})}
forces @var{event} to be added to the current command's key sequence.
individual events, which you can put in @code{unread-command-events}.
@end defun
-@defun input-pending-p
+@defun input-pending-p &optional check-timers
@cindex waiting for command key input
This function determines whether any command input is currently
available to be read. It returns immediately, with value @code{t} if
there is available input, @code{nil} otherwise. On rare occasions it
may return @code{t} when no input is available.
+
+If the optional argument @var{check-timers} is non-@code{nil}, then if
+no input is available, Emacs runs any timers which are ready.
+@xref{Timers}.
@end defun
@defvar last-input-event
@code{sit-for} waited the full time with no input arriving
(@pxref{Event Input Misc}). Otherwise, the value is @code{nil}.
-The argument @var{seconds} need not be an integer. If it is a floating
-point number, @code{sit-for} waits for a fractional number of seconds.
+The argument @var{seconds} need not be an integer. If it is floating
+point, @code{sit-for} waits for a fractional number of seconds.
Some systems support only a whole number of seconds; on these systems,
@var{seconds} is rounded down.
The expression @code{(sit-for 0)} is equivalent to @code{(redisplay)},
-i.e. it requests a redisplay, without any delay, if there is no pending input.
+i.e., it requests a redisplay, without any delay, if there is no pending input.
@xref{Forcing Redisplay}.
If @var{nodisp} is non-@code{nil}, then @code{sit-for} does not
the display. It pays no attention to available input. It returns
@code{nil}.
-The argument @var{seconds} need not be an integer. If it is a floating
-point number, @code{sleep-for} waits for a fractional number of seconds.
+The argument @var{seconds} need not be an integer. If it is floating
+point, @code{sleep-for} waits for a fractional number of seconds.
Some systems support only a whole number of seconds; on these systems,
@var{seconds} is rounded down.
@end deffn
You can specify a character other than @kbd{C-g} to use for quitting.
-See the function @code{set-input-mode} in @ref{Terminal Input}.
+See the function @code{set-input-mode} in @ref{Input Modes}.
@node Prefix Command Arguments
@section Prefix Command Arguments