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