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