man/commands.texi

   1 @c This is part of the Emacs manual.
   2 @c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc.
   3 @c See file emacs.texi for copying conditions.
   4 @iftex
   5 @chapter Characters, Keys and Commands
   6
   7   This chapter explains the character sets used by Emacs for input
   8 commands and for the contents of files, and also explains the concepts
   9 of @dfn{keys} and @dfn{commands}, which are fundamental for understanding
  10 how Emacs interprets your keyboard and mouse input.
  11 @end iftex
  12
  13 @node User Input, Keys, Screen, Top
  14 @section Kinds of User Input
  15 @cindex input with the keyboard
  16 @cindex keyboard input
  17 @cindex character set (keyboard)
  18 @cindex ASCII
  19 @cindex C-
  20 @cindex Control
  21 @cindex control characters
  22
  23   GNU Emacs uses an extension of the ASCII character set for keyboard
  24 input; it also accepts non-character input events including function
  25 keys and mouse button actions.
  26
  27   ASCII consists of 128 character codes.  Some of these codes are
  28 assigned graphic symbols such as @samp{a} and @samp{=}; the rest are
  29 control characters, such as @kbd{Control-a} (usually written @kbd{C-a}
  30 for short).  @kbd{C-a} gets its name from the fact that you type it by
  31 holding down the @key{CTRL} key while pressing @kbd{a}.
  32
  33   Some ASCII control characters have special names, and most terminals
  34 have special keys you can type them with: for example, @key{RET},
  35 @key{TAB}, @key{DEL} and @key{ESC}.  The space character is usually
  36 referred to below as @key{SPC}, even though strictly speaking it is a
  37 graphic character whose graphic happens to be blank.  Some keyboards
  38 have a key labeled ``linefeed'' which is an alias for @kbd{C-j}.
  39
  40   Emacs extends the ASCII character set with thousands more printing
  41 characters (@pxref{International}), additional control characters, and a
  42 few more modifiers that can be combined with any character.
  43
  44   On ASCII terminals, there are only 32 possible control characters.
  45 These are the control variants of letters and @samp{@@[]\^_}.  In
  46 addition, the shift key is meaningless with control characters:
  47 @kbd{C-a} and @kbd{C-A} are the same character, and Emacs cannot
  48 distinguish them.
  49
  50   But the Emacs character set has room for control variants of all
  51 printing characters, and for distinguishing between @kbd{C-a} and
  52 @kbd{C-A}.  The X Window System makes it possible to enter all these
  53 characters.  For example, @kbd{C--} (that's Control-Minus) and @kbd{C-5}
  54 are meaningful Emacs commands under X.
  55
  56   Another Emacs character-set extension is additional modifier bits.
  57 Only one modifier bit is commonly used; it is called Meta.  Every
  58 character has a Meta variant; examples include @kbd{Meta-a} (normally
  59 written @kbd{M-a}, for short), @kbd{M-A} (not the same character as
  60 @kbd{M-a}, but those two characters normally have the same meaning in
  61 Emacs), @kbd{M-@key{RET}}, and @kbd{M-C-a}.  For reasons of tradition,
  62 we usually write @kbd{C-M-a} rather than @kbd{M-C-a}; logically
  63 speaking, the order in which the modifier keys @key{CTRL} and @key{META}
  64 are mentioned does not matter.
  65
  66 @cindex Meta
  67 @cindex M-
  68 @cindex @key{ESC} replacing @key{META} key
  69   Some terminals have a @key{META} key, and allow you to type Meta
  70 characters by holding this key down.  Thus, @kbd{Meta-a} is typed by
  71 holding down @key{META} and pressing @kbd{a}.  The @key{META} key
  72 works much like the @key{SHIFT} key.  Such a key is not always labeled
  73 @key{META}, however, as this function is often a special option for a
  74 key with some other primary purpose.  Sometimes it is labeled
  75 @key{ALT} or @key{EDIT}; on a Sun keyboard, it may have a diamond on
  76 it.
  77
  78   If there is no @key{META} key, you can still type Meta characters
  79 using two-character sequences starting with @key{ESC}.  Thus, you can enter
  80 @kbd{M-a} by typing @kbd{@key{ESC} a}.  You can enter @kbd{C-M-a} by
  81 typing @kbd{@key{ESC} C-a}.  @key{ESC} is allowed on terminals with
  82 @key{META} keys, too, in case you have formed a habit of using it.
  83
  84   The X Window System provides several other modifier keys that can be
  85 applied to any input character.  These are called @key{SUPER},
  86 @key{HYPER} and @key{ALT}.  We write @samp{s-}, @samp{H-} and @samp{A-}
  87 to say that a character uses these modifiers.  Thus, @kbd{s-H-C-x} is
  88 short for @kbd{Super-Hyper-Control-x}.  Not all X terminals actually
  89 provide keys for these modifier flags---in fact, many terminals have a
  90 key labeled @key{ALT} which is really a @key{META} key.  The standard
  91 key bindings of Emacs do not include any characters with these
  92 modifiers.  But you can assign them meanings of your own by customizing
  93 Emacs.
  94
  95   Keyboard input includes keyboard keys that are not characters at all:
  96 for example function keys and arrow keys.  Mouse buttons are also
  97 outside the gamut of characters.  You can modify these events with the
  98 modifier keys @key{CTRL}, @key{META}, @key{SUPER}, @key{HYPER} and
  99 @key{ALT}, just like keyboard characters.
 100
 101 @cindex input event
 102   Input characters and non-character inputs are collectively called
 103 @dfn{input events}.  @xref{Input Events,,, elisp, The Emacs Lisp
 104 Reference Manual}, for more information.  If you are not doing Lisp
 105 programming, but simply want to redefine the meaning of some characters
 106 or non-character events, see @ref{Customization}.
 107
 108   ASCII terminals cannot really send anything to the computer except
 109 ASCII characters.  These terminals use a sequence of characters to
 110 represent each function key.  But that is invisible to the Emacs user,
 111 because the keyboard input routines recognize these special sequences
 112 and convert them to function key events before any other part of Emacs
 113 gets to see them.
 114
 115 @node Keys, Commands, User Input, Top
 116 @section Keys
 117
 118 @cindex key sequence
 119 @cindex key
 120   A @dfn{key sequence} (@dfn{key}, for short) is a sequence of input
 121 events that are meaningful as a unit---as ``a single command.''  Some
 122 Emacs command sequences are just one character or one event; for
 123 example, just @kbd{C-f} is enough to move forward one character in the
 124 buffer.  But Emacs also has commands that take two or more events to
 125 invoke.
 126
 127 @cindex complete key
 128 @cindex prefix key
 129   If a sequence of events is enough to invoke a command, it is a
 130 @dfn{complete key}.  Examples of complete keys include @kbd{C-a},
 131 @kbd{X}, @key{RET}, @key{NEXT} (a function key), @key{DOWN} (an arrow
 132 key), @kbd{C-x C-f}, and @kbd{C-x 4 C-f}.  If it isn't long enough to be
 133 complete, we call it a @dfn{prefix key}.  The above examples show that
 134 @kbd{C-x} and @kbd{C-x 4} are prefix keys.  Every key sequence is either
 135 a complete key or a prefix key.
 136
 137   Most single characters constitute complete keys in the standard Emacs
 138 command bindings.  A few of them are prefix keys.  A prefix key combines
 139 with the following input event to make a longer key sequence, which may
 140 itself be complete or a prefix.  For example, @kbd{C-x} is a prefix key,
 141 so @kbd{C-x} and the next input event combine to make a two-event
 142 key sequence.  Most of these key sequences are complete keys, including
 143 @kbd{C-x C-f} and @kbd{C-x b}.  A few, such as @kbd{C-x 4} and @kbd{C-x
 144 r}, are themselves prefix keys that lead to three-event key
 145 sequences.  There's no limit to the length of a key sequence, but in
 146 practice people rarely use sequences longer than four events.
 147
 148   By contrast, you can't add more events onto a complete key.  For
 149 example, the two-event sequence @kbd{C-f C-k} is not a key, because
 150 the @kbd{C-f} is a complete key in itself.  It's impossible to give
 151 @kbd{C-f C-k} an independent meaning as a command.  @kbd{C-f C-k} is two
 152 key sequences, not one.@refill
 153
 154   All told, the prefix keys in Emacs are @kbd{C-c}, @kbd{C-h},
 155 @kbd{C-x}, @kbd{C-x @key{RET}}, @kbd{C-x @@}, @kbd{C-x a}, @kbd{C-x n}, @w{@kbd{C-x
 156 r}}, @kbd{C-x v}, @kbd{C-x 4}, @kbd{C-x 5}, @kbd{C-x 6}, @key{ESC}, and
 157 @kbd{M-g}.  But this list is not cast in concrete; it is
 158 just a matter of Emacs's standard key bindings.  If you customize Emacs,
 159 you can make new prefix keys, or eliminate these.  @xref{Key Bindings}.
 160
 161   If you do make or eliminate prefix keys, that changes the set of
 162 possible key sequences.  For example, if you redefine @kbd{C-f} as a
 163 prefix, @kbd{C-f C-k} automatically becomes a key (complete, unless you
 164 define it too as a prefix).  Conversely, if you remove the prefix
 165 definition of @kbd{C-x 4}, then @kbd{C-x 4 f} (or @kbd{C-x 4
 166 @var{anything}}) is no longer a key.
 167
 168   Typing the help character (@kbd{C-h} or @key{F1}) after a prefix
 169 key displays a list of the commands starting with that prefix.
 170 There are a few prefix keys for which @kbd{C-h} does not
 171 work---for historical reasons, they have other meanings for @kbd{C-h}
 172 which are not easy to change.  But @key{F1} should work for all prefix
 173 keys.
 174
 175 @node Commands, Text Characters, Keys, Top
 176 @section Keys and Commands
 177
 178 @cindex binding
 179 @cindex command
 180 @cindex function definition
 181   This manual is full of passages that tell you what particular keys
 182 do.  But Emacs does not assign meanings to keys directly.  Instead,
 183 Emacs assigns meanings to named @dfn{commands}, and then gives keys
 184 their meanings by @dfn{binding} them to commands.
 185
 186   Every command has a name chosen by a programmer.  The name is usually
 187 made of a few English words separated by dashes; for example,
 188 @code{next-line} or @code{forward-word}.  A command also has a
 189 @dfn{function definition} which is a Lisp program; this is what makes
 190 the command do what it does.  In Emacs Lisp, a command is actually a
 191 special kind of Lisp function; one which specifies how to read arguments
 192 for it and call it interactively.  For more information on commands and
 193 functions, see @ref{What Is a Function,, What Is a Function, elisp, The
 194 Emacs Lisp Reference Manual}.  (The definition we use in this manual is
 195 simplified slightly.)
 196
 197   The bindings between keys and commands are recorded in various tables
 198 called @dfn{keymaps}.  @xref{Keymaps}.
 199
 200   When we say that ``@kbd{C-n} moves down vertically one line'' we are
 201 glossing over a distinction that is irrelevant in ordinary use but is vital
 202 in understanding how to customize Emacs.  It is the command
 203 @code{next-line} that is programmed to move down vertically.  @kbd{C-n} has
 204 this effect @emph{because} it is bound to that command.  If you rebind
 205 @kbd{C-n} to the command @code{forward-word} then @kbd{C-n} will move
 206 forward by words instead.  Rebinding keys is a common method of
 207 customization.@refill
 208
 209   In the rest of this manual, we usually ignore this subtlety to keep
 210 things simple.  To give the information needed for customization, we
 211 state the name of the command which really does the work in parentheses
 212 after mentioning the key that runs it.  For example, we will say that
 213 ``The command @kbd{C-n} (@code{next-line}) moves point vertically
 214 down,'' meaning that @code{next-line} is a command that moves vertically
 215 down and @kbd{C-n} is a key that is standardly bound to it.
 216
 217   While we are on the subject of information for customization only,
 218 it's a good time to tell you about @dfn{variables}.  Often the
 219 description of a command will say, ``To change this, set the variable
 220 @code{mumble-foo}.''  A variable is a name used to remember a value.
 221 Most of the variables documented in this manual exist just to facilitate
 222 customization: some command or other part of Emacs examines the variable
 223 and behaves differently according to the value that you set.  Until you
 224 are interested in customizing, you can ignore the information about
 225 variables.  When you are ready to be interested, read the basic
 226 information on variables, and then the information on individual
 227 variables will make sense.  @xref{Variables}.
 228
 229 @node Text Characters, Entering Emacs, Commands, Top
 230 @section Character Set for Text
 231 @cindex characters (in text)
 232
 233   Text in Emacs buffers is a sequence of 8-bit bytes.  Each byte can
 234 hold a single ASCII character.  Both ASCII control characters (octal
 235 codes 000 through 037, and 0177) and ASCII printing characters (codes
 236 040 through 0176) are allowed; however, non-ASCII control characters
 237 cannot appear in a buffer.  The other modifier flags used in keyboard
 238 input, such as Meta, are not allowed in buffers either.
 239
 240   Some ASCII control characters serve special purposes in text, and have
 241 special names.  For example, the newline character (octal code 012) is
 242 used in the buffer to end a line, and the tab character (octal code 011)
 243 is used for indenting to the next tab stop column (normally every 8
 244 columns).  @xref{Text Display}.
 245
 246   Non-ASCII printing characters can also appear in buffers.  When
 247 multibyte characters are enabled, you can use any of the non-ASCII
 248 printing characters that Emacs supports.  They have character codes
 249 starting at 256, octal 0400, and each one is represented as a sequence
 250 of two or more bytes.  @xref{International}.  Single-byte characters
 251 with codes 128 through 255 can also appear in multibyte buffers.
 252
 253   If you disable multibyte characters, then you can use only one
 254 alphabet of non-ASCII characters, but they all fit in one byte.  They
 255 use codes 0200 through 0377.  @xref{Single-Byte Character Support}.