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 works
  72 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 key
  74 with some other primary purpose.@refill
  75
  76   If there is no @key{META} key, you can still type Meta characters
  77 using two-character sequences starting with @key{ESC}.  Thus, to enter
  78 @kbd{M-a}, you could type @kbd{@key{ESC} a}.  To enter @kbd{C-M-a}, you
  79 would type @kbd{@key{ESC} C-a}.  @key{ESC} is allowed on terminals with
  80 @key{META} keys, too, in case you have formed a habit of using it.
  81
  82   The X Window System provides several other modifier keys that can be
  83 applied to any input character.  These are called @key{SUPER},
  84 @key{HYPER} and @key{ALT}.  We write @samp{s-}, @samp{H-} and @samp{A-}
  85 to say that a character uses these modifiers.  Thus, @kbd{s-H-C-x} is
  86 short for @kbd{Super-Hyper-Control-x}.  Not all X terminals actually
  87 provide keys for these modifier flags---in fact, many terminals have a
  88 key labeled @key{ALT} which is really a @key{META} key.  The standard
  89 key bindings of Emacs do not include any characters with these
  90 modifiers.  But you can assign them meanings of your own by customizing
  91 Emacs.
  92
  93   Keyboard input includes keyboard keys that are not characters at all:
  94 for example function keys and arrow keys.  Mouse buttons are also
  95 outside the gamut of characters.  You can modify these events with the
  96 modifier keys @key{CTRL}, @key{META}, @key{SUPER}, @key{HYPER} and
  97 @key{ALT}, just like keyboard characters.
  98
  99 @cindex input event
 100   Input characters and non-character inputs are collectively called
 101 @dfn{input events}.  @xref{Input Events,,, elisp, The Emacs Lisp
 102 Reference Manual}, for more information.  If you are not doing Lisp
 103 programming, but simply want to redefine the meaning of some characters
 104 or non-character events, see @ref{Customization}.
 105
 106   ASCII terminals cannot really send anything to the computer except
 107 ASCII characters.  These terminals use a sequence of characters to
 108 represent each function key.  But that is invisible to the Emacs user,
 109 because the keyboard input routines recognize these special sequences
 110 and convert them to function key events before any other part of Emacs
 111 gets to see them.
 112
 113 @node Keys, Commands, User Input, Top
 114 @section Keys
 115
 116 @cindex key sequence
 117 @cindex key
 118   A @dfn{key sequence} (@dfn{key}, for short) is a sequence of input
 119 events that are meaningful as a unit---as ``a single command.''
 120 Some Emacs command sequences are just one character or one event; for
 121 example, just @kbd{C-f} is enough to move forward one character.  But
 122 Emacs also has commands that take two or more events to invoke.
 123
 124 @cindex complete key
 125 @cindex prefix key
 126   If a sequence of events is enough to invoke a command, it is a
 127 @dfn{complete key}.  Examples of complete keys include @kbd{C-a},
 128 @kbd{X}, @key{RET}, @key{NEXT} (a function key), @key{DOWN} (an arrow
 129 key), @kbd{C-x C-f}, and @kbd{C-x 4 C-f}.  If it isn't long enough to be
 130 complete, we call it a @dfn{prefix key}.  The above examples show that
 131 @kbd{C-x} and @kbd{C-x 4} are prefix keys.  Every key sequence is either
 132 a complete key or a prefix key.
 133
 134   Most single characters constitute complete keys in the standard Emacs
 135 command bindings.  A few of them are prefix keys.  A prefix key combines
 136 with the following input event to make a longer key sequence, which may
 137 itself be complete or a prefix.  For example, @kbd{C-x} is a prefix key,
 138 so @kbd{C-x} and the next input event combine to make a two-character
 139 key sequence.  Most of these key sequences are complete keys, including
 140 @kbd{C-x C-f} and @kbd{C-x b}.  A few, such as @kbd{C-x 4} and @kbd{C-x
 141 r}, are themselves prefix keys that lead to three-character key
 142 sequences.  There's no limit to the length of a key sequence, but in
 143 practice people rarely use sequences longer than four events.
 144
 145   By contrast, you can't add more events onto a complete key.  For
 146 example, the two-character sequence @kbd{C-f C-k} is not a key, because
 147 the @kbd{C-f} is a complete key in itself.  It's impossible to give
 148 @kbd{C-f C-k} an independent meaning as a command.  @kbd{C-f C-k} is two
 149 key sequences, not one.@refill
 150
 151   All told, the prefix keys in Emacs are @kbd{C-c}, @kbd{C-h},
 152 @kbd{C-x}, @kbd{C-x @key{RET}}, @kbd{C-x @@}, @kbd{C-x a}, @kbd{C-x n}, @w{@kbd{C-x
 153 r}}, @kbd{C-x v}, @kbd{C-x 4}, @kbd{C-x 5}, @kbd{C-x 6}, @key{ESC},
 154 @kbd{M-g} and @kbd{M-j}.  But this list is not cast in concrete; it is
 155 just a matter of Emacs's standard key bindings.  If you customize Emacs,
 156 you can make new prefix keys, or eliminate these.  @xref{Key Bindings}.
 157
 158   If you do make or eliminate prefix keys, that changes the set of
 159 possible key sequences.  For example, if you redefine @kbd{C-f} as a
 160 prefix, @kbd{C-f C-k} automatically becomes a key (complete, unless you
 161 define it too as a prefix).  Conversely, if you remove the prefix
 162 definition of @kbd{C-x 4}, then @kbd{C-x 4 f} (or @kbd{C-x 4
 163 @var{anything}}) is no longer a key.
 164
 165   Typing the help character (@kbd{C-h} or @key{F1}) after a prefix
 166 character displays a list of the commands starting with that prefix.
 167 There are a few prefix characters for which @kbd{C-h} does not
 168 work---for historical reasons, they have other meanings for @kbd{C-h}
 169 which are not easy to change.  But @key{F1} should work for all prefix
 170 characters.
 171
 172 @node Commands, Text Characters, Keys, Top
 173 @section Keys and Commands
 174
 175 @cindex binding
 176 @cindex function
 177 @cindex command
 178 @cindex function definition
 179   This manual is full of passages that tell you what particular keys
 180 do.  But Emacs does not assign meanings to keys directly.  Instead,
 181 Emacs assigns meanings to named @dfn{commands}, and then gives keys
 182 their meanings by @dfn{binding} them to commands.
 183
 184   Every command has a name chosen by a programmer.  The name is usually
 185 made of a few English words separated by dashes; for example,
 186 @code{next-line} or @code{forward-word}.  A command also has a
 187 @dfn{function definition} which is a Lisp program; this is what makes
 188 the command do what it does.  In Emacs Lisp, a command is actually a
 189 special kind of Lisp function; one which specifies how to read arguments
 190 for it and call it interactively.  For more information on commands and
 191 functions, see @ref{What Is a Function,, What Is a Function, elisp, The
 192 Emacs Lisp Reference Manual}.  (The definition we use in this manual is
 193 simplified slightly.)
 194
 195   The bindings between keys and commands are recorded in various tables
 196 called @dfn{keymaps}.  @xref{Keymaps}.
 197
 198   When we say that ``@kbd{C-n} moves down vertically one line'' we are
 199 glossing over a distinction that is irrelevant in ordinary use but is vital
 200 in understanding how to customize Emacs.  It is the command
 201 @code{next-line} that is programmed to move down vertically.  @kbd{C-n} has
 202 this effect @emph{because} it is bound to that command.  If you rebind
 203 @kbd{C-n} to the command @code{forward-word} then @kbd{C-n} will move
 204 forward by words instead.  Rebinding keys is a common method of
 205 customization.@refill
 206
 207   In the rest of this manual, we usually ignore this subtlety to keep
 208 things simple.  To give the information needed for customization, we
 209 state the name of the command which really does the work in parentheses
 210 after mentioning the key that runs it.  For example, we will say that
 211 ``The command @kbd{C-n} (@code{next-line}) moves point vertically
 212 down,'' meaning that @code{next-line} is a command that moves vertically
 213 down and @kbd{C-n} is a key that is standardly bound to it.
 214
 215   While we are on the subject of information for customization only,
 216 it's a good time to tell you about @dfn{variables}.  Often the
 217 description of a command will say, ``To change this, set the variable
 218 @code{mumble-foo}.''  A variable is a name used to remember a value.
 219 Most of the variables documented in this manual exist just to facilitate
 220 customization: some command or other part of Emacs examines the variable
 221 and behaves differently according to the value that you set.  Until you
 222 are interested in customizing, you can ignore the information about
 223 variables.  When you are ready to be interested, read the basic
 224 information on variables, and then the information on individual
 225 variables will make sense.  @xref{Variables}.
 226
 227 @node Text Characters, Entering Emacs, Commands, Top
 228 @section Character Set for Text
 229 @cindex characters (in text)
 230
 231   Text in Emacs buffers is a sequence of 8-bit bytes.  Each byte can
 232 hold a single ASCII character.  Both ASCII control characters (octal
 233 codes 000 through 037, and 0177) and ASCII printing characters (codes
 234 040 through 0176) are allowed; however, non-ASCII control characters
 235 cannot appear in a buffer.  The other modifier flags used in keyboard
 236 input, such as Meta, are not allowed in buffers either.
 237
 238   Some ASCII control characters serve special purposes in text, and have
 239 special names.  For example, the newline character (octal code 012) is
 240 used in the buffer to end a line, and the tab character (octal code 011)
 241 is used for indenting to the next tab stop column (normally every 8
 242 columns).  @xref{Text Display}.
 243
 244   Non-ASCII printing characters can also appear in buffers.  When
 245 multibyte characters are enabled, you can use any of the non-ASCII
 246 printing characters that Emacs supports.  They have character codes
 247 starting at 256, octal 0400, and each one is represented as a sequence
 248 of two or more bytes.  @xref{International}.  Single byte characters
 249 with codes 128 through 255 may also appear in multibyte buffers.
 250
 251   If you disable multibyte characters, then you can use only one
 252 alphabet of non-ASCII characters, but they all fit in one byte.  They
 253 use codes 0200 through 0377.  @xref{Single-Byte Character Support}.