|
DataMuseum.dkPresents historical artifacts from the history of: DKUUG/EUUG Conference tapes |
This is an automatic "excavation" of a thematic subset of
See our Wiki for more about DKUUG/EUUG Conference tapes Excavated with: AutoArchaeologist - Free & Open Source Software. |
top - metrics - downloadIndex: T l
Length: 55416 (0xd878)
Types: TextFile
Names: »lispref-9«
└─⟦a05ed705a⟧ Bits:30007078 DKUUG GNU 2/12/89
└─⟦c06c473ab⟧ »./UNRELEASED/lispref.tar.Z«
└─⟦1b57a2ffe⟧
└─⟦this⟧ »lispref-9«
Info file: lispref, -*-Text-*-
produced by texinfo-format-buffer
from file: lispref.texinfo
This file documents GNU Emacs Lisp.
This is Edition 0.1 Beta of the GNU Emacs Lisp Reference Manual, for
Emacs Version 18, with some references to Emacs Version 19.
Please read this document for review purposes.
Published by the Free Software Foundation, 675 Massachusetts Avenue,
Cambridge, MA 02139 USA
Copyright (C) 1989 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.
Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation
approved by the Foundation.
▶1f◀
File: lispref Node: interactive Examples, Prev: Interactive Code, Up: Defining Commands
Examples of Using `interactive'
-------------------------------
Here are some more examples of `interactive':
(defun foo1 () ; `foo1' takes no arguments,
(interactive) ; just moves forward two words.
(forward-word 2))
=> foo
(defun foo2 (n) ; `foo2' takes one argument,
(interactive "p") ; which is the processed prefix.
(forward-word (* 2 n)))
=> foo2
(defun foo3 (n) ; `foo3' takes one argument,
(interactive "nCount:") ; which is read from the Minibuffer.
(forward-word (* 2 n)))
=> foo3
(defun three-b (b1 b2 b3)
"Select three existing buffers (prompting for them in
the Minibuffer). Put them into three windows, selecting the
last one."
(interactive "bBuffer1:\nbBuffer2:\nbBuffer3:")
(delete-other-windows)
(split-window (selected-window) 8)
(switch-to-buffer b1)
(other-window 1)
(split-window (selected-window) 8)
(switch-to-buffer b2)
(other-window 1)
(switch-to-buffer b3)
)
=> three-b
(three-b "*scratch*" "declarations.texinfo" "*mail*")
=> nil
▶1f◀
File: lispref Node: Interactive Call, Prev: Defining Commands, Up: Command Loop, Next: Command Loop Info
Interactive Call
================
After the command loop has translated a key sequence into a
definition, it invokes the definition using the function
`command-execute'. If the definition is an ordinary command, that
function calls `call-interactively', which reads the arguments and calls
the command. You can also call these functions yourself.
* Function: commandp OBJECT
Returns `t' if OBJECT is suitable for calling interactively; that
is, if OBJECT is a command. Otherwise, returns `nil'.
The interactively callable objects are strings (treated as keyboard
macros), lambda expressions that contain a top-level call to
`interactive', autoload-objects that are declared as interactive
(non-`nil' fourth argument to `autoload'), and some of the
primitive functions.
Also, a symbol is `commandp' if its function definition is
`commandp'.
Keys and keymaps are not commands. Rather, they are used to look
up commands (*Note Keymaps::).
* Function: call-interactively COMMAND &optional RECORD-FLAG
This function calls COMMAND, reading arguments according to its
interactive calling specifications. It is an error if COMMAND is
not an interactively callable function.
If RECORD-FLAG is non-`nil', then this command and its arguments
are unconditionally added to the `command-history'. Otherwise,
this is done only if the minibuffer is used to read an argument.
*Note Command History::.
* Function: command-execute COMMAND &optional RECORD-FLAG
This function executes COMMAND as an editor command. COMMAND must
satisfy the `commandp' predicate: it must be an interactively
callable function or a string.
A string is executed with `execute-kbd-macro'. Along with the
optional RECORD-FLAG, a function is passed to `call-interactively'.
A symbol is handled by using its function definition in its stead.
A symbol with an `autoload' definition counts as a command if it
was declared to stand for an interactively callable function. Such
a definition is handled by loading the library and then rechecking
the definition of the symbol.
* Command: execute-extended-command PREFIX-ARGUMENT
This primitive function reads a command name from the minibuffer.
It calls the `completing-read' function (*Note Completion::). Then
`execute-extended-command' the command read by `completing-read',
reading the arguments according to the command's `interactive'
specifications. Whatever that command returns becomes the value of
`execute-extended-command'.
If the command asks for a prefix argument, the value
PREFIX-ARGUMENT is supplied to it. If `execute-extended-command'
is called interactively, the raw prefix argument is used for
PREFIX-ARGUMENT, and thus passed on to whatever command is run.
`execute-extended-command' is the normal definition of `M-x'. It
uses the string `M-x ' as a prompt. It would be better to take the
prompt from whatever characters were used to invoke
`execute-extended-command', but that is painful to implement. A
description of the value of the prefix argument, if any, also
becomes part of the prompt.
(execute-extended-command 1)
---------- Buffer: Minibuffer ----------
M-x forward-word RET
---------- Buffer: Minibuffer ----------
=> t
* Function: interactive-p
This function returns `t' if the containing function (the one which
called `interactive-p') was called interactively, with
`call-interactively'. It makes no difference whether
`call-interactively' was called from Lisp or by the editor command
loop. But if the containing function was called from Lisp, then it
was not called interactively.
The usual use of `interactive-p' is for deciding whether to print
an informative message.
As a special exception, `interactive-p' returns `nil' whenever a
keyboard macro is being run. This is to suppress the informative
messages and speed execution of the macro.
For example:
(defun foo ()
(interactive)
(and (interactive-p)
(message "foo")))
=> foo
(defun bar ()
(interactive)
(setq foobar (list (foo) (interactive-p))))
=> bar
;; Type `M-x foo'.
-| foo
;; Although you cannot see it, this returns `"foo"'.
;; Type `M-x bar'.
;; This does not print anything.
foobar
=> (nil t)
▶1f◀
File: lispref Node: Command Loop Info, Prev: Interactive Call, Up: Command Loop, Next: Keyboard Input
Information from the Command Loop
=================================
The editor command loop sets several Lisp variables to keep status
records for itself or to provide them for commands that are run.
* Variable: last-command
This global variable records the name of the previous command
executed by the command loop, the one before the current command.
Normally the value is a symbol with a function definition, but this
is not guaranteed.
This variable is set by copying the value of `this-command' when
each command returns to the command loop, except for commands that
specify a prefix argument.
* Variable: this-command
This global variable is records the name of the command now being
executed by Emacs. As for `last-command', normally it is a symbol
with a function definition.
This variable is set by the command loop just before the command is
run, and its value is copied into `last-command' when the command
finishes (unless the command specifies a prefix argument).
Some commands change the value of this variable during their
execution, simply as a flag for whatever command runs next. In
particular, the functions that kill text always set `this-command'
to `kill-region' so that any kill commands immediately following
will know to append the killed text to the previous kill.
* Function: this-command-keys
This function returns a string of the key sequence that invoked the
present command. It includes the characters that generated the
prefix argument, if any.
(this-command-keys) ;; Now type `C-u C-x C-e'.
=> "^U^X^E"
* Variable: last-command-char
This global variable is set to the last character that was typed on
the terminal and was part of a command. The principal use of this
variable is in `self-insert-command', which uses it to decide which
character to insert.
last-command-char ;; Now type `C-u C-x C-e'.
=> 5
The value is 5 because that is the ASCII code for `C-e'.
* Variable: echo-keystrokes
This global variable determines how much time should elapse before
command characters are echoed. Its value must be a number. If the
user has typed a prefix key (say `C-x') and then delays this many
seconds before continuing, then the key `C-x' will be echoed in the
echo area. Any subsequent keys will be echoed as well.
If the value is 0, then prefix keys are never echoed.
▶1f◀
File: lispref Node: Keyboard Input, Prev: Command Loop Info, Up: Command Loop, Next: Quitting
Keyboard Input
==============
The editor command loop reads keyboard input using
`read-key-sequence', which uses `read-char'. These functions and others
are also available for use in Lisp programs.
Also, see `momentary-string-display' in *Note Temporary Displays::.
* Function: input-pending-p
This function determines whether command input is currently
available. It returns immediately and the result is `t' if so,
`nil' otherwise.
On rare occasions this command may return `t' even when no input is
available.
* Function: discard-input
This function discards the contents of the terminal input buffer
and flushes any keyboard macro that might be in the process of
definition. It returns `nil'.
In the example, the user may type a bunch of characters right after
starting the evaluation of the form. After the `sleep-for'
finishes sleeping, any characters that have been typed are
discarded.
(progn (sleep-for 2)
(discard-input))
=> nil
* Function: read-char
This function reads a character from the command input (which is
either direct keyboard input or characters coming from an executing
keyboard macro), and returns it. It does not move the cursor or
provide any sort of a prompt or other indication that it is waiting
to read a character. However, if the user pauses, previous
keystrokes may echo; see `echo-keystrokes' in *Note Command Loop
Info::.
In the first example, the user types `1' (which is ASCII code 49).
The second example shows a keyboard macro definition which calls
`read-char' from the minibuffer. The keyboard macro's very next
character is the digit 1. This is the character read by
`read-char'.
(read-char)
=> 49
(symbol-function 'foo)
=> "^[^[(read-char)^M1"
(execute-kbd-macro foo)
-| 49
=> nil
* Function: read-quoted-char &optional PROMPT
This function is like `read-char', except that if the first
character read is an octal digit, it reads up to two more octal
digits (0-7) until a non-octal digit is found and returns the
character represented by the octal number consisting of those
digits.
Also, quitting is suppressed. *Note Quitting::.
If PROMPT is supplied, it specifies a string to use to prompt the
user. The prompt string is always printed in the echo area and
followed by a single `-'.
In the example, the user types in the octal number 177. This is
127 in decimal.
(read-quoted-char "What character")
---------- Echo Area ----------
What character-177
---------- Echo Area ----------
=> 127
* Function: read-key-sequence PROMPT
This function reads a key sequence and returns it as a string.
Characters are read until the sequence is sufficient to specify a
(non-prefix) command using the current local and global keymaps.
For each character, if it is an uppercase letter that does not have
a binding in either the local or global keymaps, then the
corresponding lowercase letter is tried; if that is successful, the
character is converted. This function is used to read command
input; the key lookup is different from that of `lookup-key'
because of this automatic downcasing.
Quitting is suppressed inside `read-key-sequence'. In other words,
a `C-g' typed while reading with this function is treated like any
other character, and `quit-flag' is not set. *Note Quitting::.
PROMPT is either a string that is displayed in the echo area as a
prompt, or `nil', in which case no prompt is displayed.
In the example, the prompt `?' is displayed in the echo area, and
the user types `C-x C-f'.
(read-key-sequence "?")
---------- Echo Area ----------
?C-x C-f
---------- Echo Area ----------
=> "^X^F"
* Variable: unread-command-char
This global variable is set to the character to be read as the next
input from the command input stream, or `-1' if there is no such
character. Basically, this is the character that is ``unread'',
when an input function has to read an extra character to finish
parsing its input.
For example, the function that governs prefix arguments reads any
number of digits. When it finds a non-digit character, it must
unread that so that it becomes input for the next command.
For more information, see `waiting-for-user-input-p' in *Note
Receiving Information from Processes::. See `sit-for' in *Note
Waiting::. *Note Terminal Input::, for other functions and variables
related to command key input.
▶1f◀
File: lispref Node: Quitting, Prev: Keyboard Input, Up: Command Loop, Next: Prefix Command Arguments
Quitting
========
Typing `C-g' while the command loop has run a Lisp function causes
Emacs to "quit" whatever it is doing. This means that control returns
to the innermost active command loop.
Typing `C-g' while the command loop is waiting for keyboard input does
not cause a quit. It acts as an ordinary input character. In the
simplest case, you cannot tell the difference, because `C-g' normally
runs the command `keyboard-quit', whose effect is to quit. However,
when `C-g' follows a prefix key, the result is an undefined key. All
this does is cancel the prefix key and any prefix argument.
In the minibuffer, `C-g' has a different definition, which aborts out
of the minibuffer. This means, in effect, that it exits the minibuffer
and then quits. (Simply quitting would return to the command loop
*within* the minibuffer.) This feature is the reason why `C-g' does not
quit directly when the command reader is reading input. `C-g' following
a prefix key is not redefined in the minibuffer; it has its normal
effect, canceling the prefix key and prefix argument as usual.
Certain functions such as `read-key-sequence' or `read-quoted-char'
prevent quitting entirely even though they wait for input. Instead of
quitting, `C-g' serves as the requested input. In the case of
`read-key-sequence', this serves to bring about the special behavior of
`C-g' in the command loop. In the case of `read-quoted-char', this is
so that `C-q' can be used to quote an `C-g'.
The only direct effect of typing `C-g' is to set the variable
`quit-flag' to a non-`nil' value. Appropriate places inside Emacs check
this variable and quit if it is not `nil'. Setting `quit-flag'
non-`nil' in any other way also causes a quit.
At the level of C code, quits cannot happen just anywhere; only at
particular places which check `quit-flag'. This is so quitting will not
leave an inconsistency in Emacs's internal state. Instead, the quit is
delayed until a safe point, such as when the primitive finishes or tries
to wait for input.
You can prevent quitting for a portion of a Lisp function by binding
the variable `inhibit-quit' to a non-`nil' value. `C-g' still sets
`quit-flag' to `t' as usual, but the usual result of this---a quit---is
prevented. When the binding is unwound at the end of the `let' form, if
`quit-flag' is still non-`nil', the requested quit happens immediately.
This is exactly what you want for a ``critical section'', where you
simply wish quitting not to happen at a certain point in the program.
If you wish to handle `C-g' in a completely different way, so there
should be no quit at all, then you should set `quit-flag' to `nil'
before unbinding `inhibit-quit'. This excerpt from the definition of
`read-quoted-char' shows how this is done; it also shows that normal
quitting is permitted after the first character of input.
(defun read-quoted-char (&optional prompt)
"...DOCUMENTATION..."
(let ((count 0) (code 0) char)
(while (< count 3)
(let ((inhibit-quit (zerop count))
(help-form nil))
(and prompt (message "%s-" prompt))
(setq char (read-char))
(if inhibit-quit (setq quit-flag nil)))
...)
(logand 255 code)))
* Variable: quit-flag
If this variable is non-`nil', then Emacs quits immediately, unless
`inhibit-quit' is non-`nil'. Typing `C-g' sets `quit-flag'
non-`nil', regardless of `inhibit-quit'.
* Variable: inhibit-quit
This variable determines whether Emacs should quit when `quit-flag'
is set to `t'. If `inhibit-quit' is non-`nil', then `quit-flag'
has no special effect.
* Command: keyboard-quit
This function signals the `quit' condition with `(signal 'quit)'.
This is the same thing that quitting does. (See `signal' in *Note
Errors::.)
▶1f◀
File: lispref Node: Prefix Command Arguments, Prev: Quitting, Up: Command Loop, Next: Recursive Editing
Prefix Command Arguments
========================
Most Emacs commands can use a prefix argument, a number specified
before the command itself. (Don't confuse prefix arguments with prefix
keys.) The prefix argument is represented by a value which is always
available (though it may be `nil', meaning there is no prefix argument);
each command may use it or ignore it.
There are two representations of the prefix argument: "raw" and
"numeric". Emacs uses the raw representation internally, and so do the
Lisp variables which store the information, but commands can request
either representation.
Here are the possible values of a raw prefix argument:
* `nil', meaning there is no prefix argument. Its numeric value is
1, but numerous commands make a distinction.
* An integer, which stands for itself.
* A list of one element, that being an integer. This form of prefix
argument results from a succession of `C-u''s with no digits. The
numeric value is that integer, but some commands make a
distinction.
* The symbol `-'. This indicates that `M--' or `C-u -' was typed
without digits. The numeric value is -1, but some commands make a
distinction.
There are two variables used to store the prefix argument:
`prefix-arg' and `current-prefix-arg'. Commands such as
`universal-argument' which create prefix arguments store them in
`prefix-arg'. In contrast, `current-prefix-arg' conveys the prefix
argument to the current command; setting that variable has no effect on
the prefix arguments for future commands.
Normally, commands specify which kind of the argument they want to
see, either processed or unprocessed, in the `interactive' declaration.
(*Note Interactive Call::.) Alternatively, functions may look at the
value of the prefix argument directly in the variable
`current-prefix-arg'. Don't call `universal-argument',
`digit-argument', or `negative-argument' unless you intend to let the
user enter the prefix argument for the *next* command.
* Command: universal-argument
This command reads input and specifies a prefix argument for the
following command. Don't call this command yourself unless you are
a real wizard.
* Command: digit-argument ARG
This command constructs part of the prefix argument for the
following command. The argument ARG is the raw prefix argument as
it was before this command; it is used to compute the updated
prefix argument. Don't call this command yourself unless you are a
real wizard.
* Command: negative-argument ARG
This command constructs part of the numeric argument for the next
command. The argument ARG is the raw prefix argument as it was
before this command; its value is negated to form the new prefix
argument. Don't call this command yourself unless you are a real
wizard.
* Function: prefix-numeric-value ARG
This function returns the numeric meaning of the raw prefix
argument, ARG. A raw prefix argument may be a symbol, a number, or
a list. If it is `nil', then the value 1 is returned. If it is
any other symbol, then the value -1 is returned. If it is a
number, that number is returned, and if it is a list, then the CAR
of that list (which should be a number) is returned.
* Variable: current-prefix-arg
This variable is the value of the raw prefix argument for the
*current* command. Commands may examine it directly, but the usual
way to access it is with `(interactive "P")'.
* Variable: prefix-arg
The value of this variable is the raw prefix argument for the
*next* editing command. Commands which specify prefix arguments
set this variable.
▶1f◀
File: lispref Node: Recursive Editing, Prev: Prefix Command Arguments, Up: Command Loop, Next: Disabling Commands
Recursive Editing
=================
The Emacs command loop is entered automatically when Emacs starts up.
This top-level invocation of the command loop is never exited until the
Emacs is killed. Lisp programs can also invoke the command loop. Since
this makes more than one activation of the command loop, we call it
"recursive editing". A recursive editing level has the effect of
suspending whatever command invoked it and permitting the user to do
arbitrary editing before resuming that command.
The same commands are available during recursive editing as are
available in the top-level editing loop, depending on the major mode, of
course. Only a few special commands exit the recursive editing level;
the others remain within it. (These special commands are always
available, but are useless when recursive editing is not in progress.)
All command loops, including recursive ones, set up all-purpose error
handlers so that an error in a command run from the command loop will
not exit the loop.
Minibuffer input is a special kind of recursive editing. It has a few
special wrinkles, such as enabling display of the minibuffer and the
minibuffer window, but fewer than you might suppose. Keystrokes behave
differently in the minibuffer, but that is only because of the
minibuffer's local map; if you switch windows, you get the usual Emacs
commands.
To invoke a recursive editing level, call the function
`recursive-edit'. This function contains the command loop. It also
contains a call to `catch' with tag `exit'; this makes it possible to
exit the recursive editing level by throwing to `exit'. *Note Catch and
Throw::.
If you throw a value other than `t', then `recursive-edit' returns
normally to the function which called it. The command `C-M-c'
(`exit-recursive-edit') does this. Throwing a `t' value causes
`recursive-edit' to quit, so that control returns to the command loop
one level up. This is called "aborting", and is done by `C-]'
(`abort-recursive-edit').
Most applications should not use recursive editing, except for the
minibuffer. Usually it is better for the user to change the major mode
of the current buffer temporarily to a special, new mode, which has a
command to go back to the previous mode. This technique is used by the
`w' command in Rmail, for example. Or, if you wish to give the user
different text to edit ``recursively'', create and select a new buffer
in a special mode. In this mode, define a command to complete the
processing and go back to the previous buffer. The `m' command in Rmail
does this.
One place where recursive edits are useful is in debugging. You can
insert a call to `recursive-edit' into a function as a sort of
breakpoint, so that you can look around when you get there. Even
better, instead of calling `recursive-edit' directly, call `debug',
which uses a recursive edit but also provides the other features of the
debugger.
Recursive editing levels are also used when you type `C-r' in
`query-replace' or use `C-x q' (`kbd-macro-query').
* Function: recursive-edit
This function invokes the editor command loop. It is called
automatically by the initialization of Emacs to begin editing.
When called from a Lisp program, it enters a recursive editing
level.
In the example, the function `simple-rec' first advances the
point one word, then enters a recursive edit, printing out a
message in the echo area. The user can then do any editing
desired, then type `C-M-c' to exit and continue executing
`simple-rec'.
(defun simple-rec ()
(forward-word 1)
(message "Recursive edit in progress.")
(recursive-edit)
(forward-word 1))
=> simple-rec
(simple-rec)
=> nil
* Command: exit-recursive-edit
This function exits from the innermost recursive edit (including
minibuffer input). Its definition is effectively `(throw 'exit
nil)'.
* Command: abort-recursive-edit
This function aborts the command that requested the innermost
recursive edit (including minibuffer input), by signaling a `quit'
error after exiting the recursive edit. Its definition is
effectively `(throw 'exit t)'.
* Command: top-level
This function exits all recursive editing levels. It does not
return a value, as it essentially jumps completely out of any
computation directly back into the main command loop.
* Function: recursion-depth
This function returns the current depth of recursive edits. When
no recursive edit is active, it returns 0.
▶1f◀
File: lispref Node: Disabling Commands, Prev: Recursive Editing, Up: Command Loop, Next: Command History
Disabling Commands
==================
Disabling a command marks the command as requiring confirmation before
it can be executed. The purpose of disabling a command is to prevent
users from executing it by accident, which could be confusing or
damaging.
The direct mechanism for disabling a command is to have a non-`nil'
`disabled' property on the Lisp symbol for the command. These
properties are normally set up by the user's `.emacs' file with Lisp
expressions such as
(put 'upcase-region 'disabled t)
For a few commands, these properties are present by default and may be
removed by the `.emacs' file.
If the value of the `disabled' property is a string, that string is
included in the message printed when the command is used:
(put 'delete-region 'disabled
"Text deleted this way cannot be yanked back!\n")
*Note Disabling Commands: (emacs)Disabling Commands, for the details
on what happens when a disabled command is invoked. Disabling a command
has no effect on calling it as a function from Lisp programs.
* Command: enable-command COMMAND
Allow COMMAND to be executed without special confirmation from now
on. The user's `.emacs' file is optionally altered so that this
will apply to future sessions.
* Command: disable-command COMMAND
Require special confirmation to execute COMMAND from now on. The
user's `.emacs' file is optionally altered so that this will apply
to future sessions.
* Variable: disabled-command-hook
The value of this variable is a function to be called instead of
any command that is disabled (i.e., that has a non-`nil' disabled
property). By default, the value of `disabled-command-hook' is a
function defined to ask the user whether to proceed.
▶1f◀
File: lispref Node: Command History, Prev: Disabling Commands, Up: Command Loop, Next: Keyboard Macros
Command History
===============
Emacs keeps a history of the complex commands that have been executed,
to make it easy to repeat these commands. A "complex command" is
defined to be one whose arguments are read using the minibuffer. This
includes any `M-x' command, any `M-ESC' command, and any command whose
`interactive' specification reads an argument from the minibuffer. It
does *not* include commands because they use the minibuffer explicitly
once they are called.
* Variable: command-history
This global variable's value is a list of recent commands. Each
command is represented as a form to evaluate. It continues to
accumulate all complex commands for the duration of the editing
session, but at garbage collection time all but the first (most
recent) thirty elements are deleted.
command-history
=> ((switch-to-buffer "chistory.texinfo")
(describe-key "^X^[")
(visit-tags-table "~/emacs/src/")
(find-tag "repeat-complex-command"))
There are a number of commands and even two entire modes devoted to
facilitating the editing and recall of previous commands. The commands
`repeat-complex-command', and `list-command-history' are described in
the user manual (*Note Command History: (emacs)Command History.).
* Variable: repeat-complex-command-map
The value of this variable is a sparse keymap used by the
minibuffer when attempting to repeat a ``complex'' command.
▶1f◀
File: lispref Node: Keyboard Macros, Prev: Command History, Up: Command Loop
Keyboard Macros
===============
A keyboard macro is a canned sequence of keystrokes that can be
considered a command and made the definition of a key. Don't confuse
keyboard macros with Lisp macros (*Note Macros::).
* Function: execute-kbd-macro MACRO &optional COUNT
This function executes MACRO as a string of editor commands. If
MACRO is a string, then the characters in that string are executed
exactly as if they had been typed to Emacs.
If MACRO is a symbol, then its function definition is used in place
of MACRO. If that is another symbol, this process repeats.
Eventually the result should be a string. If the result is neither
a symbol nor a string, an error is signaled.
The argument COUNT is a repeat count; MACRO is executed that many
times. If COUNT is omitted or `nil', MACRO is executed once. If
it is 0, MACRO is executed over and over until it encounters an
error or a failing search.
* Variable: last-kbd-macro
This variable is the definition of the most recently defined
keyboard macro. Its value should be a string of characters, or
`nil'.
* Variable: defining-kbd-macro
This variable indicates whether a keyboard macro is being defined.
It is set to `t' by `start-kbd-macro', and `nil' by
`end-kbd-macro'. Do not set this variable yourself!
* Variable: executing-macro
This variable contains the string that defines the keyboard macro
that is currently executing. It is `nil' if no macro is currently
executing.
* Variable: executing-macro-index
This variable is the number of characters already executed from the
currently executing keyboard macro. It increments as the macro is
executed.
The user-level commands for defining, running and editing keyboard
macros include `call-last-kbd-macro', `insert-kbd-macro',
`start-kbd-macro', `end-kbd-macro', `kbd-macro-query', and
`name-last-kbd-macro'. They are described in the user's manual (*Note
Keyboard Macros: (emacs)Keyboard Macros.).
▶1f◀
File: lispref Node: Keymaps, Prev: Command Loop, Up: Top, Next: Major and Minor Modes
Keymaps
*******
The bindings between keyboard input and commands are recorded in data
structures called "keymaps". Each binding in a keymap is between an
individual character and either another keymap or a command. When a
character is bound to another keymap, the next character in the key
sequence is looked up in that keymap, and so on until a command is
found. This process is called "key lookup".
* Menu:
* Keymap Terms::
* Creating Keymaps::
* Key Lookup::
* Prefix Keys::
* Global and Local Keymaps::
* Changing Key Bindings::
▶1f◀
File: lispref Node: Keymap Terms, Prev: Keymaps, Up: Keymaps, Next: Creating Keymaps
Keymaps: Terminology
====================
A sequence of keyboard input characters, or "keystrokes" is called a
"key". Thus, a key is not necessarily a single character.
A key is said to have a "key binding" if all the characters in the
sequence of keyboard input characters are bound; this is the case when
each character is bound to a keymap in which the rest of the key is
looked up.
A "complete key" is one that is bound to a command. A "prefix key" is
one that is bound to a keymap. Therefore, any initial sequence of a
complete key is a prefix key. But the characters that follow a prefix
key may or may not complete the key. An "undefined key" is one that is
not bound to either a keymap or a command. *Note Prefix Keys::, for a
more details.
Examples of complete keys are ``X'', ``RET'', and ``C-x 4 C-f''.
Examples of prefix keys are ``C-c'', ``C-x'', and ``C-x 4''. Examples
of undefined keys are ``C-x C-g'', and ``C-c 3''.
At any one time, two primary keymaps are in use: the "global map",
which is available in all buffers, and the "local keymap", which is
usually associated with a major mode. The local keymap bindings shadow
(i.e., are used in place of) the corresponding global bindings. *Note
Global and Local Keymaps::, for the details.
Note that a command is any action that may be called interactively
(*Note Command Overview::), including keyboard macros (*Note Keyboard
Macros::).
▶1f◀
File: lispref Node: Creating Keymaps, Prev: Keymap Terms, Up: Keymaps, Next: Key Lookup
Creating Keymaps
================
A keymap can be represented as one of two kinds of Lisp object: a
vector or a list. A "full keymap" is a vector of length 128. The
binding for a character in such a keymap is found by indexing into the
vector with the character as the index.
A "sparse keymap" is a list whose CAR is the symbol `keymap', and whose
remaining elements are pairs of the form `(CHAR . BINDING)'. Such a
list is called a "sparse keymap" because most of the entries would be
`nil' in a full keymap. Use a sparse keymap when you expect only a few
entries. (Also, Emacs automatically creates sparse keymaps for
intermediate keymaps, when `define-key' requires them.)
Keymaps are only of length 128, and so are unable to handle META
characters, whose codes are from 128 to 255. Instead, Emacs represents
a META character as a sequence of two characters, the first of which is
ESC (the usual value of `meta-prefix-char'). Thus, the key `M-a' is
really represented as `ESC a', and its binding is found at the slot for
`a' in `esc-map'.
For example, the Lisp mode keymap uses `C-c C-l' for the `run-lisp'
command, `M-C-q' for `indent-sexp', and `M-C-x' for `lisp-send-defun'.
lisp-mode-map
=>
(keymap
(9 . lisp-indent-line) ; TAB
(127 . backward-delete-char-untabify) ; DEL
(3 keymap
(12 . run-lisp)) ; `C-c C-l'
(27 keymap
(17 . indent-sexp) ; `M-C-q'
(24 . lisp-send-defun))) ; `M-C-x'
* Function: keymapp OBJECT
This function returns `t' if OBJECT is a keymap, `nil' otherwise.
A keymap is either a vector of length 128, or a list with the form
`(keymap PAIRS...)', where PAIRS is a series of pairs of the form
`(CHAR . BINDING)'.
(keymapp '(keymap))
=> t
(keymapp (current-global-map))
=> t
* Function: make-keymap
This function creates and returns a new full keymap (i.e., a
vector of length 128). All entries in the keymap are `nil', which
means that each command is undefined in this keymap.
(make-keymap)
=> [nil nil nil ... nil nil]
* Function: make-sparse-keymap
This function creates and returns a new sparse keymap with no
entries.
(make-sparse-keymap)
=> (keymap)
* Function: copy-keymap KEYMAP
This function returns a copy of KEYMAP. Starting with Emacs
version 18.50, `copy-keymap' is done recursively so any keymaps
that are components of KEYMAP are copied as well.
(setq map (copy-keymap (current-local-map)))
=> (keymap
(27 keymap ; (This implements META characters.)
(83 . center-paragraph)
(115 . center-line))
(9 . tab-to-tab-stop))
(eq map (current-local-map))
=> nil
(equal map (current-local-map))
=> t
▶1f◀
File: lispref Node: Key Lookup, Prev: Creating Keymaps, Up: Keymaps, Next: Prefix Keys
Key Lookup
==========
"Key lookup" is the process by which Emacs searches through keymaps to
find the non-keymap object bound to the key. (Note that the key lookup
process should be distinguished from the process of calling the command
that is found by the key lookup.)
There are several types of "keymap entry" that may appear in either
full or sparse keymaps. Indeed, any Lisp object may appear in a keymap,
but only a few types of object have meaning either for looking up keys
or for calling commands.
When Emacs looks up a key, the lookup process starts from a particular
keymap that is determined by Emacs's current mode. Emacs uses each
character of the key in sequence, determining the binding of the
character. If the binding of the character in the keymap is another
keymap, the next character in the key, if any, is used to lookup the
next object. This process repeats until any non-keymap object is found;
that object is the result of the key lookup. If the key is not long
enough to lead to a non-keymap object, then a keymap is the result of
the lookup.
The recognized keymap entries and their meanings are listed below.
`nil'
As a special case, `nil' means that the characters used so far in
the lookup are undefined in this keymap. A `nil' entry is also
returned if a sparse keymap has no binding for the character.
KEYMAP
The characters used so far in the lookup are a prefix key.
Subsequent characters are looked up starting in KEYMAP, which may
be full or sparse.
LIST
The characters used so far in the lookup may or may not be a prefix
key, depending on the form of the list.
* If the CAR of LIST is the symbol `keymap', then this is really
a keymap entry and is used as described above.
* As a special case, if LIST looks like `(KEYMAP . CHAR)', then
the binding of CHAR in the keymap called KEYMAP is used as if
it had been the entry. This permits you to define one key as
an alias for another key, so it uses whatever definition the
othr key has.
* If the CAR of LIST is `lambda', then this is a lambda
expression, which should be interactive. It is the definition
of the key.
STRING
The STRING represents a keyboard macro. When the characters used
so far in the lookup is entered as a command, the characters in
STRING are used as if they had been typed instead of the key.
(*Note Keyboard Macros::, for the details.)
SYMBOL
The SYMBOL's function definition is found by dereferencing. e*Note
Classifying Lists::, to find out how symbols are dereferenced. One
of the following objects should be found.
* As a special case, if a keymap is found in the symbol's
function cell, it is used as if the entry had been that
keymap. A keymap is not a function, so this symbol would not
be valid in a function call.
* If a function is found, it is the result of the key lookup.
When the key is entered, that function is called; it must be
interactive.
Two commands are available for special purposes: `ignore' and
`undefined'.
The command `ignore' means that the key does nothing (`ignore'
just returns `nil'). The command `undefined' means to treat
the key as undefined; this command calls `ding' to ring the
bell, but does not cause an error.
* If a string is found, it represents a keyboard macro, as
above.
* If a list of the form `(KEYMAP . CHAR)' is found, it is *not*
used as if it had been the entry. This sort of list is
meaningful only if it appears directly in the keymap.
ANYTHING ELSE
If any other type of object is found, the lookup terminates.
In short, a keymap entry may be another keymap, or a command. Three
special cases are `nil', meaning that the characters used so far are
undefined in this keymap; a list that starts with a keymap; and a symbol
with a keymap in the function cell.
* Function: lookup-key KEYMAP KEY
This function returns the definition of KEY in KEYMAP. If it
returns a number, this means KEY is ``too long''; that is, the
characters fail to be a valid sequence in KEYMAP. The number is
how many characters at the front of KEY that compose a meaningful
key sequence.
This function does not perform automatic downcasing as is done by
`read-key-sequence' (*Note Keyboard Input::). All the other
functions described in this chapter that lookup keys use
`lookup-key'.
(lookup-key (current-global-map) "\C-x\C-f")
=> find-file
(lookup-key (current-global-map) "\C-x\C-f12345")
=> 2
* Function: ignore &rest ARGS
Ignore any arguments and return `nil'. Used in keymaps to ignore
keys.
* Command: undefined
Used in keymaps to undefine keys. It calls `ding', but does not
cause an error.
▶1f◀
File: lispref Node: Prefix Keys, Prev: Key Lookup, Up: Keymaps, Next: Global and Local Keymaps
Prefix Keys
===========
A "prefix key" has an associated keymap which defines what to do with
key sequences that start with the prefix key. For example, `ctl-x-map'
is the keymap used for characters following the prefix key `C-x'. The
following keymaps are reached via the global keymap when looking up the
associated prefix key.
* `ctl-x-map' is the variable name for the map used for characters
that follow `C-x'. This map is also in the function cell of
`Control-X-prefix'.
* `ctl-x-4-map' is for characters that follow `C-x 4'.
* `esc-map' is for characters that follow ESC. Thus, all Meta
characters are actually defined by this map. This map is also in
the function cell of `ESC-prefix'.
* `help-map' is used for characters that follow `C-h'.
* `mode-specific-map' is for characters that follow `C-c'.
The binding of a prefix key is the keymap to use for looking up the
characters that follow the prefix key. In many cases, the binding is to
a Lisp symbol whose function definition is a keymap. The effect is the
same, but the use of a symbol doubles as a description of what the
prefix key is for. Thus, the binding of `C-x' is the symbol
`Control-X-prefix', whose function definition is the keymap for `C-x'
commands. This keymap is also the value of `ctl-x-map'.
Prefix key definitions of this sort can appear in either the global
map or a local map. The definitions of `C-c', `C-x', `C-h' and ESC as
prefix keys appear in the global map, so these prefix keys are always
available. Major modes can locally redefine a key as a prefix by
putting a prefix key definition for it in the local map.
If a key is defined as a prefix in both the local map and the global,
the two definitions are effectively merged: the commands defined in the
local map's prefix definition take priority; those not defined there are
taken from the global map.
In this example, `C-p' is made a prefix key in the local keymap (so
that `C-p' is identical to `C-x'). The binding for `C-p C-f' is the
function `find-file', just like `C-x C-f'. The key sequence `C-p 6' is
not found in either the local map or global map.
(use-local-map (make-sparse-keymap))
=> nil
(local-set-key "\C-p" ctl-x-map)
=> nil
(key-binding "\C-p\C-f")
=> find-file
(key-binding "\C-p6")
=> nil
* Function: define-prefix-command SYMBOL
This function defines SYMBOL as a prefix command. It creates a
full keymap and stores it as SYMBOL's function definition. This
can be used to create a keymap that is used like the `ESC-prefix'
keymap. It may be convenient to also store the keymap in a
variable. This function returns SYMBOL.
In version 19, both the function definition and value are set.
In 18.54, the function definition is set, but not the value.
* Variable: meta-prefix-char
This global variable is the Meta-prefix character code. Normally
it will be ESC, which has the value of the decimal integer 27. It
is used when translating a meta-character to a two-character
sequence so it can be looked up in a keymap.
Thus, in the default configuration, typing `M-b' causes Emacs to
look up `ESC b' in the current keymap and this calls the
`backward-word' command. However, if you set the value of
`meta-prefix-char' to 24, the code for `C-x', typing `M-b' will
cause Emacs to look up `C-x b' when you type `M-b'; this will call
the `switch-to-buffer' command.
meta-prefix-char ; The default value.
=> 27
(key-binding "\M-b")
=> backward-word
?\C-x ; The print representation
=> 24 ; of a character.
(setq meta-prefix-char 24)
=> 24
(key-binding "\M-b")
=> switch-to-buffer ; Now, typing `M-b' is
; like typing `C-x b'.
(setq meta-prefix-char 27) ; Avoid confusion!
=> 27 ; Restore the default value!
▶1f◀
File: lispref Node: Global and Local Keymaps, Prev: Prefix Keys, Up: Keymaps, Next: Changing Key Bindings
Global and Local Keymaps
========================
The "global keymap" holds the bindings of keys that are defined
regardless of the current buffer, such as `C-f'. The variable
`global-map' holds this keymap.
Each buffer may have another keymap, its "local keymap", which may
contain new or overriding definitions for keys. Each buffer records
which local keymap is used with it.
Both the global and local keymaps are used to determine what command
to execute when a key is entered. The key lookup proceeds as described
earlier (*Note Key Lookup::), but Emacs *first* searches for the key in
the local map; if Emacs does not find a local definition, Emacs then
searches the global map.
Since every buffer that uses the same major mode normally uses the
very same local keymap, it may appear as if the keymap is local to the
mode. A change to the local keymap in one buffer (using `define-key',
for example) will only be seen in other buffers that use that keymap.
The minibuffer has local keymaps, too; they contain various completion
and exit commands. *Note Minibuffers::.
The local keymaps that are used for Lisp mode, C mode, and several
other major modes always exist even when they are not in use. These
local maps are the values of the variables `lisp-mode-map',
`c-mode-map', and so on. Other modes are less frequently used, and the
local keymaps for these modes are constructed only when the mode is used
for the first time in a session.
*Note Standard Keymaps::, for a list of standard keymaps.
* Variable: global-map
This variable contains the default global keymap that maps Emacs
keyboard input to commands. The value of `global-map' is a keymap
which is usually (but not necessarily) Emacs's global map. The
default global keymap is a full keymap that binds
`self-insert-command' to all of the visible characters.
* Function: current-global-map
This function returns the current global keymap. Normally, this
is the same as the value of the `global-map'.
(current-global-map)
=> [set-mark-command beginning-of-line ... delete-backward-char]
* Function: current-local-map
This function returns the current buffer's local keymap, or `nil'
if it has none. In the following example, the keymap for the
`*scratch*' buffer (using Lisp Interaction mode) is a sparse keymap
in which the entry for ESC, 27, is another sparse keymap.
(current-local-map)
=> (keymap
(10 . eval-print-last-sexp)
(9 . lisp-indent-line)
(127 . backward-delete-char-untabify)
(27 keymap
(24 . eval-defun)
(17 . indent-sexp)))
* Function: use-global-map KEYMAP
This function makes KEYMAP the new current global keymap. The
KEYMAP map must be a full keymap (a vector of length 128). It
returns `nil'.
It is very unusual to change the global keymap (there are few
standard modes that do so).
* Function: use-local-map KEYMAP
This function makes KEYMAP the new current local keymap of the
current buffer. If KEYMAP is `nil', then there will be no local
keymap. It returns `nil'. Most major modes use this function.
* Function: key-binding KEY
This function returns the definition for KEY in the current
keymaps trying the current buffer's local map and then the global
map. The result is `nil' if KEY is undefined in the keymaps.
It is an error unless KEY is a string.
(key-binding "\C-x\C-f")
=> find-file
* Function: local-key-binding KEY
This function returns the definition for KEY in the current local
keymap, or `nil', if it is undefined there.
* Function: global-key-binding KEY
This function returns the definition for command KEY in the
current global keymap, or `nil', if it is undefined there.
* Function: accessible-keymaps KEYMAP
This function returns a list of all the keymaps that can be
accessed, via prefix keys, from KEYMAP. The list returned is an
association list with elements of the form `(KEY . MAP)', where KEY
is a prefix whose definition in KEYMAP is MAP.
The elements of the alist are ordered so that the KEY increases
in length. The first element is always `("" . KEYMAP)', which
means that the empty string prefix gets you to the keymap you start
with.
In the example below, the returned alist indicates that by typing
ESC, which is displayed as `"^["', you will get to the sparse
keymap `(keymap (83 . center-paragraph) (115 . foo))'.
(accessible-keymaps (current-local-map))
=>(("" keymap
(27 keymap ; Note this keymap for ESC appears below.
(83 . center-paragraph)
(115 . center-line))
(9 . tab-to-tab-stop))
("^[" keymap
(83 . center-paragraph)
(115 . foo)))
In the following example, typing `C-h' will get you to the sparse
keymap starting `(118 . describe-variable) ...'. Typing `C-x 4',
will get you to the full keymap beginning `[nil ...]' (which
happens to be `ctl-x-4-map').
(accessible-keymaps (current-global-map))
=> (("" . [set-mark-command beginning-of-line ...
delete-backward-char])
("^C" keymap (13 . x-flush-mouse-queue))
("^H" keymap (118 . describe-variable) ... (8 . help-for-help))
("^X" . [x-flush-mouse-queue ... backward-kill-sentence])
("^[" . [mark-sexp backward-sexp ... backward-kill-word])
("^X4" . [nil ... find-file-other-window nil ...
nil nil]))
* Function: where-is-internal COMMAND &optional KEYMAP FIRSTONLY
This function returns list of key sequences (of any length) that
are bound to COMMAND in KEYMAP and the global keymap. COMMAND can
be any object; it is compared with all keymap entries using `eq'.
If KEYMAP is not supplied, then the global map is used.
If FIRSTONLY is non-`nil', then it returns a string representing
the first key sequence found, rather than a list of all possible
key sequences.
This function is used by `where-is' (*Note Help: (emacs)Help.).
(where-is-internal 'kill-word)
=> ("^[d" "^[OC") ; Locally, `kill-word' is
; bound to a function key
; as well as to `M-d'.
* Command: describe-bindings
This function creates a listing of all defined keys, and their
definitions. The listing is put in a buffer named `*Help*', which
then is displayed in a window.
A command using the META key is shown as ESC followed by the rest
of the key sequence. A command using the control key is shown as
`C-' followed by the rest of the key sequence.
A number of keys that all share the same definition are shown as
the first character followed by two dots, followed by the last
character. It does help to know ASCII codes for this instance. In
the default global map, `SPC .. ~' are all bound to
`self-insert-command'. SPC is ASCII 32, `~' is ASCII 126, and all
the normal printing characters, (e.g., letters, digits,
punctuation, etc.) lie between these two.
▶1f◀