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