@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.
+
+@anchor{The interactive-only property}
+@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, either directly
+or via @code{declare} (@pxref{Declare Form}). This causes the
+byte compiler to warn if the command is called from Lisp. The output
+of @code{describe-function} will include similar information.
+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
the name of an existing buffer, which becomes the second and final
argument.
-@c Emacs 19 feature
The prompt string can use @samp{%} to include previous argument values
(starting with the first argument) in the prompt. This is done using
@code{format} (@pxref{Formatting Strings}). For example, here is how
signaled if the buffer is read-only.
@cindex @samp{@@} in @code{interactive}
-@c Emacs 19 feature
If @samp{@@} appears at the beginning of the string, and if the key
sequence used to invoke the command includes any mouse events, then
the window associated with the first of those events is selected
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
@end defvar
@defvar last-command-event
-@defvarx last-command-char
This variable is set to the last input event that was read by the
command loop as part of a command. The principal use of this variable
is in @code{self-insert-command}, which uses it to decide which
@noindent
The value is 5 because that is the @acronym{ASCII} code for @kbd{C-e}.
-
-The alias @code{last-command-char} is obsolete.
@end defvar
-@c Emacs 19 feature
@defvar last-event-frame
This variable records which frame the last input event was directed to.
Usually this is the frame that was selected when the event was
@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.
@end example
@defvar num-input-keys
-@c Emacs 19 feature
This variable's value is the number of key sequences processed so far in
this Emacs session. This includes key sequences read from the terminal
and key sequences read from keyboard macros being executed.
@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}.
@code{keyboard-translate-table} (if applicable), before returning it
from @code{read-event}.
-@c Emacs 19 feature
@defvar extra-keyboard-modifiers
This variable lets Lisp programs ``press'' the modifier keys on the
keyboard. The value is a character. Only the modifiers of the
@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
-@defvarx last-input-char
This variable records the last terminal input event read, whether
as part of a command or explicitly by a Lisp program.
@result{} 49
@end group
@end example
-
-The alias @code{last-input-char} is obsolete.
@end defvar
@defmac while-no-input body@dots{}
@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