Mercurial > emacs
annotate doc/emacs/programs.texi @ 101907:459248f6207e
(Holidays, Displaying the Diary): Update for new marker defaults.
author | Glenn Morris <rgm@gnu.org> |
---|---|
date | Mon, 09 Feb 2009 07:50:44 +0000 |
parents | cb5d2387102c |
children | 6813b59a55fa |
rev | line source |
---|---|
84262 | 1 @c This is part of the Emacs manual. |
2 @c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 1999, 2000, | |
100974 | 3 @c 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. |
84262 | 4 @c See file emacs.texi for copying conditions. |
5 @node Programs, Building, Text, Top | |
6 @chapter Editing Programs | |
7 @cindex Lisp editing | |
8 @cindex C editing | |
9 @cindex program editing | |
10 | |
11 Emacs provides many features to facilitate editing programs. Some | |
12 of these features can | |
13 | |
14 @itemize @bullet | |
15 @item | |
16 Find or move over top-level definitions (@pxref{Defuns}). | |
17 @item | |
18 Apply the usual indentation conventions of the language | |
19 (@pxref{Program Indent}). | |
20 @item | |
21 Balance parentheses (@pxref{Parentheses}). | |
22 @item | |
23 Insert, kill or align comments (@pxref{Comments}). | |
24 @item | |
25 Highlight program syntax (@pxref{Font Lock}). | |
26 @end itemize | |
27 | |
28 This chapter describes these features and many more. | |
29 | |
30 @menu | |
31 * Program Modes:: Major modes for editing programs. | |
32 * Defuns:: Commands to operate on major top-level parts | |
33 of a program. | |
34 * Program Indent:: Adjusting indentation to show the nesting. | |
35 * Parentheses:: Commands that operate on parentheses. | |
36 * Comments:: Inserting, killing, and aligning comments. | |
37 * Documentation:: Getting documentation of functions you plan to call. | |
38 * Hideshow:: Displaying blocks selectively. | |
39 * Symbol Completion:: Completion on symbol names of your program or language. | |
40 * Glasses:: Making identifiersLikeThis more readable. | |
41 * Misc for Programs:: Other Emacs features useful for editing programs. | |
42 * C Modes:: Special commands of C, C++, Objective-C, | |
43 Java, and Pike modes. | |
44 * Asm Mode:: Asm mode and its special features. | |
45 @ifnottex | |
46 * Fortran:: Fortran mode and its special features. | |
47 @end ifnottex | |
48 @end menu | |
49 | |
50 @node Program Modes | |
51 @section Major Modes for Programming Languages | |
52 @cindex modes for programming languages | |
53 | |
54 Emacs has specialized major modes for various programming languages. | |
55 @xref{Major Modes}. A programming language major mode typically | |
56 specifies the syntax of expressions, the customary rules for | |
57 indentation, how to do syntax highlighting for the language, and how | |
99317
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
58 to find the beginning or end of a function definition. It often |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
59 customizes or provides facilities for compiling and debugging programs |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
60 as well. |
84262 | 61 |
62 Ideally, Emacs should provide a major mode for each programming | |
63 language that you might want to edit; if it doesn't have a mode for | |
64 your favorite language, you can contribute one. But often the mode | |
65 for one language can serve for other syntactically similar languages. | |
66 The major mode for language @var{l} is called @code{@var{l}-mode}, | |
67 and you can select it by typing @kbd{M-x @var{l}-mode @key{RET}}. | |
68 @xref{Choosing Modes}. | |
69 | |
70 @cindex Perl mode | |
71 @cindex Icon mode | |
72 @cindex Makefile mode | |
73 @cindex Tcl mode | |
74 @cindex CPerl mode | |
75 @cindex DSSSL mode | |
76 @cindex Octave mode | |
77 @cindex Metafont mode | |
78 @cindex Modula2 mode | |
79 @cindex Prolog mode | |
80 @cindex Python mode | |
100334
2f23225ada6b
(Program Modes): Mention Ruby mode.
Chong Yidong <cyd@stupidchicken.com>
parents:
100077
diff
changeset
|
81 @cindex Ruby mode |
84262 | 82 @cindex Simula mode |
83 @cindex VHDL mode | |
84 @cindex M4 mode | |
85 @cindex Shell-script mode | |
86 @cindex Delphi mode | |
87 @cindex PostScript mode | |
88 @cindex Conf mode | |
89 @cindex DNS mode | |
99317
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
90 The existing programming language major modes include Lisp, Scheme |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
91 (a variant of Lisp) and the Scheme-based DSSSL expression language, |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
92 Ada, ASM, AWK, C, C++, Delphi (Object Pascal), Fortran, Icon, IDL |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
93 (CORBA), IDLWAVE, Java, Metafont (@TeX{}'s companion for font |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
94 creation), Modula2, Objective-C, Octave, Pascal, Perl, Pike, |
100334
2f23225ada6b
(Program Modes): Mention Ruby mode.
Chong Yidong <cyd@stupidchicken.com>
parents:
100077
diff
changeset
|
95 PostScript, Prolog, Python, Ruby, Simula, Tcl, and VHDL. An |
2f23225ada6b
(Program Modes): Mention Ruby mode.
Chong Yidong <cyd@stupidchicken.com>
parents:
100077
diff
changeset
|
96 alternative mode for Perl is called CPerl mode. Modes are available |
2f23225ada6b
(Program Modes): Mention Ruby mode.
Chong Yidong <cyd@stupidchicken.com>
parents:
100077
diff
changeset
|
97 for the scripting languages of the common GNU and Unix shells, VMS |
2f23225ada6b
(Program Modes): Mention Ruby mode.
Chong Yidong <cyd@stupidchicken.com>
parents:
100077
diff
changeset
|
98 DCL, and MS-DOS/MS-Windows @samp{BAT} files. There are also major |
2f23225ada6b
(Program Modes): Mention Ruby mode.
Chong Yidong <cyd@stupidchicken.com>
parents:
100077
diff
changeset
|
99 modes for editing makefiles, DNS master files, and various sorts of |
99317
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
100 configuration files. |
84262 | 101 |
102 @kindex DEL @r{(programming modes)} | |
103 @findex c-electric-backspace | |
104 In most programming languages, indentation should vary from line to | |
105 line to illustrate the structure of the program. So the major modes | |
106 for programming languages arrange for @key{TAB} to update the | |
99317
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
107 indentation of the current line (@pxref{Program Indent}). They also |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
108 rebind @key{DEL} to treat a tab as if it were the equivalent number of |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
109 spaces; this lets you delete one column of indentation without |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
110 worrying whether the whitespace consists of spaces or tabs. Use |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
111 @kbd{C-b C-d} to delete a tab character before point, in these modes. |
84262 | 112 |
113 Separate manuals are available for the modes for Ada (@pxref{Top, , Ada | |
114 Mode, ada-mode, Ada Mode}), C/C++/Objective C/Java/Corba IDL/Pike/AWK | |
115 (@pxref{Top, , CC Mode, ccmode, CC Mode}) and the IDLWAVE modes | |
116 (@pxref{Top, , IDLWAVE, idlwave, IDLWAVE User Manual}). For Fortran | |
117 mode, see | |
118 @iftex | |
119 @ref{Fortran,,, emacs-xtra, Specialized Emacs Features}. | |
120 @end iftex | |
121 @ifnottex | |
122 @ref{Fortran}. | |
123 @end ifnottex | |
124 | |
125 @cindex mode hook | |
126 @vindex c-mode-hook | |
127 @vindex lisp-mode-hook | |
128 @vindex emacs-lisp-mode-hook | |
129 @vindex lisp-interaction-mode-hook | |
130 @vindex scheme-mode-hook | |
131 Turning on a major mode runs a normal hook called the @dfn{mode | |
132 hook}, which is the value of a Lisp variable. Each major mode has a | |
133 mode hook, and the hook's name is always made from the mode command's | |
134 name by adding @samp{-hook}. For example, turning on C mode runs the | |
135 hook @code{c-mode-hook}, while turning on Lisp mode runs the hook | |
136 @code{lisp-mode-hook}. The purpose of the mode hook is to give you a | |
137 place to set up customizations for that major mode. @xref{Hooks}. | |
138 | |
139 @node Defuns | |
140 @section Top-Level Definitions, or Defuns | |
141 | |
99317
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
142 In Emacs, a major definition at the top level in the buffer, such as |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
143 a function, is called a @dfn{defun}. The name comes from Lisp, but in |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
144 Emacs we use it for all languages. |
84262 | 145 |
146 @menu | |
147 * Left Margin Paren:: An open-paren or similar opening delimiter | |
148 starts a defun if it is at the left margin. | |
149 * Moving by Defuns:: Commands to move over or mark a major definition. | |
150 * Imenu:: Making buffer indexes as menus. | |
151 * Which Function:: Which Function mode shows which function you are in. | |
152 @end menu | |
153 | |
154 @node Left Margin Paren | |
155 @subsection Left Margin Convention | |
156 | |
157 @cindex open-parenthesis in leftmost column | |
158 @cindex ( in leftmost column | |
99317
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
159 Many programming-language modes assume by default that any opening |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
160 delimiter found at the left margin is the start of a top-level |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
161 definition, or defun. Therefore, @strong{don't put an opening |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
162 delimiter at the left margin unless it should have that significance}. |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
163 For instance, never put an open-parenthesis at the left margin in a |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
164 Lisp file unless it is the start of a top-level list. |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
165 |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
166 The convention speeds up many Emacs operations, which would |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
167 otherwise have to scan back to the beginning of the buffer to analyze |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
168 the syntax of the code. |
84262 | 169 |
170 If you don't follow this convention, not only will you have trouble | |
171 when you explicitly use the commands for motion by defuns; other | |
99317
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
172 features that use them will also give you trouble. This includes the |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
173 indentation commands (@pxref{Program Indent}) and Font Lock mode |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
174 (@pxref{Font Lock}). |
84262 | 175 |
176 The most likely problem case is when you want an opening delimiter | |
177 at the start of a line inside a string. To avoid trouble, put an | |
178 escape character (@samp{\}, in C and Emacs Lisp, @samp{/} in some | |
179 other Lisp dialects) before the opening delimiter. This will not | |
180 affect the contents of the string, but will prevent that opening | |
181 delimiter from starting a defun. Here's an example: | |
182 | |
183 @example | |
184 (insert "Foo: | |
185 \(bar) | |
186 ") | |
187 @end example | |
188 | |
189 To help you catch violations of this convention, Font Lock mode | |
190 highlights confusing opening delimiters (those that ought to be | |
191 quoted) in bold red. | |
192 | |
99317
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
193 If you need to override this convention, you can do so by setting |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
194 this user option: |
84262 | 195 |
196 @defvar open-paren-in-column-0-is-defun-start | |
197 If this user option is set to @code{t} (the default), opening | |
198 parentheses or braces at column zero always start defuns. When it's | |
199 @code{nil}, defuns are found by searching for parens or braces at the | |
200 outermost level. | |
201 @end defvar | |
202 | |
99317
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
203 Usually, you should leave this option at its default value of |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
204 @code{t}. If your buffer contains parentheses or braces in column |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
205 zero which don't start defuns, and it is somehow impractical to remove |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
206 these parentheses or braces, it might be helpful to set the option to |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
207 @code{nil}. Be aware that this might make scrolling and display in |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
208 large buffers quite sluggish. Furthermore, the parentheses and braces |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
209 must be correctly matched throughout the buffer for it to work |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
210 properly. |
84262 | 211 |
212 @node Moving by Defuns | |
213 @subsection Moving by Defuns | |
214 @cindex defuns | |
215 | |
216 These commands move point or set up the region based on top-level | |
217 major definitions, also called @dfn{defuns}. | |
218 | |
219 @table @kbd | |
220 @item C-M-a | |
221 Move to beginning of current or preceding defun | |
222 (@code{beginning-of-defun}). | |
223 @item C-M-e | |
224 Move to end of current or following defun (@code{end-of-defun}). | |
225 @item C-M-h | |
226 Put region around whole current or following defun (@code{mark-defun}). | |
227 @end table | |
228 | |
229 @cindex move to beginning or end of function | |
230 @cindex function, move to beginning or end | |
231 @kindex C-M-a | |
232 @kindex C-M-e | |
233 @kindex C-M-h | |
234 @findex beginning-of-defun | |
235 @findex end-of-defun | |
236 @findex mark-defun | |
237 The commands to move to the beginning and end of the current defun | |
238 are @kbd{C-M-a} (@code{beginning-of-defun}) and @kbd{C-M-e} | |
239 (@code{end-of-defun}). If you repeat one of these commands, or use a | |
240 positive numeric argument, each repetition moves to the next defun in | |
241 the direction of motion. | |
242 | |
243 @kbd{C-M-a} with a negative argument @minus{}@var{n} moves forward | |
244 @var{n} times to the next beginning of a defun. This is not exactly | |
245 the same place that @kbd{C-M-e} with argument @var{n} would move to; | |
246 the end of this defun is not usually exactly the same place as the | |
247 beginning of the following defun. (Whitespace, comments, and perhaps | |
248 declarations can separate them.) Likewise, @kbd{C-M-e} with a | |
249 negative argument moves back to an end of a defun, which is not quite | |
250 the same as @kbd{C-M-a} with a positive argument. | |
251 | |
252 @kindex C-M-h @r{(C mode)} | |
253 @findex c-mark-function | |
93357
50a71f4146c8
(Moving by Defuns, Expressions, Comment Commands): Describe Transient
Chong Yidong <cyd@stupidchicken.com>
parents:
88056
diff
changeset
|
254 To operate on the current defun, use @kbd{C-M-h} |
50a71f4146c8
(Moving by Defuns, Expressions, Comment Commands): Describe Transient
Chong Yidong <cyd@stupidchicken.com>
parents:
88056
diff
changeset
|
255 (@code{mark-defun}), which sets the mark at the end of the current |
50a71f4146c8
(Moving by Defuns, Expressions, Comment Commands): Describe Transient
Chong Yidong <cyd@stupidchicken.com>
parents:
88056
diff
changeset
|
256 defun and puts point at its beginning. @xref{Marking Objects}. This |
50a71f4146c8
(Moving by Defuns, Expressions, Comment Commands): Describe Transient
Chong Yidong <cyd@stupidchicken.com>
parents:
88056
diff
changeset
|
257 is the easiest way to get ready to kill the defun in order to move it |
50a71f4146c8
(Moving by Defuns, Expressions, Comment Commands): Describe Transient
Chong Yidong <cyd@stupidchicken.com>
parents:
88056
diff
changeset
|
258 to a different place in the file. If you use the command while point |
50a71f4146c8
(Moving by Defuns, Expressions, Comment Commands): Describe Transient
Chong Yidong <cyd@stupidchicken.com>
parents:
88056
diff
changeset
|
259 is between defuns, it uses the following defun. If you use the |
50a71f4146c8
(Moving by Defuns, Expressions, Comment Commands): Describe Transient
Chong Yidong <cyd@stupidchicken.com>
parents:
88056
diff
changeset
|
260 command while the mark is already active, it sets the mark but does |
50a71f4146c8
(Moving by Defuns, Expressions, Comment Commands): Describe Transient
Chong Yidong <cyd@stupidchicken.com>
parents:
88056
diff
changeset
|
261 not move point; furthermore, each successive use of @kbd{C-M-h} |
50a71f4146c8
(Moving by Defuns, Expressions, Comment Commands): Describe Transient
Chong Yidong <cyd@stupidchicken.com>
parents:
88056
diff
changeset
|
262 extends the end of the region to include one more defun. |
84262 | 263 |
264 In C mode, @kbd{C-M-h} runs the function @code{c-mark-function}, | |
265 which is almost the same as @code{mark-defun}; the difference is that | |
266 it backs up over the argument declarations, function name and returned | |
267 data type so that the entire C function is inside the region. This is | |
268 an example of how major modes adjust the standard key bindings so that | |
269 they do their standard jobs in a way better fitting a particular | |
270 language. Other major modes may replace any or all of these key | |
271 bindings for that purpose. | |
272 | |
273 @node Imenu | |
274 @subsection Imenu | |
275 @cindex index of buffer definitions | |
276 @cindex buffer definitions index | |
277 | |
278 The Imenu facility offers a way to find the major definitions in | |
279 a file by name. It is also useful in text formatter major modes, | |
280 where it treats each chapter, section, etc., as a definition. | |
281 (@xref{Tags}, for a more powerful feature that handles multiple files | |
282 together.) | |
283 | |
284 @findex imenu | |
285 If you type @kbd{M-x imenu}, it reads the name of a definition using | |
286 the minibuffer, then moves point to that definition. You can use | |
287 completion to specify the name; the command always displays the whole | |
288 list of valid names. | |
289 | |
290 @findex imenu-add-menubar-index | |
291 Alternatively, you can bind the command @code{imenu} to a mouse | |
292 click. Then it displays mouse menus for you to select a definition | |
293 name. You can also add the buffer's index to the menu bar by calling | |
294 @code{imenu-add-menubar-index}. If you want to have this menu bar | |
295 item available for all buffers in a certain major mode, you can do | |
296 this by adding @code{imenu-add-menubar-index} to its mode hook. But | |
297 if you have done that, you will have to wait a little while each time | |
298 you visit a file in that mode, while Emacs finds all the definitions | |
299 in that buffer. | |
300 | |
301 @vindex imenu-auto-rescan | |
302 When you change the contents of a buffer, if you add or delete | |
303 definitions, you can update the buffer's index based on the | |
304 new contents by invoking the @samp{*Rescan*} item in the menu. | |
305 Rescanning happens automatically if you set @code{imenu-auto-rescan} to | |
306 a non-@code{nil} value. There is no need to rescan because of small | |
307 changes in the text. | |
308 | |
309 @vindex imenu-sort-function | |
310 You can customize the way the menus are sorted by setting the | |
311 variable @code{imenu-sort-function}. By default, names are ordered as | |
312 they occur in the buffer; if you want alphabetic sorting, use the | |
313 symbol @code{imenu--sort-by-name} as the value. You can also | |
314 define your own comparison function by writing Lisp code. | |
315 | |
316 Imenu provides the information to guide Which Function mode | |
317 @ifnottex | |
318 (@pxref{Which Function}). | |
319 @end ifnottex | |
320 @iftex | |
321 (see below). | |
322 @end iftex | |
323 The Speedbar can also use it (@pxref{Speedbar}). | |
324 | |
325 @node Which Function | |
326 @subsection Which Function Mode | |
327 @cindex current function name in mode line | |
328 | |
329 Which Function mode is a minor mode that displays the current | |
330 function name in the mode line, updating it as you move around in a | |
331 buffer. | |
332 | |
333 @findex which-function-mode | |
334 @vindex which-func-modes | |
335 To either enable or disable Which Function mode, use the command | |
99317
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
336 @kbd{M-x which-function-mode}. This command applies to all buffers, |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
337 both existing ones and those yet to be created. However, it takes |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
338 effect only in certain major modes, those listed in the value of |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
339 @code{which-func-modes}. If the value of @code{which-func-modes} is |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
340 @code{t} rather than a list of modes, then Which Function mode applies |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
341 to all major modes that know how to support it---in other words, all |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
342 the major modes that support Imenu. |
84262 | 343 |
344 @node Program Indent | |
345 @section Indentation for Programs | |
346 @cindex indentation for programs | |
347 | |
348 The best way to keep a program properly indented is to use Emacs to | |
99317
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
349 reindent it as you change it. Emacs has commands to indent either a |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
350 single line, a specified number of lines, or all of the lines inside a |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
351 single parenthetical grouping. |
84262 | 352 |
353 @menu | |
354 * Basic Indent:: Indenting a single line. | |
355 * Multi-line Indent:: Commands to reindent many lines at once. | |
356 * Lisp Indent:: Specifying how each Lisp function should be indented. | |
357 * C Indent:: Extra features for indenting C and related modes. | |
358 * Custom C Indent:: Controlling indentation style for C and related modes. | |
359 @end menu | |
360 | |
361 @cindex pretty-printer | |
362 Emacs also provides a Lisp pretty-printer in the library @code{pp}. | |
363 This program reformats a Lisp object with indentation chosen to look nice. | |
364 | |
365 @node Basic Indent | |
366 @subsection Basic Program Indentation Commands | |
367 | |
368 The basic indentation commands indent a single line according to the | |
369 usual conventions of the language you are editing. | |
370 | |
371 @table @kbd | |
372 @item @key{TAB} | |
373 Adjust indentation of current line. | |
374 @item C-j | |
375 Insert a newline, then adjust indentation of following line | |
376 (@code{newline-and-indent}). | |
377 @end table | |
378 | |
379 @kindex TAB @r{(programming modes)} | |
380 @findex c-indent-command | |
381 @findex indent-line-function | |
382 @findex indent-for-tab-command | |
99317
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
383 The basic indentation command is @key{TAB}. In any |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
384 programming-language major mode, @key{TAB} gives the current line the |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
385 correct indentation as determined from the previous lines. It does |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
386 this by inserting or deleting whitespace at the beginning of the |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
387 current line. If point was inside the whitespace at the beginning of |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
388 the line, @key{TAB} puts it at the end of that whitespace; otherwise, |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
389 @key{TAB} keeps point fixed with respect to the characters around it. |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
390 If the region is active (@pxref{Mark}), @key{TAB} indents every line |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
391 within the region instead of just the current line. The function that |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
392 @key{TAB} runs depends on the major mode; for instance, it is |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
393 @code{c-indent-line-or-region} in C mode. Each function is aware of |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
394 the syntax and conventions for its particular language. |
84262 | 395 |
396 Use @kbd{C-q @key{TAB}} to insert a tab character at point. | |
397 | |
398 @kindex C-j | |
399 @findex newline-and-indent | |
400 When entering lines of new code, use @kbd{C-j} | |
401 (@code{newline-and-indent}), which inserts a newline and then adjusts | |
402 indentation after it. (It also deletes any trailing whitespace which | |
99317
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
403 remains before the new newline.) For instance, @kbd{C-j} at the end |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
404 of a line creates a blank line with appropriate indentation. In |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
405 programming language modes, it is equivalent to @key{RET} @key{TAB}. |
84262 | 406 |
99317
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
407 When Emacs indents a line that starts within a parenthetical |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
408 grouping, it usually places the start of the line under the preceding |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
409 line within the group, or under the text after the parenthesis. If |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
410 you manually give one of these lines a nonstandard indentation, the |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
411 lines below will tend to follow it. This behavior is convenient in |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
412 cases where you have overridden the standard result of @key{TAB} |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
413 indentation (e.g., for aesthetic purposes). |
84262 | 414 |
99317
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
415 Many programming-language modes assume that an open-parenthesis, |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
416 open-brace or other opening delimiter at the left margin is the start |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
417 of a function. This assumption speeds up indentation commands. If |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
418 the text you are editing contains opening delimiters in column zero |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
419 that aren't the beginning of a functions---even if these delimiters |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
420 occur inside strings or comments---then you must set |
84262 | 421 @code{open-paren-in-column-0-is-defun-start}. @xref{Left Margin |
99317
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
422 Paren}. |
84262 | 423 |
99317
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
424 Normally, Emacs indents lines using an ``optimal'' mix of tab and |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
425 space characters. If you want Emacs to use spaces only, set |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
426 @code{indent-tabs-mode} (@pxref{Just Spaces}). |
84262 | 427 |
428 @node Multi-line Indent | |
429 @subsection Indenting Several Lines | |
430 | |
99317
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
431 Sometimes, you may want to reindent several lines of code at a time. |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
432 One way to do this is to use the mark; when the mark is active and the |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
433 region is non-empty, @key{TAB} indents every line within the region. |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
434 In addition, Emacs provides several other commands for indenting large |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
435 chunks of code: |
84262 | 436 |
437 @table @kbd | |
438 @item C-M-q | |
99317
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
439 Reindent all the lines within one parenthetical grouping. |
84262 | 440 @item C-M-\ |
441 Reindent all lines in the region (@code{indent-region}). | |
442 @item C-u @key{TAB} | |
443 Shift an entire parenthetical grouping rigidly sideways so that its | |
444 first line is properly indented. | |
445 @item M-x indent-code-rigidly | |
446 Shift all the lines in the region rigidly sideways, but do not alter | |
447 lines that start inside comments and strings. | |
448 @end table | |
449 | |
450 @kindex C-M-q | |
451 @findex indent-pp-sexp | |
99317
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
452 To reindent the contents of a single parenthetical grouping, |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
453 position point before the beginning of the grouping and type |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
454 @kbd{C-M-q}. This changes the relative indentation within the |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
455 grouping, without affecting its overall indentation (i.e., the |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
456 indentation of the line where the grouping starts). The function that |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
457 @kbd{C-M-q} runs depends on the major mode; it is |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
458 @code{indent-pp-sexp} in Lisp mode, @code{c-indent-exp} in C mode, |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
459 etc. To correct the overall indentation as well, type @key{TAB} |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
460 first. |
84262 | 461 |
99317
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
462 @kbd{C-M-\} (@code{indent-region}) applies @key{TAB} to the region. |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
463 This is useful when Transient Mark mode is disabled (@pxref{Persistent |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
464 Mark}), because in that case @key{TAB} does not act on the region. |
84262 | 465 |
466 @kindex C-u TAB | |
99317
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
467 If you like the relative indentation within a grouping but not the |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
468 indentation of its first line, move point to that first line and type |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
469 @kbd{C-u @key{TAB}}. In Lisp, C, and some other major modes, |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
470 @key{TAB} with a numeric argument reindents the current line as usual, |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
471 then reindents by the same amount all the lines in the parenthetical |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
472 grouping starting on the current line. It is clever, though, and does |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
473 not alter lines that start inside strings. Neither does it alter C |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
474 preprocessor lines when in C mode, but it does reindent any |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
475 continuation lines that may be attached to them. |
84262 | 476 |
477 @findex indent-code-rigidly | |
99317
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
478 The command @kbd{M-x indent-code-rigidly} rigidly shifts all the |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
479 lines in the region sideways, like @code{indent-rigidly} does |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
480 (@pxref{Indentation Commands}). It doesn't alter the indentation of |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
481 lines that start inside a string, unless the region also starts inside |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
482 that string. The prefix arg specifies the number of columns to |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
483 indent. |
84262 | 484 |
485 @node Lisp Indent | |
486 @subsection Customizing Lisp Indentation | |
487 @cindex customizing Lisp indentation | |
488 | |
489 The indentation pattern for a Lisp expression can depend on the function | |
490 called by the expression. For each Lisp function, you can choose among | |
491 several predefined patterns of indentation, or define an arbitrary one with | |
492 a Lisp program. | |
493 | |
494 The standard pattern of indentation is as follows: the second line of the | |
495 expression is indented under the first argument, if that is on the same | |
496 line as the beginning of the expression; otherwise, the second line is | |
497 indented underneath the function name. Each following line is indented | |
498 under the previous line whose nesting depth is the same. | |
499 | |
500 @vindex lisp-indent-offset | |
501 If the variable @code{lisp-indent-offset} is non-@code{nil}, it overrides | |
502 the usual indentation pattern for the second line of an expression, so that | |
503 such lines are always indented @code{lisp-indent-offset} more columns than | |
504 the containing list. | |
505 | |
506 @vindex lisp-body-indent | |
507 Certain functions override the standard pattern. Functions whose | |
508 names start with @code{def} treat the second lines as the start of | |
509 a @dfn{body}, by indenting the second line @code{lisp-body-indent} | |
510 additional columns beyond the open-parenthesis that starts the | |
511 expression. | |
512 | |
513 @cindex @code{lisp-indent-function} property | |
514 You can override the standard pattern in various ways for individual | |
515 functions, according to the @code{lisp-indent-function} property of | |
516 the function name. Normally you would use this for macro definitions | |
517 and specify it using the @code{declare} construct (@pxref{Defining | |
518 Macros,,, elisp, the Emacs Lisp Reference Manual}). | |
519 | |
520 @node C Indent | |
521 @subsection Commands for C Indentation | |
522 | |
523 Here are special features for indentation in C mode and related modes: | |
524 | |
525 @table @code | |
526 @item C-c C-q | |
527 @kindex C-c C-q @r{(C mode)} | |
528 @findex c-indent-defun | |
529 Reindent the current top-level function definition or aggregate type | |
530 declaration (@code{c-indent-defun}). | |
531 | |
532 @item C-M-q | |
533 @kindex C-M-q @r{(C mode)} | |
534 @findex c-indent-exp | |
535 Reindent each line in the balanced expression that follows point | |
536 (@code{c-indent-exp}). A prefix argument inhibits warning messages | |
537 about invalid syntax. | |
538 | |
539 @item @key{TAB} | |
540 @findex c-indent-command | |
541 Reindent the current line, and/or in some cases insert a tab character | |
542 (@code{c-indent-command}). | |
543 | |
544 @vindex c-tab-always-indent | |
545 If @code{c-tab-always-indent} is @code{t}, this command always reindents | |
546 the current line and does nothing else. This is the default. | |
547 | |
548 If that variable is @code{nil}, this command reindents the current line | |
549 only if point is at the left margin or in the line's indentation; | |
550 otherwise, it inserts a tab (or the equivalent number of spaces, | |
551 if @code{indent-tabs-mode} is @code{nil}). | |
552 | |
553 Any other value (not @code{nil} or @code{t}) means always reindent the | |
554 line, and also insert a tab if within a comment or a string. | |
555 @end table | |
556 | |
557 To reindent the whole current buffer, type @kbd{C-x h C-M-\}. This | |
558 first selects the whole buffer as the region, then reindents that | |
559 region. | |
560 | |
561 To reindent the current block, use @kbd{C-M-u C-M-q}. This moves | |
562 to the front of the block and then reindents it all. | |
563 | |
564 @node Custom C Indent | |
565 @subsection Customizing C Indentation | |
566 @cindex style (for indentation) | |
567 | |
568 C mode and related modes use a flexible mechanism for customizing | |
569 indentation. C mode indents a source line in two steps: first it | |
570 classifies the line syntactically according to its contents and | |
571 context; second, it determines the indentation offset associated by | |
572 your selected @dfn{style} with the syntactic construct and adds this | |
573 onto the indentation of the @dfn{anchor statement}. | |
574 | |
575 @table @kbd | |
576 @item C-c . @key{RET} @var{style} @key{RET} | |
577 Select a predefined style @var{style} (@code{c-set-style}). | |
578 @end table | |
579 | |
580 A @dfn{style} is a named collection of customizations that can be | |
581 used in C mode and the related modes. @ref{Styles,,, ccmode, The CC | |
582 Mode Manual}, for a complete description. Emacs comes with several | |
583 predefined styles, including @code{gnu}, @code{k&r}, @code{bsd}, | |
584 @code{stroustrup}, @code{linux}, @code{python}, @code{java}, | |
585 @code{whitesmith}, @code{ellemtel}, and @code{awk}. Some of these | |
586 styles are primarily intended for one language, but any of them can be | |
587 used with any of the languages supported by these modes. To find out | |
588 what a style looks like, select it and reindent some code, e.g., by | |
589 typing @key{C-M-q} at the start of a function definition. | |
590 | |
591 @kindex C-c . @r{(C mode)} | |
592 @findex c-set-style | |
593 To choose a style for the current buffer, use the command @w{@kbd{C-c | |
594 .}}. Specify a style name as an argument (case is not significant). | |
595 This command affects the current buffer only, and it affects only | |
596 future invocations of the indentation commands; it does not reindent | |
597 the code already in the buffer. To reindent the whole buffer in the | |
598 new style, you can type @kbd{C-x h C-M-\}. | |
599 | |
600 @vindex c-default-style | |
601 You can also set the variable @code{c-default-style} to specify the | |
602 default style for various major modes. Its value should be either the | |
603 style's name (a string) or an alist, in which each element specifies | |
604 one major mode and which indentation style to use for it. For | |
605 example, | |
606 | |
607 @example | |
608 (setq c-default-style | |
609 '((java-mode . "java") (awk-mode . "awk") (other . "gnu"))) | |
610 @end example | |
611 | |
612 @noindent | |
613 specifies explicit choices for Java and AWK modes, and the default | |
614 @samp{gnu} style for the other C-like modes. (These settings are | |
615 actually the defaults.) This variable takes effect when you select | |
616 one of the C-like major modes; thus, if you specify a new default | |
617 style for Java mode, you can make it take effect in an existing Java | |
618 mode buffer by typing @kbd{M-x java-mode} there. | |
619 | |
620 The @code{gnu} style specifies the formatting recommended by the GNU | |
621 Project for C; it is the default, so as to encourage use of our | |
622 recommended style. | |
623 | |
624 @xref{Indentation Engine Basics,,, ccmode, the CC Mode Manual}, and | |
625 @ref{Customizing Indentation,,, ccmode, the CC Mode Manual}, for more | |
626 information on customizing indentation for C and related modes, | |
627 including how to override parts of an existing style and how to define | |
628 your own styles. | |
629 | |
630 @node Parentheses | |
631 @section Commands for Editing with Parentheses | |
632 | |
633 @findex check-parens | |
634 @cindex unbalanced parentheses and quotes | |
635 This section describes the commands and features that take advantage | |
636 of the parenthesis structure in a program, or help you keep it | |
637 balanced. | |
638 | |
639 When talking about these facilities, the term ``parenthesis'' also | |
640 includes braces, brackets, or whatever delimiters are defined to match | |
641 in pairs. The major mode controls which delimiters are significant, | |
642 through the syntax table (@pxref{Syntax}). In Lisp, only parentheses | |
643 count; in C, these commands apply to braces and brackets too. | |
644 | |
645 You can use @kbd{M-x check-parens} to find any unbalanced | |
646 parentheses and unbalanced string quotes in the buffer. | |
647 | |
648 @menu | |
649 * Expressions:: Expressions with balanced parentheses. | |
650 * Moving by Parens:: Commands for moving up, down and across | |
651 in the structure of parentheses. | |
652 * Matching:: Insertion of a close-delimiter flashes matching open. | |
653 @end menu | |
654 | |
655 @node Expressions | |
656 @subsection Expressions with Balanced Parentheses | |
657 | |
658 @cindex sexp | |
659 @cindex expression | |
660 @cindex balanced expression | |
661 These commands deal with balanced expressions, also called | |
662 @dfn{sexps}@footnote{The word ``sexp'' is used to refer to an | |
663 expression in Lisp.}. | |
664 | |
665 @table @kbd | |
666 @item C-M-f | |
667 Move forward over a balanced expression (@code{forward-sexp}). | |
668 @item C-M-b | |
669 Move backward over a balanced expression (@code{backward-sexp}). | |
670 @item C-M-k | |
671 Kill balanced expression forward (@code{kill-sexp}). | |
672 @item C-M-t | |
673 Transpose expressions (@code{transpose-sexps}). | |
674 @item C-M-@@ | |
675 @itemx C-M-@key{SPC} | |
676 Put mark after following expression (@code{mark-sexp}). | |
677 @end table | |
678 | |
679 Each programming language major mode customizes the definition of | |
680 balanced expressions to suit that language. Balanced expressions | |
681 typically include symbols, numbers, and string constants, as well as | |
682 any pair of matching delimiters and their contents. Some languages | |
683 have obscure forms of expression syntax that nobody has bothered to | |
684 implement in Emacs. | |
685 | |
686 @cindex Control-Meta | |
687 By convention, the keys for these commands are all Control-Meta | |
688 characters. They usually act on expressions just as the corresponding | |
689 Meta characters act on words. For instance, the command @kbd{C-M-b} | |
690 moves backward over a balanced expression, just as @kbd{M-b} moves | |
691 back over a word. | |
692 | |
693 @kindex C-M-f | |
694 @kindex C-M-b | |
695 @findex forward-sexp | |
696 @findex backward-sexp | |
697 To move forward over a balanced expression, use @kbd{C-M-f} | |
698 (@code{forward-sexp}). If the first significant character after point | |
699 is an opening delimiter (@samp{(} in Lisp; @samp{(}, @samp{[} or | |
700 @samp{@{} in C), @kbd{C-M-f} moves past the matching closing | |
701 delimiter. If the character begins a symbol, string, or number, | |
702 @kbd{C-M-f} moves over that. | |
703 | |
704 The command @kbd{C-M-b} (@code{backward-sexp}) moves backward over a | |
705 balanced expression. The detailed rules are like those above for | |
706 @kbd{C-M-f}, but with directions reversed. If there are prefix | |
707 characters (single-quote, backquote and comma, in Lisp) preceding the | |
708 expression, @kbd{C-M-b} moves back over them as well. The balanced | |
709 expression commands move across comments as if they were whitespace, | |
710 in most modes. | |
711 | |
712 @kbd{C-M-f} or @kbd{C-M-b} with an argument repeats that operation the | |
713 specified number of times; with a negative argument, it moves in the | |
714 opposite direction. | |
715 | |
716 @cindex killing expressions | |
717 @kindex C-M-k | |
718 @findex kill-sexp | |
719 Killing a whole balanced expression can be done with @kbd{C-M-k} | |
720 (@code{kill-sexp}). @kbd{C-M-k} kills the characters that @kbd{C-M-f} | |
721 would move over. | |
722 | |
723 @cindex transposition of expressions | |
724 @kindex C-M-t | |
725 @findex transpose-sexps | |
726 A somewhat random-sounding command which is nevertheless handy is | |
727 @kbd{C-M-t} (@code{transpose-sexps}), which drags the previous | |
728 balanced expression across the next one. An argument serves as a | |
729 repeat count, moving the previous expression over that many following | |
730 ones. A negative argument drags the previous balanced expression | |
731 backwards across those before it (thus canceling out the effect of | |
732 @kbd{C-M-t} with a positive argument). An argument of zero, rather | |
733 than doing nothing, transposes the balanced expressions ending at or | |
734 after point and the mark. | |
735 | |
736 @kindex C-M-@@ | |
737 @kindex C-M-@key{SPC} | |
738 @findex mark-sexp | |
739 To set the region around the next balanced expression in the buffer, | |
93357
50a71f4146c8
(Moving by Defuns, Expressions, Comment Commands): Describe Transient
Chong Yidong <cyd@stupidchicken.com>
parents:
88056
diff
changeset
|
740 use @kbd{C-M-@key{SPC}} (@code{mark-sexp}), which sets mark at the |
50a71f4146c8
(Moving by Defuns, Expressions, Comment Commands): Describe Transient
Chong Yidong <cyd@stupidchicken.com>
parents:
88056
diff
changeset
|
741 same place that @kbd{C-M-f} would move to. @kbd{C-M-@key{SPC}} treats |
50a71f4146c8
(Moving by Defuns, Expressions, Comment Commands): Describe Transient
Chong Yidong <cyd@stupidchicken.com>
parents:
88056
diff
changeset
|
742 numeric arguments in the same way as @kbd{C-M-f}; in particular, a |
50a71f4146c8
(Moving by Defuns, Expressions, Comment Commands): Describe Transient
Chong Yidong <cyd@stupidchicken.com>
parents:
88056
diff
changeset
|
743 negative argument puts the mark at the beginning of the previous |
50a71f4146c8
(Moving by Defuns, Expressions, Comment Commands): Describe Transient
Chong Yidong <cyd@stupidchicken.com>
parents:
88056
diff
changeset
|
744 balanced expression. The alias @kbd{C-M-@@} is equivalent to |
50a71f4146c8
(Moving by Defuns, Expressions, Comment Commands): Describe Transient
Chong Yidong <cyd@stupidchicken.com>
parents:
88056
diff
changeset
|
745 @kbd{C-M-@key{SPC}}. While the mark is active, each successive use of |
50a71f4146c8
(Moving by Defuns, Expressions, Comment Commands): Describe Transient
Chong Yidong <cyd@stupidchicken.com>
parents:
88056
diff
changeset
|
746 @kbd{C-M-@key{SPC}} extends the region by shifting the mark by one |
50a71f4146c8
(Moving by Defuns, Expressions, Comment Commands): Describe Transient
Chong Yidong <cyd@stupidchicken.com>
parents:
88056
diff
changeset
|
747 sexp. |
84262 | 748 |
749 In languages that use infix operators, such as C, it is not possible | |
750 to recognize all balanced expressions as such because there can be | |
751 multiple possibilities at a given position. For example, C mode does | |
752 not treat @samp{foo + bar} as a single expression, even though it | |
753 @emph{is} one C expression; instead, it recognizes @samp{foo} as one | |
754 expression and @samp{bar} as another, with the @samp{+} as punctuation | |
755 between them. Both @samp{foo + bar} and @samp{foo} are legitimate | |
756 choices for ``the expression following point'' when point is at the | |
757 @samp{f}, so the expression commands must perforce choose one or the | |
758 other to operate on. Note that @samp{(foo + bar)} is recognized as a | |
759 single expression in C mode, because of the parentheses. | |
760 | |
761 @node Moving by Parens | |
762 @subsection Moving in the Parenthesis Structure | |
763 | |
764 @cindex parenthetical groupings | |
765 @cindex parentheses, moving across | |
766 @cindex matching parenthesis and braces, moving to | |
767 @cindex braces, moving across | |
768 @cindex list commands | |
99956
6eac7f3fceba
(Moving by Parens): Clarify that parens inside strings and comments are
Alan Mackenzie <acm@muc.de>
parents:
99317
diff
changeset
|
769 |
84262 | 770 The Emacs commands for handling parenthetical groupings see nothing |
771 except parentheses (or whatever characters must balance in the | |
99956
6eac7f3fceba
(Moving by Parens): Clarify that parens inside strings and comments are
Alan Mackenzie <acm@muc.de>
parents:
99317
diff
changeset
|
772 language you are working with). They ignore strings and comments |
6eac7f3fceba
(Moving by Parens): Clarify that parens inside strings and comments are
Alan Mackenzie <acm@muc.de>
parents:
99317
diff
changeset
|
773 (including any parentheses within them) and ignore parentheses quoted |
6eac7f3fceba
(Moving by Parens): Clarify that parens inside strings and comments are
Alan Mackenzie <acm@muc.de>
parents:
99317
diff
changeset
|
774 by an escape character. They are mainly intended for editing |
84262 | 775 programs, but can be useful for editing any text that has parentheses. |
776 They are sometimes called ``list'' commands because in Lisp these | |
777 groupings are lists. | |
778 | |
99956
6eac7f3fceba
(Moving by Parens): Clarify that parens inside strings and comments are
Alan Mackenzie <acm@muc.de>
parents:
99317
diff
changeset
|
779 These commands assume that the starting point is not inside a string |
6eac7f3fceba
(Moving by Parens): Clarify that parens inside strings and comments are
Alan Mackenzie <acm@muc.de>
parents:
99317
diff
changeset
|
780 or a comment. Sometimes you can invoke them usefully from one of |
6eac7f3fceba
(Moving by Parens): Clarify that parens inside strings and comments are
Alan Mackenzie <acm@muc.de>
parents:
99317
diff
changeset
|
781 these places (for example, when you have a parenthesised clause in a |
6eac7f3fceba
(Moving by Parens): Clarify that parens inside strings and comments are
Alan Mackenzie <acm@muc.de>
parents:
99317
diff
changeset
|
782 comment) but this is unreliable. |
6eac7f3fceba
(Moving by Parens): Clarify that parens inside strings and comments are
Alan Mackenzie <acm@muc.de>
parents:
99317
diff
changeset
|
783 |
84262 | 784 @table @kbd |
785 @item C-M-n | |
786 Move forward over a parenthetical group (@code{forward-list}). | |
787 @item C-M-p | |
788 Move backward over a parenthetical group (@code{backward-list}). | |
789 @item C-M-u | |
790 Move up in parenthesis structure (@code{backward-up-list}). | |
791 @item C-M-d | |
792 Move down in parenthesis structure (@code{down-list}). | |
793 @end table | |
794 | |
795 @kindex C-M-n | |
796 @kindex C-M-p | |
797 @findex forward-list | |
798 @findex backward-list | |
799 The ``list'' commands @kbd{C-M-n} (@code{forward-list}) and | |
99956
6eac7f3fceba
(Moving by Parens): Clarify that parens inside strings and comments are
Alan Mackenzie <acm@muc.de>
parents:
99317
diff
changeset
|
800 @kbd{C-M-p} (@code{backward-list}) move forward or backward over one |
6eac7f3fceba
(Moving by Parens): Clarify that parens inside strings and comments are
Alan Mackenzie <acm@muc.de>
parents:
99317
diff
changeset
|
801 (or @var{n}) parenthetical groupings. |
84262 | 802 |
803 @kindex C-M-u | |
804 @findex backward-up-list | |
805 @kbd{C-M-n} and @kbd{C-M-p} try to stay at the same level in the | |
806 parenthesis structure. To move @emph{up} one (or @var{n}) levels, use | |
807 @kbd{C-M-u} (@code{backward-up-list}). @kbd{C-M-u} moves backward up | |
808 past one unmatched opening delimiter. A positive argument serves as a | |
809 repeat count; a negative argument reverses the direction of motion, so | |
810 that the command moves forward and up one or more levels. | |
811 | |
812 @kindex C-M-d | |
813 @findex down-list | |
814 To move @emph{down} in the parenthesis structure, use @kbd{C-M-d} | |
815 (@code{down-list}). In Lisp mode, where @samp{(} is the only opening | |
816 delimiter, this is nearly the same as searching for a @samp{(}. An | |
817 argument specifies the number of levels to go down. | |
818 | |
819 @node Matching | |
820 @subsection Automatic Display Of Matching Parentheses | |
821 @cindex matching parentheses | |
822 @cindex parentheses, displaying matches | |
823 | |
824 The Emacs parenthesis-matching feature is designed to show | |
825 automatically how parentheses (and other matching delimiters) match in | |
826 the text. Whenever you type a self-inserting character that is a | |
827 closing delimiter, the cursor moves momentarily to the location of the | |
828 matching opening delimiter, provided that is on the screen. If it is | |
829 not on the screen, Emacs displays some of the text near it in the echo | |
830 area. Either way, you can tell which grouping you are closing off. | |
831 | |
832 If the opening delimiter and closing delimiter are mismatched---such | |
833 as in @samp{[x)}---a warning message is displayed in the echo area. | |
834 | |
835 @vindex blink-matching-paren | |
836 @vindex blink-matching-paren-distance | |
837 @vindex blink-matching-delay | |
838 Three variables control parenthesis match display: | |
839 | |
840 @code{blink-matching-paren} turns the feature on or off: @code{nil} | |
841 disables it, but the default is @code{t} to enable match display. | |
842 | |
843 @code{blink-matching-delay} says how many seconds to leave the | |
844 cursor on the matching opening delimiter, before bringing it back to | |
845 the real location of point; the default is 1, but on some systems it | |
846 is useful to specify a fraction of a second. | |
847 | |
848 @code{blink-matching-paren-distance} specifies how many characters | |
849 back to search to find the matching opening delimiter. If the match | |
850 is not found in that distance, scanning stops, and nothing is displayed. | |
851 This is to prevent the scan for the matching delimiter from wasting | |
852 lots of time when there is no match. The default is 25600. | |
853 | |
854 @cindex Show Paren mode | |
855 @cindex highlighting matching parentheses | |
856 @findex show-paren-mode | |
857 Show Paren mode provides a more powerful kind of automatic matching. | |
99317
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
858 Whenever point is before an opening delimiter or after a closing |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
859 delimiter, both that delimiter and its opposite delimiter are |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
860 highlighted. Use the command @kbd{M-x show-paren-mode} to enable or |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
861 disable this mode. |
84262 | 862 |
863 Show Paren mode uses the faces @code{show-paren-match} and | |
864 @code{show-paren-mismatch} to highlight parentheses; you can customize | |
865 them to control how highlighting looks. @xref{Face Customization}. | |
866 | |
867 @node Comments | |
868 @section Manipulating Comments | |
869 @cindex comments | |
870 | |
871 Because comments are such an important part of programming, Emacs | |
872 provides special commands for editing and inserting comments. It can | |
873 also do spell checking on comments with Flyspell Prog mode | |
874 (@pxref{Spelling}). | |
875 | |
876 @menu | |
877 * Comment Commands:: Inserting, killing, and aligning comments. | |
878 * Multi-Line Comments:: Commands for adding and editing multi-line comments. | |
879 * Options for Comments::Customizing the comment features. | |
880 @end menu | |
881 | |
882 @node Comment Commands | |
883 @subsection Comment Commands | |
884 @cindex indentation for comments | |
885 @cindex alignment for comments | |
886 | |
99317
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
887 The commands in this table insert, kill and align comments: |
84262 | 888 |
889 @table @asis | |
890 @item @kbd{M-;} | |
891 Insert or realign comment on current line; alternatively, comment or | |
892 uncomment the region (@code{comment-dwim}). | |
893 @item @kbd{C-u M-;} | |
894 Kill comment on current line (@code{comment-kill}). | |
895 @item @kbd{C-x ;} | |
896 Set comment column (@code{comment-set-column}). | |
897 @item @kbd{C-M-j} | |
898 @itemx @kbd{M-j} | |
899 Like @key{RET} followed by inserting and aligning a comment | |
900 (@code{comment-indent-new-line}). @xref{Multi-Line Comments}. | |
901 @item @kbd{M-x comment-region} | |
902 @itemx @kbd{C-c C-c} (in C-like modes) | |
903 Add or remove comment delimiters on all the lines in the region. | |
904 @end table | |
905 | |
906 @kindex M-; | |
907 @findex comment-dwim | |
908 The command to create or align a comment is @kbd{M-;} | |
909 (@code{comment-dwim}). The word ``dwim'' is an acronym for ``Do What | |
910 I Mean''; it indicates that this command can be used for many | |
911 different jobs relating to comments, depending on the situation where | |
912 you use it. | |
913 | |
100077
c1e5046326d7
(Other C Commands): Document hide-ifdef-shadow.
Chong Yidong <cyd@stupidchicken.com>
parents:
99956
diff
changeset
|
914 When a region is active, @kbd{M-;} either adds or removes comment |
c1e5046326d7
(Other C Commands): Document hide-ifdef-shadow.
Chong Yidong <cyd@stupidchicken.com>
parents:
99956
diff
changeset
|
915 delimiters on each line of the region. @xref{Mark}. If every line in |
c1e5046326d7
(Other C Commands): Document hide-ifdef-shadow.
Chong Yidong <cyd@stupidchicken.com>
parents:
99956
diff
changeset
|
916 the region is a comment, it removes comment delimiters from each; |
c1e5046326d7
(Other C Commands): Document hide-ifdef-shadow.
Chong Yidong <cyd@stupidchicken.com>
parents:
99956
diff
changeset
|
917 otherwise, it adds comment delimiters to each. You can also use the |
c1e5046326d7
(Other C Commands): Document hide-ifdef-shadow.
Chong Yidong <cyd@stupidchicken.com>
parents:
99956
diff
changeset
|
918 commands @code{comment-region} and @code{uncomment-region} to |
c1e5046326d7
(Other C Commands): Document hide-ifdef-shadow.
Chong Yidong <cyd@stupidchicken.com>
parents:
99956
diff
changeset
|
919 explicitly comment or uncomment the text in the region |
c1e5046326d7
(Other C Commands): Document hide-ifdef-shadow.
Chong Yidong <cyd@stupidchicken.com>
parents:
99956
diff
changeset
|
920 (@pxref{Multi-Line Comments}). If you supply a prefix argument to |
c1e5046326d7
(Other C Commands): Document hide-ifdef-shadow.
Chong Yidong <cyd@stupidchicken.com>
parents:
99956
diff
changeset
|
921 @kbd{M-;} when a region is active, that specifies how many comment |
c1e5046326d7
(Other C Commands): Document hide-ifdef-shadow.
Chong Yidong <cyd@stupidchicken.com>
parents:
99956
diff
changeset
|
922 delimiters to add or how many to delete. |
84262 | 923 |
100077
c1e5046326d7
(Other C Commands): Document hide-ifdef-shadow.
Chong Yidong <cyd@stupidchicken.com>
parents:
99956
diff
changeset
|
924 If the region is not active, @kbd{M-;} inserts a new comment if |
c1e5046326d7
(Other C Commands): Document hide-ifdef-shadow.
Chong Yidong <cyd@stupidchicken.com>
parents:
99956
diff
changeset
|
925 there is no comment already on the line. The new comment is normally |
c1e5046326d7
(Other C Commands): Document hide-ifdef-shadow.
Chong Yidong <cyd@stupidchicken.com>
parents:
99956
diff
changeset
|
926 aligned at a specific column called the @dfn{comment column}; if the |
c1e5046326d7
(Other C Commands): Document hide-ifdef-shadow.
Chong Yidong <cyd@stupidchicken.com>
parents:
99956
diff
changeset
|
927 text of the line extends past the comment column, @kbd{M-;} aligns the |
c1e5046326d7
(Other C Commands): Document hide-ifdef-shadow.
Chong Yidong <cyd@stupidchicken.com>
parents:
99956
diff
changeset
|
928 comment start string to a suitable boundary (usually, at least one |
c1e5046326d7
(Other C Commands): Document hide-ifdef-shadow.
Chong Yidong <cyd@stupidchicken.com>
parents:
99956
diff
changeset
|
929 space is inserted). The comment begins with the string Emacs thinks |
c1e5046326d7
(Other C Commands): Document hide-ifdef-shadow.
Chong Yidong <cyd@stupidchicken.com>
parents:
99956
diff
changeset
|
930 comments should start with (the value of @code{comment-start}; see |
c1e5046326d7
(Other C Commands): Document hide-ifdef-shadow.
Chong Yidong <cyd@stupidchicken.com>
parents:
99956
diff
changeset
|
931 below). Emacs places point after that string, so you can insert the |
c1e5046326d7
(Other C Commands): Document hide-ifdef-shadow.
Chong Yidong <cyd@stupidchicken.com>
parents:
99956
diff
changeset
|
932 text of the comment right away. If the major mode has specified a |
c1e5046326d7
(Other C Commands): Document hide-ifdef-shadow.
Chong Yidong <cyd@stupidchicken.com>
parents:
99956
diff
changeset
|
933 string to terminate comments, @kbd{M-;} inserts that string after |
c1e5046326d7
(Other C Commands): Document hide-ifdef-shadow.
Chong Yidong <cyd@stupidchicken.com>
parents:
99956
diff
changeset
|
934 point, to keep the syntax valid. |
84262 | 935 |
936 You can also use @kbd{M-;} to align an existing comment. If a line | |
937 already contains the comment-start string, @kbd{M-;} realigns it to | |
938 the conventional alignment and moves point after it. (Exception: | |
939 comments starting in column 0 are not moved.) Even when an existing | |
940 comment is properly aligned, @kbd{M-;} is still useful for moving | |
941 directly to the start of the text inside the comment. | |
942 | |
943 @findex comment-kill | |
944 @kindex C-u M-; | |
945 @kbd{C-u M-;} kills any comment on the current line, along with the | |
946 whitespace before it. To reinsert the comment on another line, move | |
947 to the end of that line, do @kbd{C-y}, and then do @kbd{M-;} to | |
948 realign it. | |
949 | |
950 Note that @kbd{C-u M-;} is not a distinct key; it is @kbd{M-;} | |
951 (@code{comment-dwim}) with a prefix argument. That command is | |
952 programmed so that when it receives a prefix argument it calls | |
953 @code{comment-kill}. However, @code{comment-kill} is a valid command | |
954 in its own right, and you can bind it directly to a key if you wish. | |
955 | |
956 Some major modes have special rules for aligning certain kinds of | |
957 comments in certain contexts. For example, in Lisp code, comments which | |
958 start with two semicolons are indented as if they were lines of code, | |
959 instead of at the comment column. Comments which start with three | |
960 semicolons are supposed to start at the left margin and are often used | |
961 for sectioning purposes. Emacs understands | |
962 these conventions by indenting a double-semicolon comment using @key{TAB}, | |
963 and by not changing the indentation of a triple-semicolon comment at all. | |
964 | |
965 @example | |
966 ;; This function is just an example. | |
967 ;;; Here either two or three semicolons are appropriate. | |
968 (defun foo (x) | |
969 ;;; And now, the first part of the function: | |
970 ;; The following line adds one. | |
971 (1+ x)) ; This line adds one. | |
972 @end example | |
973 | |
99317
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
974 For C-like modes, you can configure the exact effect of @kbd{M-;} by |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
975 setting the variables @code{c-indent-comment-alist} and |
84262 | 976 @code{c-indent-comments-syntactically-p}. For example, on a line |
977 ending in a closing brace, @kbd{M-;} puts the comment one space after | |
978 the brace rather than at @code{comment-column}. For full details see | |
99317
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
979 @ref{Comment Commands,,, ccmode, The CC Mode Manual}. |
84262 | 980 |
981 @node Multi-Line Comments | |
982 @subsection Multiple Lines of Comments | |
983 | |
984 @kindex C-M-j | |
985 @kindex M-j | |
986 @cindex blank lines in programs | |
987 @findex comment-indent-new-line | |
988 | |
989 If you are typing a comment and wish to continue it on another line, | |
990 you can use the command @kbd{C-M-j} or @kbd{M-j} | |
991 (@code{comment-indent-new-line}). If @code{comment-multi-line} | |
992 (@pxref{Options for Comments}) is non-@code{nil}, it moves to a new | |
993 line within the comment. Otherwise it closes the comment and starts a | |
994 new comment on a new line. When Auto Fill mode is on, going past the | |
995 fill column while typing a comment causes the comment to be continued | |
996 in just this fashion. | |
997 | |
998 @kindex C-c C-c (C mode) | |
999 @findex comment-region | |
1000 To turn existing lines into comment lines, use the @kbd{M-x | |
1001 comment-region} command (or type @kbd{C-c C-c} in C-like modes). It | |
1002 adds comment delimiters to the lines that start in the region, thus | |
1003 commenting them out. With a negative argument, it does the | |
1004 opposite---it deletes comment delimiters from the lines in the region. | |
1005 | |
1006 With a positive argument, @code{comment-region} duplicates the last | |
1007 character of the comment start sequence it adds; the argument | |
1008 specifies how many copies of the character to insert. Thus, in Lisp | |
1009 mode, @kbd{C-u 2 M-x comment-region} adds @samp{;;} to each line. | |
1010 Duplicating the comment delimiter is a way of calling attention to the | |
1011 comment. It can also affect how the comment is aligned or indented. | |
1012 In Lisp, for proper indentation, you should use an argument of two or | |
1013 three, if between defuns; if within a defun, it must be three. | |
1014 | |
1015 You can configure C Mode such that when you type a @samp{/} at the | |
1016 start of a line in a multi-line block comment, this closes the | |
1017 comment. Enable the @code{comment-close-slash} clean-up for this. | |
1018 @xref{Clean-ups,,, ccmode, The CC Mode Manual}. | |
1019 | |
1020 @node Options for Comments | |
1021 @subsection Options Controlling Comments | |
1022 | |
1023 @vindex comment-column | |
1024 @kindex C-x ; | |
1025 @findex comment-set-column | |
1026 The @dfn{comment column}, the column at which Emacs tries to place | |
1027 comments, is stored in the variable @code{comment-column}. You can | |
1028 set it to a number explicitly. Alternatively, the command @kbd{C-x ;} | |
1029 (@code{comment-set-column}) sets the comment column to the column | |
1030 point is at. @kbd{C-u C-x ;} sets the comment column to match the | |
1031 last comment before point in the buffer, and then does a @kbd{M-;} to | |
1032 align the current line's comment under the previous one. | |
1033 | |
1034 The variable @code{comment-column} is per-buffer: setting the variable | |
1035 in the normal fashion affects only the current buffer, but there is a | |
1036 default value which you can change with @code{setq-default}. | |
1037 @xref{Locals}. Many major modes initialize this variable for the | |
1038 current buffer. | |
1039 | |
1040 @vindex comment-start-skip | |
1041 The comment commands recognize comments based on the regular | |
1042 expression that is the value of the variable @code{comment-start-skip}. | |
1043 Make sure this regexp does not match the null string. It may match more | |
1044 than the comment starting delimiter in the strictest sense of the word; | |
1045 for example, in C mode the value of the variable is | |
1046 @c This stops M-q from breaking the line inside that @code. | |
1047 @code{@w{"/\\*+ *\\|//+ *"}}, which matches extra stars and spaces | |
1048 after the @samp{/*} itself, and accepts C++ style comments also. | |
1049 (Note that @samp{\\} is needed in Lisp syntax to include a @samp{\} in | |
1050 the string, which is needed to deny the first star its special meaning | |
1051 in regexp syntax. @xref{Regexp Backslash}.) | |
1052 | |
1053 @vindex comment-start | |
1054 @vindex comment-end | |
1055 When a comment command makes a new comment, it inserts the value of | |
1056 @code{comment-start} to begin it. The value of @code{comment-end} is | |
1057 inserted after point, so that it will follow the text that you will | |
1058 insert into the comment. When @code{comment-end} is non-empty, it | |
1059 should start with a space. For example, in C mode, | |
1060 @code{comment-start} has the value @w{@code{"/* "}} and | |
1061 @code{comment-end} has the value @w{@code{" */"}}. | |
1062 | |
1063 @vindex comment-padding | |
1064 The variable @code{comment-padding} specifies how many spaces | |
1065 @code{comment-region} should insert on each line between the comment | |
1066 delimiter and the line's original text. The default is 1, to insert | |
1067 one space. @code{nil} means 0. Alternatively, @code{comment-padding} | |
1068 can hold the actual string to insert. | |
1069 | |
1070 @vindex comment-multi-line | |
1071 The variable @code{comment-multi-line} controls how @kbd{C-M-j} | |
1072 (@code{indent-new-comment-line}) behaves when used inside a comment. | |
1073 Specifically, when @code{comment-multi-line} is @code{nil}, the | |
1074 command inserts a comment terminator, begins a new line, and finally | |
1075 inserts a comment starter. Otherwise it does not insert the | |
1076 terminator and starter, so it effectively continues the current | |
1077 comment across multiple lines. In languages that allow multi-line | |
1078 comments, the choice of value for this variable is a matter of taste. | |
1079 The default for this variable depends on the major mode. | |
1080 | |
1081 @vindex comment-indent-function | |
1082 The variable @code{comment-indent-function} should contain a function | |
1083 that will be called to compute the alignment for a newly inserted | |
1084 comment or for aligning an existing comment. It is set differently by | |
1085 various major modes. The function is called with no arguments, but with | |
1086 point at the beginning of the comment, or at the end of a line if a new | |
1087 comment is to be inserted. It should return the column in which the | |
1088 comment ought to start. For example, in Lisp mode, the indent hook | |
1089 function bases its decision on how many semicolons begin an existing | |
1090 comment, and on the code in the preceding lines. | |
1091 | |
1092 @node Documentation | |
1093 @section Documentation Lookup | |
1094 | |
1095 Emacs provides several features you can use to look up the | |
1096 documentation of functions, variables and commands that you plan to | |
1097 use in your program. | |
1098 | |
1099 @menu | |
1100 * Info Lookup:: Looking up library functions and commands | |
1101 in Info files. | |
1102 * Man Page:: Looking up man pages of library functions and commands. | |
1103 * Lisp Doc:: Looking up Emacs Lisp functions, etc. | |
1104 @end menu | |
1105 | |
1106 @node Info Lookup | |
1107 @subsection Info Documentation Lookup | |
1108 | |
1109 @findex info-lookup-symbol | |
1110 @findex info-lookup-file | |
1111 @kindex C-h S | |
99317
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
1112 For major modes that apply to languages which have documentation in |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
1113 Info, you can use @kbd{C-h S} (@code{info-lookup-symbol}) to view the |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
1114 Info documentation for a symbol used in the program. You specify the |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
1115 symbol with the minibuffer; the default is the symbol appearing in the |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
1116 buffer at point. For example, in C mode this looks for the symbol in |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
1117 the C Library Manual. The command only works if the appropriate |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
1118 manual's Info files are installed. |
84262 | 1119 |
1120 The major mode determines where to look for documentation for the | |
1121 symbol---which Info files to look in, and which indices to search. | |
1122 You can also use @kbd{M-x info-lookup-file} to look for documentation | |
1123 for a file name. | |
1124 | |
1125 If you use @kbd{C-h S} in a major mode that does not support it, | |
1126 it asks you to specify the ``symbol help mode.'' You should enter | |
1127 a command such as @code{c-mode} that would select a major | |
1128 mode which @kbd{C-h S} does support. | |
1129 | |
1130 @node Man Page | |
1131 @subsection Man Page Lookup | |
1132 | |
1133 @cindex manual page | |
1134 On Unix, the main form of on-line documentation was the @dfn{manual | |
1135 page} or @dfn{man page}. In the GNU operating system, we aim to | |
1136 replace man pages with better-organized manuals that you can browse | |
1137 with Info (@pxref{Misc Help}). This process is not finished, so it is | |
1138 still useful to read manual pages. | |
1139 | |
1140 @findex manual-entry | |
1141 You can read the man page for an operating system command, library | |
1142 function, or system call, with the @kbd{M-x man} command. It | |
1143 runs the @code{man} program to format the man page; if the system | |
1144 permits, it runs @code{man} asynchronously, so that you can keep on | |
1145 editing while the page is being formatted. (On MS-DOS and MS-Windows | |
1146 3, you cannot edit while Emacs waits for @code{man} to finish.) The | |
1147 result goes in a buffer named @samp{*Man @var{topic}*}. These buffers | |
1148 use a special major mode, Man mode, that facilitates scrolling and | |
1149 jumping to other manual pages. For details, type @kbd{C-h m} while in | |
1150 a man page buffer. | |
1151 | |
1152 @cindex sections of manual pages | |
1153 Each man page belongs to one of ten or more @dfn{sections}, each | |
1154 named by a digit or by a digit and a letter. Sometimes there are | |
1155 multiple man pages with the same name in different sections. To read | |
1156 a man page from a specific section, type | |
1157 @samp{@var{topic}(@var{section})} or @samp{@var{section} @var{topic}} | |
1158 when @kbd{M-x manual-entry} prompts for the topic. For example, to | |
1159 read the man page for the C library function @code{chmod} (as opposed | |
1160 to a command of the same name), type @kbd{M-x manual-entry @key{RET} | |
1161 chmod(2) @key{RET}}. (@code{chmod} is a system call, so it is in | |
1162 section @samp{2}.) | |
1163 | |
1164 @vindex Man-switches | |
1165 If you do not specify a section, the results depend on how the | |
1166 @code{man} program works on your system. Some of them display only | |
1167 the first man page they find. Others display all man pages that have | |
1168 the specified name, so you can move between them with the @kbd{M-n} | |
1169 and @kbd{M-p} keys@footnote{On some systems, the @code{man} program | |
1170 accepts a @samp{-a} command-line option which tells it to display all | |
1171 the man pages for the specified topic. If you want this behavior, you | |
1172 can add this option to the value of the variable @code{Man-switches}.}. | |
1173 The mode line shows how many manual pages are present in the Man buffer. | |
1174 | |
1175 @vindex Man-fontify-manpage-flag | |
1176 By default, Emacs highlights the text in man pages. For a long man | |
1177 page, highlighting can take substantial time. You can turn off | |
1178 highlighting of man pages by setting the variable | |
1179 @code{Man-fontify-manpage-flag} to @code{nil}. | |
1180 | |
1181 @findex Man-fontify-manpage | |
1182 If you insert the text of a man page into an Emacs buffer in some | |
1183 other fashion, you can use the command @kbd{M-x Man-fontify-manpage} to | |
1184 perform the same conversions that @kbd{M-x manual-entry} does. | |
1185 | |
1186 @findex woman | |
1187 @cindex manual pages, on MS-DOS/MS-Windows | |
1188 An alternative way of reading manual pages is the @kbd{M-x woman} | |
1189 command@footnote{The name of the command, @code{woman}, is an acronym | |
1190 for ``w/o (without) man,'' since it doesn't use the @code{man} | |
1191 program.}. Unlike @kbd{M-x man}, it does not run any external | |
1192 programs to format and display the man pages; instead it does the job | |
1193 in Emacs Lisp, so it works on systems such as MS-Windows, where the | |
1194 @code{man} program (and other programs it uses) are not generally | |
1195 available. | |
1196 | |
1197 @kbd{M-x woman} prompts for a name of a manual page, and provides | |
1198 completion based on the list of manual pages that are installed on | |
1199 your machine; the list of available manual pages is computed | |
1200 automatically the first time you invoke @code{woman}. The word at | |
1201 point in the current buffer is used to suggest the default for the | |
1202 name the manual page. | |
1203 | |
1204 With a numeric argument, @kbd{M-x woman} recomputes the list of the | |
1205 manual pages used for completion. This is useful if you add or delete | |
1206 manual pages. | |
1207 | |
1208 If you type a name of a manual page and @kbd{M-x woman} finds that | |
1209 several manual pages by the same name exist in different sections, it | |
1210 pops up a window with possible candidates asking you to choose one of | |
1211 them. | |
1212 | |
1213 For more information about setting up and using @kbd{M-x woman}, see | |
1214 @ref{Top, WoMan, Browse UN*X Manual Pages WithOut Man, woman, The WoMan | |
1215 Manual}. | |
1216 | |
1217 @node Lisp Doc | |
1218 @subsection Emacs Lisp Documentation Lookup | |
1219 | |
1220 As you edit Lisp code to be run in Emacs, you can use the commands | |
1221 @kbd{C-h f} (@code{describe-function}) and @kbd{C-h v} | |
1222 (@code{describe-variable}) to view documentation of functions and | |
1223 variables that you want to use. These commands use the minibuffer to | |
1224 read the name of a function or variable to document, and display the | |
1225 documentation in a window. Their default arguments are based on the | |
1226 code in the neighborhood of point. For @kbd{C-h f}, the default is | |
1227 the function called in the innermost list containing point. @kbd{C-h | |
1228 v} uses the symbol name around or adjacent to point as its default. | |
1229 | |
1230 @cindex Eldoc mode | |
1231 @findex eldoc-mode | |
1232 A more automatic but less powerful method is Eldoc mode. This minor | |
1233 mode constantly displays in the echo area the argument list for the | |
1234 function being called at point. (In other words, it finds the | |
1235 function call that point is contained in, and displays the argument | |
1236 list of that function.) If point is over a documented variable, it | |
1237 shows the first line of the variable's docstring. Eldoc mode applies | |
1238 in Emacs Lisp and Lisp Interaction modes, and perhaps a few others | |
1239 that provide special support for looking up doc strings. Use the | |
1240 command @kbd{M-x eldoc-mode} to enable or disable this feature. | |
1241 | |
1242 @node Hideshow | |
1243 @section Hideshow minor mode | |
1244 | |
1245 @findex hs-minor-mode | |
1246 Hideshow minor mode provides selective display of portions of a | |
1247 program, known as @dfn{blocks}. You can use @kbd{M-x hs-minor-mode} | |
1248 to enable or disable this mode, or add @code{hs-minor-mode} to the | |
1249 mode hook for certain major modes in order to enable it automatically | |
1250 for those modes. | |
1251 | |
1252 Just what constitutes a block depends on the major mode. In C mode | |
1253 or C++ mode, they are delimited by braces, while in Lisp mode and | |
1254 similar modes they are delimited by parentheses. Multi-line comments | |
1255 also count as blocks. | |
1256 | |
1257 @findex hs-hide-all | |
1258 @findex hs-hide-block | |
1259 @findex hs-show-all | |
1260 @findex hs-show-block | |
1261 @findex hs-show-region | |
1262 @findex hs-hide-level | |
1263 @findex hs-minor-mode | |
1264 @kindex C-c @@ C-h | |
1265 @kindex C-c @@ C-s | |
1266 @kindex C-c @@ C-M-h | |
1267 @kindex C-c @@ C-M-s | |
1268 @kindex C-c @@ C-r | |
1269 @kindex C-c @@ C-l | |
1270 @kindex S-Mouse-2 | |
1271 @table @kbd | |
1272 @item C-c @@ C-h | |
1273 Hide the current block (@code{hs-hide-block}). | |
1274 @item C-c @@ C-s | |
1275 Show the current block (@code{hs-show-block}). | |
1276 @item C-c @@ C-c | |
1277 Either hide or show the current block (@code{hs-toggle-hiding}). | |
1278 @item S-Mouse-2 | |
1279 Either hide or show the block you click on (@code{hs-mouse-toggle-hiding}). | |
1280 @item C-c @@ C-M-h | |
1281 Hide all top-level blocks (@code{hs-hide-all}). | |
1282 @item C-c @@ C-M-s | |
1283 Show everything in the buffer (@code{hs-show-all}). | |
1284 @item C-c @@ C-l | |
1285 Hide all blocks @var{n} levels below this block | |
1286 (@code{hs-hide-level}). | |
1287 @end table | |
1288 | |
1289 @vindex hs-hide-comments-when-hiding-all | |
1290 @vindex hs-isearch-open | |
1291 @vindex hs-special-modes-alist | |
1292 These variables exist for customizing Hideshow mode. | |
1293 | |
1294 @table @code | |
1295 @item hs-hide-comments-when-hiding-all | |
1296 Non-@code{nil} says that @kbd{hs-hide-all} should hide comments too. | |
1297 | |
1298 @item hs-isearch-open | |
1299 Specifies what kind of hidden blocks incremental search should make | |
1300 visible. The value should be one of these four symbols: | |
1301 | |
1302 @table @code | |
1303 @item code | |
1304 Open only code blocks. | |
1305 @item comment | |
1306 Open only comments. | |
1307 @item t | |
1308 Open both code blocks and comments. | |
1309 @item nil | |
1310 Open neither code blocks nor comments. | |
1311 @end table | |
1312 | |
1313 @item hs-special-modes-alist | |
1314 A list of elements, each specifying how to initialize Hideshow | |
1315 variables for one major mode. See the variable's documentation string | |
1316 for more information. | |
1317 @end table | |
1318 | |
1319 @node Symbol Completion | |
1320 @section Completion for Symbol Names | |
1321 @cindex completion (symbol names) | |
1322 | |
99317
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
1323 In Emacs, completion is something you normally do in the minibuffer |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
1324 (@pxref{Completion}). But one kind of completion is available in all |
988149a79ff6
(Program Modes): Link to Program Indent node.
Chong Yidong <cyd@stupidchicken.com>
parents:
93357
diff
changeset
|
1325 buffers: completion for symbol names. |
84262 | 1326 |
1327 @kindex M-TAB | |
1328 The character @kbd{M-@key{TAB}} runs a command to complete the | |
1329 partial symbol before point against the set of meaningful symbol | |
1330 names. This command inserts at point any additional characters that | |
1331 it can determine from the partial name. | |
1332 | |
1333 If your window manager defines @kbd{M-@key{TAB}} to switch windows, | |
1334 you can type @kbd{@key{ESC} @key{TAB}} or @kbd{C-M-i} instead. | |
100077
c1e5046326d7
(Other C Commands): Document hide-ifdef-shadow.
Chong Yidong <cyd@stupidchicken.com>
parents:
99956
diff
changeset
|
1335 However, most window managers let you customize these shortcuts, so |
c1e5046326d7
(Other C Commands): Document hide-ifdef-shadow.
Chong Yidong <cyd@stupidchicken.com>
parents:
99956
diff
changeset
|
1336 you can change any that interfere with the way you use Emacs. |
84262 | 1337 |
1338 If the partial name in the buffer has multiple possible completions | |
1339 that differ in the very next character, so that it is impossible to | |
1340 complete even one more character, @kbd{M-@key{TAB}} displays a list of | |
1341 all possible completions in another window. | |
1342 | |
1343 @cindex tags-based completion | |
1344 @cindex Info index completion | |
1345 @findex complete-symbol | |
1346 In most programming language major modes, @kbd{M-@key{TAB}} runs the | |
1347 command @code{complete-symbol}, which provides two kinds of completion. | |
1348 Normally it does completion based on a tags table (@pxref{Tags}); with a | |
1349 numeric argument (regardless of the value), it does completion based on | |
1350 the names listed in the Info file indexes for your language. Thus, to | |
1351 complete the name of a symbol defined in your own program, use | |
1352 @kbd{M-@key{TAB}} with no argument; to complete the name of a standard | |
1353 library function, use @kbd{C-u M-@key{TAB}}. Of course, Info-based | |
1354 completion works only if there is an Info file for the standard library | |
1355 functions of your language, and only if it is installed at your site. | |
1356 | |
1357 @cindex Lisp symbol completion | |
1358 @cindex completion (Lisp symbols) | |
1359 @findex lisp-complete-symbol | |
1360 In Emacs-Lisp mode, the name space for completion normally consists of | |
1361 nontrivial symbols present in Emacs---those that have function | |
1362 definitions, values or properties. However, if there is an | |
1363 open-parenthesis immediately before the beginning of the partial symbol, | |
1364 only symbols with function definitions are considered as completions. | |
1365 The command which implements this is @code{lisp-complete-symbol}. | |
1366 | |
1367 In Text mode and related modes, @kbd{M-@key{TAB}} completes words | |
1368 based on the spell-checker's dictionary. @xref{Spelling}. | |
1369 | |
1370 @node Glasses | |
1371 @section Glasses minor mode | |
1372 @cindex Glasses mode | |
1373 @cindex identifiers, making long ones readable | |
1374 @cindex StudlyCaps, making them readable | |
1375 @findex glasses-mode | |
1376 | |
1377 Glasses minor mode makes @samp{unreadableIdentifiersLikeThis} | |
1378 readable by altering the way they display. It knows two different | |
1379 ways to do this: by displaying underscores between a lower-case letter | |
1380 and the following capital letter, and by emboldening the capital | |
1381 letters. It does not alter the buffer text, only the way they | |
1382 display, so you can use it even on read-only buffers. You can use the | |
1383 command @kbd{M-x glasses-mode} to enable or disable the mode in the | |
1384 current buffer; you can also add @code{glasses-mode} to the mode hook | |
1385 of the programming language major modes in which you normally want | |
1386 to use Glasses mode. | |
1387 | |
1388 @node Misc for Programs | |
1389 @section Other Features Useful for Editing Programs | |
1390 | |
1391 A number of Emacs commands that aren't designed specifically for | |
1392 editing programs are useful for that nonetheless. | |
1393 | |
1394 The Emacs commands that operate on words, sentences and paragraphs | |
1395 are useful for editing code. Most symbols names contain words | |
1396 (@pxref{Words}); sentences can be found in strings and comments | |
1397 (@pxref{Sentences}). Paragraphs in the strict sense can be found in | |
1398 program code (in long comments), but the paragraph commands are useful | |
1399 in other places too, because programming language major modes define | |
1400 paragraphs to begin and end at blank lines (@pxref{Paragraphs}). | |
1401 Judicious use of blank lines to make the program clearer will also | |
1402 provide useful chunks of text for the paragraph commands to work on. | |
1403 Auto Fill mode, if enabled in a programming language major mode, | |
1404 indents the new lines which it creates. | |
1405 | |
1406 The selective display feature is useful for looking at the overall | |
1407 structure of a function (@pxref{Selective Display}). This feature | |
1408 hides the lines that are indented more than a specified amount. | |
1409 Programming modes often support Outline minor mode (@pxref{Outline | |
1410 Mode}). The Foldout package provides folding-editor features | |
1411 (@pxref{Foldout}). | |
1412 | |
1413 The ``automatic typing'' features may be useful for writing programs. | |
1414 @xref{Top,,Autotyping, autotype, Autotyping}. | |
1415 | |
1416 @node C Modes | |
1417 @section C and Related Modes | |
1418 @cindex C mode | |
1419 @cindex Java mode | |
1420 @cindex Pike mode | |
1421 @cindex IDL mode | |
1422 @cindex CORBA IDL mode | |
1423 @cindex Objective C mode | |
1424 @cindex C++ mode | |
1425 @cindex AWK mode | |
1426 @cindex mode, Java | |
1427 @cindex mode, C | |
1428 @cindex mode, C++ | |
1429 @cindex mode, Objective C | |
1430 @cindex mode, CORBA IDL | |
1431 @cindex mode, Pike | |
1432 @cindex mode, AWK | |
1433 | |
1434 This section gives a brief description of the special features | |
1435 available in C, C++, Objective-C, Java, CORBA IDL, Pike and AWK modes. | |
1436 (These are called ``C mode and related modes.'') @xref{Top, , CC Mode, | |
1437 ccmode, CC Mode}, for a more extensive description of these modes | |
1438 and their special features. | |
1439 | |
1440 @menu | |
1441 * Motion in C:: Commands to move by C statements, etc. | |
1442 * Electric C:: Colon and other chars can automatically reindent. | |
1443 * Hungry Delete:: A more powerful DEL command. | |
1444 * Other C Commands:: Filling comments, viewing expansion of macros, | |
1445 and other neat features. | |
1446 @end menu | |
1447 | |
1448 @node Motion in C | |
1449 @subsection C Mode Motion Commands | |
1450 | |
1451 This section describes commands for moving point, in C mode and | |
1452 related modes. | |
1453 | |
1454 @table @code | |
1455 @item M-x c-beginning-of-defun | |
1456 @itemx M-x c-end-of-defun | |
1457 @findex c-beginning-of-defun | |
1458 @findex c-end-of-defun | |
1459 Move point to the beginning or end of the current function or | |
1460 top-level definition. These are found by searching for the least | |
1461 enclosing braces. (By contrast, @code{beginning-of-defun} and | |
1462 @code{end-of-defun} search for braces in column zero.) If you are | |
1463 editing code where the opening brace of a function isn't placed in | |
1464 column zero, you may wish to bind @code{C-M-a} and @code{C-M-e} to | |
1465 these commands. @xref{Moving by Defuns}. | |
1466 | |
1467 @item C-c C-u | |
1468 @kindex C-c C-u @r{(C mode)} | |
1469 @findex c-up-conditional | |
1470 Move point back to the containing preprocessor conditional, leaving the | |
1471 mark behind. A prefix argument acts as a repeat count. With a negative | |
1472 argument, move point forward to the end of the containing | |
1473 preprocessor conditional. | |
1474 | |
1475 @samp{#elif} is equivalent to @samp{#else} followed by @samp{#if}, so | |
1476 the function will stop at a @samp{#elif} when going backward, but not | |
1477 when going forward. | |
1478 | |
1479 @item C-c C-p | |
1480 @kindex C-c C-p @r{(C mode)} | |
1481 @findex c-backward-conditional | |
1482 Move point back over a preprocessor conditional, leaving the mark | |
1483 behind. A prefix argument acts as a repeat count. With a negative | |
1484 argument, move forward. | |
1485 | |
1486 @item C-c C-n | |
1487 @kindex C-c C-n @r{(C mode)} | |
1488 @findex c-forward-conditional | |
1489 Move point forward across a preprocessor conditional, leaving the mark | |
1490 behind. A prefix argument acts as a repeat count. With a negative | |
1491 argument, move backward. | |
1492 | |
1493 @item M-a | |
1494 @kindex M-a (C mode) | |
1495 @findex c-beginning-of-statement | |
1496 Move point to the beginning of the innermost C statement | |
1497 (@code{c-beginning-of-statement}). If point is already at the beginning | |
1498 of a statement, move to the beginning of the preceding statement. With | |
1499 prefix argument @var{n}, move back @var{n} @minus{} 1 statements. | |
1500 | |
1501 In comments or in strings which span more than one line, this command | |
1502 moves by sentences instead of statements. | |
1503 | |
1504 @item M-e | |
1505 @kindex M-e (C mode) | |
1506 @findex c-end-of-statement | |
1507 Move point to the end of the innermost C statement or sentence; like | |
1508 @kbd{M-a} except that it moves in the other direction | |
1509 (@code{c-end-of-statement}). | |
1510 @end table | |
1511 | |
1512 @node Electric C | |
1513 @subsection Electric C Characters | |
1514 | |
1515 In C mode and related modes, certain printing characters are | |
1516 @dfn{electric}---in addition to inserting themselves, they also | |
1517 reindent the current line, and optionally also insert newlines. The | |
1518 ``electric'' characters are @kbd{@{}, @kbd{@}}, @kbd{:}, @kbd{#}, | |
1519 @kbd{;}, @kbd{,}, @kbd{<}, @kbd{>}, @kbd{/}, @kbd{*}, @kbd{(}, and | |
1520 @kbd{)}. | |
1521 | |
1522 You might find electric indentation inconvenient if you are editing | |
1523 chaotically indented code. If you are new to CC Mode, you might find | |
1524 it disconcerting. You can toggle electric action with the command | |
1525 @kbd{C-c C-l}; when it is enabled, @samp{/l} appears in the mode line | |
1526 after the mode name: | |
1527 | |
1528 @table @kbd | |
1529 @item C-c C-l | |
1530 @kindex C-c C-l @r{(C mode)} | |
1531 @findex c-toggle-electric-state | |
1532 Toggle electric action (@code{c-toggle-electric-state}). With a | |
1533 prefix argument, this command enables electric action if the argument | |
1534 is positive, disables it if it is negative. | |
1535 @end table | |
1536 | |
1537 Electric characters insert newlines only when, in addition to the | |
1538 electric state, the @dfn{auto-newline} feature is enabled (indicated | |
1539 by @samp{/la} in the mode line after the mode name). You can turn | |
1540 this feature on or off with the command @kbd{C-c C-a}: | |
1541 | |
1542 @table @kbd | |
1543 @item C-c C-a | |
1544 @kindex C-c C-a @r{(C mode)} | |
1545 @findex c-toggle-auto-newline | |
1546 Toggle the auto-newline feature (@code{c-toggle-auto-newline}). With a | |
1547 prefix argument, this command turns the auto-newline feature on if the | |
1548 argument is positive, and off if it is negative. | |
1549 @end table | |
1550 | |
1551 Usually the CC Mode style configures the exact circumstances in | |
1552 which Emacs inserts auto-newlines. You can also configure this | |
1553 directly. @xref{Custom Auto-newlines,,, ccmode, The CC Mode Manual}. | |
1554 | |
1555 @node Hungry Delete | |
1556 @subsection Hungry Delete Feature in C | |
1557 @cindex hungry deletion (C Mode) | |
1558 | |
1559 If you want to delete an entire block of whitespace at point, you | |
1560 can use @dfn{hungry deletion}. This deletes all the contiguous | |
1561 whitespace either before point or after point in a single operation. | |
1562 @dfn{Whitespace} here includes tabs and newlines, but not comments or | |
1563 preprocessor commands. | |
1564 | |
1565 @table @kbd | |
1566 @item C-c C-@key{DEL} | |
1567 @itemx C-c @key{DEL} | |
1568 @findex c-hungry-delete-backwards | |
1569 @kindex C-c C-@key{DEL} (C Mode) | |
1570 @kindex C-c @key{DEL} (C Mode) | |
1571 @code{c-hungry-delete-backwards}---Delete the entire block of whitespace | |
1572 preceding point. | |
1573 | |
1574 @item C-c C-d | |
1575 @itemx C-c C-@key{DELETE} | |
1576 @itemx C-c @key{DELETE} | |
1577 @findex c-hungry-delete-forward | |
1578 @kindex C-c C-d (C Mode) | |
1579 @kindex C-c C-@key{DELETE} (C Mode) | |
1580 @kindex C-c @key{DELETE} (C Mode) | |
1581 @code{c-hungry-delete-forward}---Delete the entire block of whitespace | |
1582 following point. | |
1583 @end table | |
1584 | |
1585 As an alternative to the above commands, you can enable @dfn{hungry | |
1586 delete mode}. When this feature is enabled (indicated by @samp{/h} in | |
1587 the mode line after the mode name), a single @key{DEL} deletes all | |
1588 preceding whitespace, not just one space, and a single @kbd{C-c C-d} | |
1589 (but @emph{not} plain @key{DELETE}) deletes all following whitespace. | |
1590 | |
1591 @table @kbd | |
1592 @item M-x c-toggle-hungry-state | |
1593 @findex c-toggle-hungry-state | |
1594 Toggle the hungry-delete feature | |
1595 (@code{c-toggle-hungry-state})@footnote{This command had the binding | |
1596 @kbd{C-c C-d} in earlier versions of Emacs. @kbd{C-c C-d} is now | |
1597 bound to @code{c-hungry-delete-forward}.}. With a prefix argument, | |
1598 this command turns the hungry-delete feature on if the argument is | |
1599 positive, and off if it is negative. | |
1600 @end table | |
1601 | |
1602 @vindex c-hungry-delete-key | |
1603 The variable @code{c-hungry-delete-key} controls whether the | |
1604 hungry-delete feature is enabled. | |
1605 | |
1606 @node Other C Commands | |
1607 @subsection Other Commands for C Mode | |
1608 | |
1609 @table @kbd | |
1610 @item C-c C-w | |
1611 @itemx M-x c-subword-mode | |
1612 @findex c-subword-mode | |
1613 Enable (or disable) @dfn{subword mode}. In subword mode, Emacs's word | |
1614 commands recognize upper case letters in | |
1615 @samp{StudlyCapsIdentifiers} as word boundaries. This is indicated by | |
1616 the flag @samp{/w} on the mode line after the mode name | |
1617 (e.g. @samp{C/law}). You can even use @kbd{M-x c-subword-mode} in | |
1618 non-CC Mode buffers. | |
1619 | |
1620 In the GNU project, we recommend using underscores to separate words | |
1621 within an identifier in C or C++, rather than using case distinctions. | |
1622 | |
1623 @item M-x c-context-line-break | |
1624 @findex c-context-line-break | |
1625 This command inserts a line break and indents the new line in a manner | |
1626 appropriate to the context. In normal code, it does the work of | |
1627 @kbd{C-j} (@code{newline-and-indent}), in a C preprocessor line it | |
1628 additionally inserts a @samp{\} at the line break, and within comments | |
1629 it's like @kbd{M-j} (@code{c-indent-new-comment-line}). | |
1630 | |
1631 @code{c-context-line-break} isn't bound to a key by default, but it | |
1632 needs a binding to be useful. The following code will bind it to | |
1633 @kbd{C-j}. We use @code{c-initialization-hook} here to make sure | |
1634 the keymap is loaded before we try to change it. | |
1635 | |
1636 @smallexample | |
1637 (defun my-bind-clb () | |
1638 (define-key c-mode-base-map "\C-j" 'c-context-line-break)) | |
1639 (add-hook 'c-initialization-hook 'my-bind-clb) | |
1640 @end smallexample | |
1641 | |
1642 @item C-M-h | |
1643 Put mark at the end of a function definition, and put point at the | |
1644 beginning (@code{c-mark-function}). | |
1645 | |
1646 @item M-q | |
1647 @kindex M-q @r{(C mode)} | |
1648 @findex c-fill-paragraph | |
1649 Fill a paragraph, handling C and C++ comments (@code{c-fill-paragraph}). | |
1650 If any part of the current line is a comment or within a comment, this | |
1651 command fills the comment or the paragraph of it that point is in, | |
1652 preserving the comment indentation and comment delimiters. | |
1653 | |
1654 @item C-c C-e | |
1655 @cindex macro expansion in C | |
1656 @cindex expansion of C macros | |
1657 @findex c-macro-expand | |
1658 @kindex C-c C-e @r{(C mode)} | |
1659 Run the C preprocessor on the text in the region, and show the result, | |
1660 which includes the expansion of all the macro calls | |
1661 (@code{c-macro-expand}). The buffer text before the region is also | |
1662 included in preprocessing, for the sake of macros defined there, but the | |
1663 output from this part isn't shown. | |
1664 | |
1665 When you are debugging C code that uses macros, sometimes it is hard to | |
1666 figure out precisely how the macros expand. With this command, you | |
1667 don't have to figure it out; you can see the expansions. | |
1668 | |
1669 @item C-c C-\ | |
1670 @findex c-backslash-region | |
1671 @kindex C-c C-\ @r{(C mode)} | |
1672 Insert or align @samp{\} characters at the ends of the lines of the | |
1673 region (@code{c-backslash-region}). This is useful after writing or | |
1674 editing a C macro definition. | |
1675 | |
1676 If a line already ends in @samp{\}, this command adjusts the amount of | |
1677 whitespace before it. Otherwise, it inserts a new @samp{\}. However, | |
1678 the last line in the region is treated specially; no @samp{\} is | |
1679 inserted on that line, and any @samp{\} there is deleted. | |
1680 | |
1681 @item M-x cpp-highlight-buffer | |
1682 @cindex preprocessor highlighting | |
1683 @findex cpp-highlight-buffer | |
1684 Highlight parts of the text according to its preprocessor conditionals. | |
1685 This command displays another buffer named @samp{*CPP Edit*}, which | |
1686 serves as a graphic menu for selecting how to display particular kinds | |
1687 of conditionals and their contents. After changing various settings, | |
1688 click on @samp{[A]pply these settings} (or go to that buffer and type | |
1689 @kbd{a}) to rehighlight the C mode buffer accordingly. | |
1690 | |
1691 @item C-c C-s | |
1692 @findex c-show-syntactic-information | |
1693 @kindex C-c C-s @r{(C mode)} | |
1694 Display the syntactic information about the current source line | |
1695 (@code{c-show-syntactic-information}). This information directs how | |
1696 the line is indented. | |
1697 | |
1698 @item M-x cwarn-mode | |
1699 @itemx M-x global-cwarn-mode | |
1700 @findex cwarn-mode | |
1701 @findex global-cwarn-mode | |
1702 @vindex global-cwarn-mode | |
1703 @cindex CWarn mode | |
1704 @cindex suspicious constructions in C, C++ | |
1705 CWarn minor mode highlights certain suspicious C and C++ constructions: | |
1706 | |
1707 @itemize @bullet{} | |
1708 @item | |
1709 Assignments inside expressions. | |
1710 @item | |
1711 Semicolon following immediately after @samp{if}, @samp{for}, and @samp{while} | |
1712 (except after a @samp{do @dots{} while} statement); | |
1713 @item | |
1714 C++ functions with reference parameters. | |
1715 @end itemize | |
1716 | |
1717 @noindent | |
1718 You can enable the mode for one buffer with the command @kbd{M-x | |
1719 cwarn-mode}, or for all suitable buffers with the command @kbd{M-x | |
1720 global-cwarn-mode} or by customizing the variable | |
1721 @code{global-cwarn-mode}. You must also enable Font Lock mode to make | |
1722 it work. | |
1723 | |
1724 @item M-x hide-ifdef-mode | |
1725 @findex hide-ifdef-mode | |
1726 @cindex Hide-ifdef mode | |
100077
c1e5046326d7
(Other C Commands): Document hide-ifdef-shadow.
Chong Yidong <cyd@stupidchicken.com>
parents:
99956
diff
changeset
|
1727 @vindex hide-ifdef-shadow |
84262 | 1728 Hide-ifdef minor mode hides selected code within @samp{#if} and |
100077
c1e5046326d7
(Other C Commands): Document hide-ifdef-shadow.
Chong Yidong <cyd@stupidchicken.com>
parents:
99956
diff
changeset
|
1729 @samp{#ifdef} preprocessor blocks. If you change the variable |
c1e5046326d7
(Other C Commands): Document hide-ifdef-shadow.
Chong Yidong <cyd@stupidchicken.com>
parents:
99956
diff
changeset
|
1730 @code{hide-ifdef-shadow} to @code{t}, Hide-ifdef minor mode |
c1e5046326d7
(Other C Commands): Document hide-ifdef-shadow.
Chong Yidong <cyd@stupidchicken.com>
parents:
99956
diff
changeset
|
1731 ``shadows'' preprocessor blocks by displaying them with a less |
c1e5046326d7
(Other C Commands): Document hide-ifdef-shadow.
Chong Yidong <cyd@stupidchicken.com>
parents:
99956
diff
changeset
|
1732 prominent face, instead of hiding them entirely. See the |
c1e5046326d7
(Other C Commands): Document hide-ifdef-shadow.
Chong Yidong <cyd@stupidchicken.com>
parents:
99956
diff
changeset
|
1733 documentation string of @code{hide-ifdef-mode} for more information. |
84262 | 1734 |
1735 @item M-x ff-find-related-file | |
1736 @cindex related files | |
1737 @findex ff-find-related-file | |
1738 @vindex ff-related-file-alist | |
1739 Find a file ``related'' in a special way to the file visited by the | |
1740 current buffer. Typically this will be the header file corresponding | |
1741 to a C/C++ source file, or vice versa. The variable | |
1742 @code{ff-related-file-alist} specifies how to compute related file | |
1743 names. | |
1744 @end table | |
1745 | |
1746 @node Asm Mode | |
1747 @section Asm Mode | |
1748 | |
1749 @cindex Asm mode | |
1750 @cindex assembler mode | |
1751 Asm mode is a major mode for editing files of assembler code. It | |
1752 defines these commands: | |
1753 | |
1754 @table @kbd | |
1755 @item @key{TAB} | |
1756 @code{tab-to-tab-stop}. | |
1757 @item C-j | |
1758 Insert a newline and then indent using @code{tab-to-tab-stop}. | |
1759 @item : | |
1760 Insert a colon and then remove the indentation from before the label | |
1761 preceding colon. Then do @code{tab-to-tab-stop}. | |
1762 @item ; | |
1763 Insert or align a comment. | |
1764 @end table | |
1765 | |
1766 The variable @code{asm-comment-char} specifies which character | |
1767 starts comments in assembler syntax. | |
1768 | |
1769 @ifnottex | |
1770 @include fortran-xtra.texi | |
1771 @end ifnottex | |
1772 | |
1773 @ignore | |
1774 arch-tag: c7ee7409-40a4-45c7-bfb7-ae7f2c74d0c0 | |
1775 @end ignore |