cgit.sxemacs.org Git - sxemacs/blob - info/sxemacs/m-x.texi

   1 @node M-x, Help, Minibuffer, Top
   2 @chapter Running Commands by Name
   3
   4   The Emacs commands that are used often or that must be quick to type are
   5 bound to keys---short sequences of characters---for convenient use.  Other
   6 Emacs commands that are used more rarely are not bound to keys; to run
   7 them, you must refer to them by name.
   8
   9   A command name consists, by convention, of one or more words,
  10 separated by hyphens: for example, @code{auto-fill-mode} or
  11 @code{manual-entry}.  The use of English words makes the command name
  12 easier to remember than a key made up of obscure characters, even though
  13 it results in more characters to type.  You can run any command by name,
  14 even if it can be run by keys as well.
  15
  16 @kindex M-x
  17 @cindex minibuffer
  18  To run a command by name, start with @kbd{M-x}, then type the
  19 command name, and finish with @key{RET}.  @kbd{M-x} uses the minibuffer
  20 to read the command name.  @key{RET} exits the minibuffer and runs the
  21 command.
  22
  23   Emacs uses the minibuffer for reading input for many different purposes;
  24 on this occasion, the string @samp{M-x} is displayed at the beginning of
  25 the minibuffer as a @dfn{prompt} to remind you that your input should be
  26 the name of a command to be run.  @xref{Minibuffer}, for full information
  27 on the features of the minibuffer.
  28
  29   You can use completion to enter a command name.  For example, to
  30 invoke the command @code{forward-char}, type:
  31
  32 @example
  33 M-x forward-char @key{RET}
  34 @end example
  35 or
  36 @example
  37 M-x fo @key{TAB} c @key{RET}
  38 @end example
  39
  40 @noindent
  41 After you type in @code{M-x fo TAB} emacs will give you a possible list of
  42 completions from which you can choose. Note that @code{forward-char} is the
  43 same command that you invoke with the key @kbd{C-f}.  You can call any
  44 command (interactively callable function) defined in Emacs by its name
  45 using @kbd{M-x} regardless of whether or not any keys are bound to it.
  46
  47   If you type @kbd{C-g} while Emacs reads the command name, you cancel
  48 the @kbd{M-x} command and get out of the minibuffer, ending up at top level.
  49
  50   To pass a numeric argument to a command you are invoking with
  51 @kbd{M-x}, specify the numeric argument before the @kbd{M-x}.  @kbd{M-x}
  52 passes the argument along to the function that it calls.  The argument
  53 value appears in the prompt while the command name is being read.
  54
  55 @findex interactive
  56 You can use the command @code{M-x interactive} to specify a way of
  57 parsing arguments for interactive use of a function.  For example, write:
  58
  59 @example
  60   (defun foo (arg) "Doc string" (interactive "p") ...use arg...)
  61 @end example
  62
  63 to make @code{arg} be the prefix argument when @code{foo} is called as a
  64 command.  The call to @code{interactive} is actually a declaration
  65 rather than a function; it tells @code{call-interactively} how to read
  66 arguments to pass to the function.  When actually called, @code{interactive}
  67 returns @code{nil}.
  68
  69 The argument of @var{interactive} is usually a string containing a code
  70 letter followed by a prompt.  Some code letters do not use I/O to get
  71 the argument and do not need prompts.  To prompt for multiple arguments,
  72 you must provide a code letter, its prompt, a newline, and another code
  73 letter, and so forth.  If the argument is not a string, it is evaluated
  74 to get a list of arguments to pass to the function.  If you do not provide an
  75 argument to @code{interactive}, no arguments are passed when calling
  76 interactively.
  77
  78 Available code letters are:
  79
  80 @table @code
  81 @item a
  82 Function name: symbol with a function definition
  83 @item b
  84 Name of existing buffer
  85 @item B
  86 Name of buffer, possibly nonexistent
  87 @item c
  88 Character
  89 @item C
  90 Command name: symbol with interactive function definition
  91 @item d
  92 Value of point as number (does not do I/O)
  93 @item D
  94 Directory name
  95 @item e
  96 Last mouse event
  97 @item f
  98 Existing file name
  99 @item F
 100 Possibly nonexistent file name
 101 @item k
 102 Key sequence (string)
 103 @item m
 104 Value of mark as number (does not do I/O)
 105 @item n
 106 Number read using minibuffer
 107 @item N
 108 Prefix arg converted to number, or if none, do like code @code{n}
 109 @item p
 110 Prefix arg converted to number (does not do I/O)
 111 @item P
 112 Prefix arg in raw form (does not do I/O)
 113 @item r
 114 Region: point and mark as two numeric arguments, smallest first (does
 115 not do I/O)
 116 @item s
 117 Any string
 118 @item S
 119 Any symbol
 120 @item v
 121 Variable name: symbol that is @code{user-variable-p}
 122 @item x
 123 Lisp expression read but not evaluated
 124 @item X
 125 Lisp expression read and evaluated
 126 @end table
 127
 128 In addition, if the string begins with @samp{*}, an error is
 129 signaled if the buffer is read-only.  This happens before reading any
 130 arguments.  If the string begins with @samp{@@}, the window the mouse is
 131 over is selected before anything else is done.  You may use both
 132 @samp{@@} and @samp{*}; they are processed in the order that they appear.
 133
 134 Normally, when describing a command that is run by name, we omit the
 135 @key{RET} that is needed to terminate the name.  Thus we may refer to
 136 @kbd{M-x auto-fill-mode} rather than @kbd{M-x auto-fill-mode} @key{RET}.
 137 We mention the @key{RET} only when it is necessary to emphasize its
 138 presence, for example, when describing a sequence of input that contains
 139 a command name and arguments that follow it.
 140
 141 @findex execute-extended-command
 142   @kbd{M-x} is defined to run the command @code{execute-extended-command},
 143 which is responsible for reading the name of another command and invoking
 144 it.