Mercurial > emacs
annotate man/cc-mode.texi @ 26759:01f067d61668
(x_set_menu_resources_from_menu_face): Make sure
basic faces are realized before trying to use face `menu'.
author | Gerd Moellmann <gerd@gnu.org> |
---|---|
date | Tue, 07 Dec 1999 20:06:40 +0000 |
parents | 2b08d829af86 |
children | a19be798eaea |
rev | line source |
---|---|
25829 | 1 \input texinfo |
2 | |
3 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
4 @comment %**start of header (This is for running Texinfo on a region) | |
5 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
6 | |
7 @setfilename ../info/ccmode | |
8 @settitle CC MODE Version 5 Documentation | |
9 @footnotestyle end | |
10 | |
11 @dircategory Editors | |
12 @direntry | |
13 * CC mode: (ccmode). The GNU Emacs mode for editing C, C++, Objective-C | |
14 and Java code. | |
15 @end direntry | |
16 | |
17 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
18 @comment @setchapternewpage odd !! we don't want blank pages !! | |
19 @comment %**end of header (This is for running Texinfo on a region) | |
20 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
21 | |
22 | |
23 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
24 @comment | |
25 @comment Texinfo manual for CC Mode | |
26 @comment Generated from the original README file by Krishna Padmasola | |
27 @comment <krishna@earth-gw.njit.edu> | |
28 @comment | |
29 @comment Maintained by Barry A. Warsaw <cc-mode-help@python.org> | |
30 @comment | |
31 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
32 | |
33 | |
34 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
35 @comment The following line inserts the copyright notice | |
36 @comment into the Info file. | |
37 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
38 | |
39 @ifinfo | |
40 Copyright @copyright{} 1995,96,97,98 Free Software Foundation, Inc. | |
41 @end ifinfo | |
42 | |
43 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
44 @comment !!!The titlepage section does not appear in the Info file.!!! | |
45 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
46 | |
47 @titlepage | |
48 @sp 10 | |
49 | |
50 | |
51 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
52 @comment The title is printed in a large font. | |
53 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
54 | |
55 @center @titlefont{CC Mode 5.21} | |
56 @sp 2 | |
57 @center @subtitlefont{A GNU Emacs mode for editing C and C-like languages} | |
58 @sp 2 | |
59 @center Barry A. Warsaw | |
60 | |
61 | |
62 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
63 @comment The following two commands start the copyright page | |
64 @comment for the printed manual. This will not appear in the Info file. | |
65 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
66 | |
67 @page | |
68 @vskip 0pt plus 1filll | |
69 Copyright @copyright{} 1995,96,97,98 Free Software Foundation, Inc. | |
70 @end titlepage | |
71 | |
72 | |
73 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
74 @comment The Top node contains the master menu for the Info file. | |
75 @comment This appears only in the Info file, not the printed manual. | |
76 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
77 | |
78 @node Top, Introduction, (dir), (dir) | |
79 @comment node-name, next, previous, up | |
80 | |
81 | |
82 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
83 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
84 | |
85 @menu | |
86 * Introduction:: | |
87 * Getting Connected:: | |
88 * New Indentation Engine:: | |
89 * Minor Modes:: | |
90 * Commands:: | |
91 * Customizing Indentation:: | |
92 * Syntactic Symbols:: | |
93 * Performance Issues:: | |
94 * Frequently Asked Questions:: | |
95 * Getting the latest CC Mode release:: | |
96 * Sample .emacs File:: | |
97 * Limitations and Known Bugs:: | |
98 * Mailing Lists and Submitting Bug Reports:: | |
99 * Concept Index:: | |
100 * Command Index:: Command Index | |
101 * Key Index:: Key Index | |
102 * Variable Index:: Variable Index | |
103 @end menu | |
104 | |
105 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
106 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
107 | |
108 @node Introduction, Getting Connected, Top, Top | |
109 @comment node-name, next, previous, up | |
110 @chapter Introduction | |
111 @cindex Introduction | |
112 | |
113 @macro ccmode | |
114 CC Mode | |
115 @end macro | |
116 | |
117 @cindex BOCM | |
118 | |
119 Welcome to @ccmode{}. This is a GNU Emacs mode for editing files | |
120 containing C, C++, Objective-C, Java, and CORBA IDL code. This | |
121 incarnation of the mode is descendant from @file{c-mode.el} (also called | |
122 "Boring Old C Mode" or BOCM @code{:-)}, and @file{c++-mode.el} version | |
123 2, which I have been maintaining since 1992. @ccmode{} represents a | |
124 significant milestone in the mode's life. It has been fully merged back | |
125 with Emacs 19's @file{c-mode.el}. Also a new, more intuitive and | |
126 flexible mechanism for controlling indentation has been developed. | |
127 | |
128 @ccmode{} supports the editing of K&R and ANSI C, @dfn{ARM} | |
129 @footnote{``The Annotated C++ Reference Manual'', by Ellis and | |
130 Stroustrup.} C++, Objective-C, Java and CORBA's Interface | |
131 Definition Language files. In this way, you can | |
132 easily set up consistent coding styles for use in editing all C, C++, | |
133 Objective-C, Java and IDL programs. @ccmode{} does @emph{not} handle | |
134 font-locking (a.k.a. syntax coloring, keyword highlighting) or anything | |
135 of that nature, for any of these modes. Font-locking is handled by other | |
136 Emacs packages. | |
137 | |
138 This manual will describe the following: | |
139 | |
140 @itemize @bullet | |
141 @item | |
142 How to get started using @ccmode{}. | |
143 | |
144 @item | |
145 How the new indentation engine works. | |
146 | |
147 @item | |
148 How to customize the new indentation engine. | |
149 | |
150 @end itemize | |
151 | |
152 @findex c-mode | |
153 @findex c++-mode | |
154 @findex objc-mode | |
155 @findex java-mode | |
156 @findex idl-mode | |
157 Note that the name of this package is ``@ccmode{}'', but there is no top | |
158 level @code{cc-mode} entry point. All of the variables, commands, and | |
159 functions in @ccmode{} are prefixed with @code{c-@var{<thing>}}, and | |
160 @code{c-mode}, @code{c++-mode}, @code{objc-mode}, @code{java-mode}, and | |
161 @code{idl-mode} entry points are provided. This file is intended to be | |
162 a replacement for @file{c-mode.el} and @file{c++-mode.el}. | |
163 | |
164 @cindex @file{cc-compat.el} file | |
165 This distribution also contains a file | |
166 called @file{cc-compat.el} which should ease your transition from BOCM | |
167 to @ccmode{}. If you have a BOCM configuration you are really happy | |
168 with, and want to postpone learning how to configure @ccmode{}, take a | |
169 look at that file. It maps BOCM configuration variables to @ccmode{}'s | |
170 new indentation model. It is not actively supported so for the long | |
171 run, you should learn how to customize @ccmode{} to support your coding | |
172 style. | |
173 | |
174 A special word of thanks goes to Krishna Padmasola for his work in | |
175 converting the original @file{README} file to Texinfo format. I'd also | |
176 like to thank all the @ccmode{} victims who help enormously during the | |
177 early beta stages of @ccmode{}'s development. | |
178 | |
179 | |
180 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
181 | |
182 @node Getting Connected, New Indentation Engine, Introduction, Top | |
183 @comment node-name, next, previous, up | |
184 @chapter Getting Connected | |
185 @cindex Getting Connected | |
186 | |
187 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
188 | |
189 If you got this version of @ccmode{} with Emacs or XEmacs, it should | |
190 work just fine right out of the box. Note however that you may not have | |
191 the latest @ccmode{} release and may want to upgrade your copy. | |
192 | |
193 If you are upgrading an existing @ccmode{} installation, please see the | |
194 @file{README} file for installation details. @ccmode{} may not work | |
195 with older versions of Emacs or XEmacs. See the @ccmode{} release notes | |
196 Web pages for the latest information on Emacs version and package | |
197 compatibility (see @ref{Getting the latest CC Mode release}). | |
198 | |
199 @cindex @file{cc-mode-18.el} file | |
200 @emph{Note that @ccmode{} no longer works with Emacs 18!} The | |
201 @file{cc-mode-18.el} file is no longer distributed with @ccmode{}. If | |
202 you haven't upgraded from Emacs 18 by now, you are out of luck. | |
203 | |
204 @findex c-version | |
205 @findex version (c-) | |
206 You can find out what version of @ccmode{} you are using by visiting a C | |
207 file and entering @kbd{M-x c-version RET}. You should see this message in | |
208 the echo area: | |
209 @example | |
210 | |
211 Using CC Mode version 5.XX | |
212 | |
213 @end example | |
214 | |
215 @noindent | |
216 where @samp{XX} is the minor release number. | |
217 | |
218 | |
219 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
220 @node New Indentation Engine, Minor Modes, Getting Connected, Top | |
221 @comment node-name, next, previous, up | |
222 | |
223 @chapter New Indentation Engine | |
224 @cindex New Indentation Engine | |
225 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
226 | |
227 @ccmode{} has a new indentation engine, providing a simplified, yet | |
228 flexible and general mechanism for customizing indentation. It separates | |
229 indentation calculation into two steps: first, @ccmode{} analyzes the | |
230 line of code being indented to determine the kind of language construct | |
231 it's looking at, then it applies user defined offsets to the current | |
232 line based on this analysis. | |
233 | |
234 This section will briefly cover how indentation is calculated in | |
235 @ccmode{}. It is important to understand the indentation model | |
236 being used so that you will know how to customize @ccmode{} for | |
237 your personal coding style. | |
238 | |
239 @menu | |
240 * Syntactic Analysis:: | |
241 * Indentation Calculation:: | |
242 @end menu | |
243 | |
244 | |
245 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
246 @node Syntactic Analysis, Indentation Calculation, , New Indentation Engine | |
247 @comment node-name, next, previous,up | |
248 @section Syntactic Analysis | |
249 @cindex Syntactic Analysis | |
250 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
251 | |
252 @vindex c-offsets-alist | |
253 @vindex offsets-alist (c-) | |
254 @cindex relative buffer position | |
255 @cindex syntactic symbol | |
256 @cindex syntactic component | |
257 @cindex syntactic component list | |
258 @cindex relative buffer position | |
259 The first thing @ccmode{} does when indenting a line of code, is to | |
260 analyze the line, determining the @dfn{syntactic component list} of the | |
261 construct on that line. A syntactic component consists of a pair | |
262 of information (in lisp parlance, a @emph{cons cell}), where the first | |
263 part is a @dfn{syntactic symbol}, and the second part is a @dfn{relative | |
264 buffer position}. Syntactic symbols describe elements of C code | |
265 @footnote{or C++, Objective-C, Java or IDL code. In general, for the rest | |
266 of this manual I'll use the term ``C code'' to refer to all the C-like | |
267 dialects, unless otherwise noted.}, e.g. @code{statement}, | |
268 @code{substatement}, @code{class-open}, @code{class-close}, etc. | |
269 @xref{Syntactic Symbols}, for a complete list of currently recognized | |
270 syntactic symbols and their semantics. The variable | |
271 @code{c-offsets-alist} also contains the list of currently supported | |
272 syntactic symbols. | |
273 | |
274 Conceptually, a line of C code is always indented relative to the | |
275 indentation of some line higher up in the buffer. This is represented | |
276 by the relative buffer position in the syntactic component. | |
277 | |
278 Here is an example. Suppose we had the following code as the only thing | |
279 in a @code{c++-mode} buffer @footnote{The line numbers in this and | |
280 future examples don't actually appear in the buffer, of course!}: | |
281 @example | |
282 @group | |
283 | |
284 1: void swap( int& a, int& b ) | |
285 2: @{ | |
286 3: int tmp = a; | |
287 4: a = b; | |
288 5: b = tmp; | |
289 6: @} | |
290 | |
291 @end group | |
292 @end example | |
293 | |
294 @kindex C-c C-s | |
295 @findex c-show-syntactic-information | |
296 @findex show-syntactic-information (c-) | |
297 We can use the command @kbd{C-c C-s} | |
298 (@code{c-show-syntactic-information}) to simply report what the | |
299 syntactic analysis is for the current line. Running this command on | |
300 line 4 of this example, we'd see in the echo area@footnote{With a universal | |
301 argument (i.e. @kbd{C-u C-c C-s}) the analysis is inserted into the | |
302 buffer as a comment | |
303 on the current line.}: | |
304 @example | |
305 | |
306 ((statement . 35)) | |
307 | |
308 @end example | |
309 | |
310 This tells us that the line is a statement and it is indented relative | |
311 to buffer position 35, which happens to be the @samp{i} in @code{int} on | |
312 line 3. If you were to move point to line 3 and hit @kbd{C-c C-s}, you | |
313 would see: | |
314 @example | |
315 | |
316 ((defun-block-intro . 29)) | |
317 | |
318 @end example | |
319 | |
320 This indicates that the @samp{int} line is the first statement in a top | |
321 level function block, and is indented relative to buffer position 29, | |
322 which is the brace just after the function header. | |
323 | |
324 Here's another example: | |
325 @example | |
326 @group | |
327 | |
328 1: int add( int val, int incr, int doit ) | |
329 2: @{ | |
330 3: if( doit ) | |
331 4: @{ | |
332 5: return( val + incr ); | |
333 6: @} | |
334 7: return( val ); | |
335 8: @} | |
336 | |
337 @end group | |
338 @end example | |
339 | |
340 @noindent | |
341 Hitting @kbd{C-c C-s} on line 4 gives us: | |
342 @example | |
343 | |
344 ((substatement-open . 46)) | |
345 | |
346 @end example | |
347 | |
348 @cindex substatement | |
349 @cindex substatment block | |
350 @noindent | |
351 which tells us that this is a brace that @emph{opens} a substatement | |
352 block. @footnote{A @dfn{substatement} is the line after a | |
353 conditional statement, such as @code{if}, @code{else}, @code{while}, | |
354 @code{do}, @code{switch}, etc. A @dfn{substatement | |
355 block} is a brace block following one of these conditional statements.} | |
356 | |
357 @cindex comment-only line | |
358 Syntactic component lists can contain more than one component, and | |
359 individual syntactic components need not have relative buffer positions. | |
360 The most common example of this is a line that contains a @dfn{comment | |
361 only line}. | |
362 @example | |
363 @group | |
364 | |
365 1: void draw_list( List<Drawables>& drawables ) | |
366 2: @{ | |
367 3: // call the virtual draw() method on each element in list | |
368 4: for( int i=0; i < drawables.count(), ++i ) | |
369 5: @{ | |
370 6: drawables[i].draw(); | |
371 7: @} | |
372 8: @} | |
373 | |
374 @end group | |
375 @end example | |
376 | |
377 @noindent | |
378 Hitting @kbd{C-c C-s} on line 3 of this example gives: | |
379 @example | |
380 | |
381 ((comment-intro) (defun-block-intro . 46)) | |
382 | |
383 @end example | |
384 | |
385 @noindent | |
386 and you can see that the syntactic component list contains two syntactic | |
387 components. Also notice that the first component, | |
388 @samp{(comment-intro)} has no relative buffer position. | |
389 | |
390 | |
391 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
392 @node Indentation Calculation, , Syntactic Analysis, New Indentation Engine | |
393 @comment node-name, next, previous,up | |
394 @section Indentation Calculation | |
395 @cindex Indentation Calculation | |
396 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
397 | |
398 @vindex c-offsets-alist | |
399 @vindex offsets-alist (c-) | |
400 Indentation for a line is calculated using the syntactic | |
401 component list derived in step 1 above (see @ref{Syntactic Analysis}). | |
402 Each component contributes to the final total indentation of the line in | |
403 two ways. | |
404 | |
405 First, the syntactic symbols are looked up in the @code{c-offsets-alist} | |
406 variable, which is an association list of syntactic symbols and the | |
407 offsets to apply for those symbols. These offsets are added to a | |
408 running total. | |
409 | |
410 Second, if the component has a relative buffer position, @ccmode{} | |
411 adds the column number of that position to the running total. By adding | |
412 up the offsets and columns for every syntactic component on the list, | |
413 the final total indentation for the current line is computed. | |
414 | |
415 Let's use our two code examples above to see how this works. Here is | |
416 our first example again: | |
417 @example | |
418 @group | |
419 | |
420 1: void swap( int& a, int& b ) | |
421 2: @{ | |
422 3: int tmp = a; | |
423 4: a = b; | |
424 5: b = tmp; | |
425 6: @} | |
426 | |
427 @end group | |
428 @end example | |
429 | |
430 @kindex TAB | |
431 Let's say point is on line 3 and we hit the @kbd{TAB} key to re-indent | |
432 the line. Remember that the syntactic component list for that | |
433 line is: | |
434 @example | |
435 | |
436 ((defun-block-intro . 29)) | |
437 | |
438 @end example | |
439 | |
440 @noindent | |
441 @ccmode{} looks up @code{defun-block-intro} in the | |
442 @code{c-offsets-alist} variable. Let's say it finds the value @samp{4}; | |
443 it adds this to the running total (initialized to zero), yielding a | |
444 running total indentation of 4 spaces. | |
445 | |
446 Next @ccmode{} goes to buffer position 29 and asks for the current | |
447 column. This brace is in column zero, so @ccmode{} | |
448 adds @samp{0} to the running total. Since there is only one syntactic | |
449 component on the list for this line, indentation calculation is | |
450 complete, and the total indentation for the line | |
451 is 4 spaces. | |
452 | |
453 Here's another example: | |
454 @example | |
455 @group | |
456 | |
457 1: int add( int val, int incr, int doit ) | |
458 2: @{ | |
459 3: if( doit ) | |
460 4: @{ | |
461 5: return( val + incr ); | |
462 6: @} | |
463 7: return( val ); | |
464 8: @} | |
465 | |
466 @end group | |
467 @end example | |
468 | |
469 If we were to hit @kbd{TAB} on line 4 in the above example, the same | |
470 basic process is performed, despite the differences in the syntactic | |
471 component list. Remember that the list for this line is: | |
472 @example | |
473 | |
474 ((substatement-open . 46)) | |
475 | |
476 @end example | |
477 | |
478 Here, @ccmode{} first looks up the @code{substatement-open} symbol | |
479 in @code{c-offsets-alist}. Let's say it finds the value @samp{4}. This | |
480 yields a running total of 4. @ccmode{} then goes to | |
481 buffer position 46, which is the @samp{i} in @code{if} on line 3. This | |
482 character is in the fourth column on that line so adding this to the | |
483 running total yields an indentation for the line of 8 spaces. | |
484 | |
485 Simple, huh? | |
486 | |
487 Actually, the mode usually just does The Right Thing without you having | |
488 to think about it in this much detail. But when customizing | |
489 indentation, it's helpful to understand the general indentation model | |
490 being used. | |
491 | |
492 @vindex c-echo-syntactic-information-p | |
493 @vindex echo-syntactic-information-p (c-) | |
494 @cindex TAB | |
495 As you configure @ccmode{}, you might want to set the variable | |
496 @code{c-echo-syntactic-information-p} to non-@code{nil} so that the | |
497 syntactic component list and calculated offset will always be echoed in | |
498 the minibuffer when you hit @kbd{TAB}. | |
499 | |
500 | |
501 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
502 @node Minor Modes, Commands, New Indentation Engine, Top | |
503 @comment node-name, next, previous,up | |
504 | |
505 @chapter Minor Modes | |
506 @cindex Minor Modes | |
507 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
508 | |
509 @ccmode{} contains two minor-mode-like features that you should | |
510 find useful while you enter new C code. The first is called | |
511 @dfn{auto-newline} mode, and the second is called @dfn{hungry-delete} | |
512 mode. These minor modes can be toggled on and off independently, and | |
513 @ccmode{} can be configured so that it starts up with any | |
514 combination of these minor modes. By default, both of these minor modes | |
515 are turned off. | |
516 | |
517 The state of the minor modes is always reflected in the minor mode list | |
518 on the modeline of the @ccmode{} buffer. When auto-newline mode is | |
519 enabled, you will see @samp{C/a} on the mode line @footnote{Remember | |
520 that the @samp{C} could be replaced with @samp{C++}, @samp{ObjC}, | |
521 @samp{Java} or @samp{IDL}.}. When hungry delete mode is enabled you | |
522 would see @samp{C/h} and when both modes are enabled, you'd see | |
523 @samp{C/ah}. | |
524 | |
525 @kindex C-c C-a | |
526 @kindex C-c C-d | |
527 @kindex C-c C-t | |
528 @findex c-toggle-hungry-state | |
529 @findex c-toggle-auto-state | |
530 @findex c-toggle-auto-hungry-state | |
531 @findex toggle-hungry-state (c-) | |
532 @findex toggle-auto-state (c-) | |
533 @findex toggle-auto-hungry-state (c-) | |
534 @ccmode{} provides keybindings which allow you to toggle the minor | |
535 modes on the fly while editing code. To toggle just the auto-newline | |
536 state, hit @kbd{C-c C-a} (@code{c-toggle-auto-state}). When you do | |
537 this, you should see the @samp{a} indicator either appear or disappear | |
538 on the modeline. Similarly, to toggle just the hungry-delete state, use | |
539 @kbd{C-c C-d} (@code{c-toggle-hungry-state}), and to toggle both states, | |
540 use @kbd{C-c C-t} (@code{c-toggle-auto-hungry-state}). | |
541 | |
542 To set up the auto-newline and hungry-delete states to your preferred | |
543 values, you would need to add some lisp to your @file{.emacs} file that | |
544 called one of the @code{c-toggle-*-state} functions directly. When | |
545 called programmatically, each function takes a numeric value, where | |
546 a positive number enables the minor mode, a negative number disables the | |
547 mode, and zero toggles the current state of the mode. | |
548 | |
549 So for example, if you wanted to enable both auto-newline and | |
550 hungry-delete for all your C file editing, you could add the following | |
551 to your @file{.emacs} file: | |
552 @example | |
553 | |
554 (add-hook 'c-mode-common-hook | |
555 '(lambda () (c-toggle-auto-hungry-state 1))) | |
556 | |
557 @end example | |
558 | |
559 | |
560 @cindex electric characters | |
561 | |
562 @menu | |
563 * Auto-newline insertion:: | |
564 * Hungry-deletion of whitespace:: | |
565 * Auto-fill mode interaction:: | |
566 @end menu | |
567 | |
568 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
569 @node Auto-newline insertion, Hungry-deletion of whitespace, , Minor Modes | |
570 @comment node-name, next, previous,up | |
571 | |
572 @section Auto-newline insertion | |
573 @cindex Auto-newline insertion | |
574 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
575 | |
576 @cindex electric commands | |
577 Auto-newline minor mode works by enabling certain @dfn{electric | |
578 commands}. Electric commands are typically bound to special characters | |
579 such as the left and right braces, colons, semi-colons, etc., which when | |
580 typed, perform some magic formatting in addition to inserting the typed | |
581 character. As a general rule, electric commands are only electric when | |
582 the following conditions apply: | |
583 | |
584 @itemize @bullet | |
585 @item | |
586 Auto-newline minor mode is enabled, as evidenced by a @samp{C/a} or | |
587 @samp{C/ah} indicator on the modeline. | |
588 | |
589 @cindex literal | |
590 @cindex syntactic whitespace | |
591 @item | |
592 The character was not typed inside of a literal @footnote{A | |
593 @dfn{literal} is defined as any comment, string, or C preprocessor macro | |
594 definition. These constructs are also known as @dfn{syntactic | |
595 whitespace} since they are usually ignored when scanning C code.}. | |
596 | |
597 @item | |
598 @kindex C-u | |
599 No numeric argument was supplied to the command (i.e. it was typed as | |
600 normal, with no @kbd{C-u} prefix). | |
601 | |
602 @end itemize | |
603 | |
604 @menu | |
605 * Hanging Braces:: | |
606 * Hanging Colons:: | |
607 * Hanging Semi-colons and commas:: | |
608 * Other electric commands:: | |
609 * Clean-ups:: | |
610 @end menu | |
611 | |
612 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
613 @node Hanging Braces, Hanging Colons, , Auto-newline insertion | |
614 @comment node-name, next, previous,up | |
615 | |
616 @subsection Hanging Braces | |
617 @cindex Hanging Braces | |
618 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
619 | |
620 @findex c-electric-brace | |
621 @findex electric-brace (c-) | |
622 @vindex c-hanging-braces-alist | |
623 @vindex hanging-braces-alist (c-) | |
624 @vindex c-offsets-alist | |
625 @vindex offsets-alist (c-) | |
626 When you type either an open or close brace (i.e. @kbd{@{} or @kbd{@}}), | |
627 the electric command @code{c-electric-brace} gets run. This command has | |
628 two electric formatting behaviors. First, it will perform some | |
629 re-indentation of the line the brace was typed on, and second, it will | |
630 add various newlines before and/or after the typed brace. | |
631 Re-indentation occurs automatically whenever the electric behavior is | |
632 enabled. If the brace ends up on a line other than the one it was typed | |
633 on, then that line is also re-indented. | |
634 | |
635 @cindex class-open syntactic symbol | |
636 @cindex class-close syntactic symbol | |
637 @cindex defun-open syntactic symbol | |
638 @cindex defun-close syntactic symbol | |
639 @cindex inline-open syntactic symbol | |
640 @cindex inline-close syntactic symbol | |
641 @cindex brace-list-open syntactic symbol | |
642 @cindex brace-list-close syntactic symbol | |
643 @cindex brace-list-intro syntactic symbol | |
644 @cindex brace-list-entry syntactic symbol | |
645 @cindex block-open syntactic symbol | |
646 @cindex block-close syntactic symbol | |
647 @cindex substatement-open syntactic symbol | |
648 @cindex statement-case-open syntactic symbol | |
649 @cindex extern-lang-open syntactic symbol | |
650 @cindex extern-lang-close syntactic symbol | |
651 @cindex namespace-open symbol | |
652 @cindex namespace-close symbol | |
653 | |
654 The insertion of newlines is controlled by the | |
655 @code{c-hanging-braces-alist} variable. This variable contains a | |
656 mapping between syntactic symbols related to braces, and a list of | |
657 places to insert a newline. The syntactic symbols that are useful for | |
658 this list are: @code{class-open}, @code{class-close}, @code{defun-open}, | |
659 @code{defun-close}, @code{inline-open}, @code{inline-close}, | |
660 @code{brace-list-open}, @code{brace-list-close}, | |
661 @code{brace-list-intro}, @code{brace-list-entry}, @code{block-open}, | |
662 @code{block-close}, @code{substatement-open}, | |
663 @code{statement-case-open}, | |
664 @code{extern-lang-open}, @code{extern-lang-close}, | |
665 @code{namespace-open}, and @code{namespace-close}. | |
26490
2b08d829af86
Fix complaints from makeinfo 4.0.
Eli Zaretskii <eliz@gnu.org>
parents:
25829
diff
changeset
|
666 @xref{Syntactic Symbols}, for a more |
25829 | 667 detailed description of these syntactic symbols. |
668 | |
669 @cindex Custom Indentation Functions | |
670 The value associated with each syntactic symbol in this association list | |
671 is called an @var{ACTION} which can be either a function or a list. | |
26490
2b08d829af86
Fix complaints from makeinfo 4.0.
Eli Zaretskii <eliz@gnu.org>
parents:
25829
diff
changeset
|
672 @xref{Custom Brace and Colon Hanging}, for a more detailed discussion of |
25829 | 673 using a function as a brace hanging @var{ACTION}. |
674 | |
675 When the @var{ACTION} is a list, it can contain any combination of the | |
676 symbols @code{before} and @code{after}, directing @ccmode{} where to | |
677 put newlines in relationship to the brace being inserted. Thus, if the | |
678 list contains only the symbol @code{after}, then the brace is said to | |
679 @dfn{hang} on the right side of the line, as in: | |
680 @example | |
681 @group | |
682 | |
683 // here, open braces always `hang' | |
684 void spam( int i ) @{ | |
685 if( i == 7 ) @{ | |
686 dosomething(i); | |
687 @} | |
688 @} | |
689 | |
690 | |
691 @end group | |
692 @end example | |
693 | |
694 When the list contains both @code{after} and @code{before}, the braces | |
695 will appear on a line by themselves, as shown by the close braces in the | |
696 above example. The list can also be empty, in which case no newlines | |
697 are added either before or after the brace. | |
698 | |
699 For example, the default value of @code{c-hanging-braces-alist} is: | |
700 @example | |
701 @group | |
702 | |
703 (defvar c-hanging-braces-alist '((brace-list-open) | |
704 (substatement-open after) | |
705 (block-close . c-snug-do-while) | |
706 (extern-lang-open after))) | |
707 | |
708 @end group | |
709 @end example | |
710 | |
711 @noindent | |
712 which says that @code{brace-list-open} braces should both hang on the | |
713 right side, and allow subsequent text to follow on the same line as the | |
714 brace. Also, @code{substatement-open} and @code{extern-lang-open} | |
715 braces should hang on the right side, but subsequent text should follow | |
716 on the next line. Here, in the @code{block-close} entry, you also see | |
717 an example of using a function as an @var{ACTION}. | |
718 | |
719 A word of caution: it is not a good idea to hang top-level construct | |
720 introducing braces, such as @code{class-open} or @code{defun-open}. | |
721 Emacs makes an assumption that such braces will always appear in column | |
722 zero, hanging such braces can introduce performance problems. | |
26490
2b08d829af86
Fix complaints from makeinfo 4.0.
Eli Zaretskii <eliz@gnu.org>
parents:
25829
diff
changeset
|
723 @xref{Performance Issues}, for more information. |
25829 | 724 |
725 | |
726 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
727 @node Hanging Colons, Hanging Semi-colons and commas, Hanging Braces, Auto-newline insertion | |
728 @comment node-name, next, previous,up | |
729 | |
730 @subsection Hanging Colons | |
731 @cindex Hanging Colons | |
732 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
733 | |
734 @vindex hanging-colons-alist (c-) | |
735 @vindex c-hanging-colons-alist | |
736 Using a mechanism similar to brace hanging (see @ref{Hanging Braces}), | |
737 colons can also be made to hang using the variable | |
738 @code{c-hanging-colons-alist}. The syntactic symbols appropriate for | |
739 this assocation list are: @code{case-label}, @code{label}, | |
740 @code{access-label}, @code{member-init-intro}, and @code{inher-intro}. | |
741 Note however that for @code{c-hanging-colons-alist}, @var{ACTION}s as | |
742 functions are not supported. See also @ref{Custom Brace and Colon | |
743 Hanging} for details. | |
744 | |
745 @cindex Clean-ups | |
746 In C++, double-colons are used as a scope operator but because these | |
747 colons always appear right next to each other, newlines before and after | |
748 them are controlled by a different mechanism, called @dfn{clean-ups} in | |
26490
2b08d829af86
Fix complaints from makeinfo 4.0.
Eli Zaretskii <eliz@gnu.org>
parents:
25829
diff
changeset
|
749 @ccmode{}. @xref{Clean-ups}, for details. |
25829 | 750 |
751 | |
752 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
753 @node Hanging Semi-colons and commas, Other electric commands, Hanging Colons, Auto-newline insertion | |
754 @comment node-name, next, previous,up | |
755 | |
756 @subsection Hanging Semi-colons and commas | |
757 @cindex Hanging Semi-colons and commas | |
758 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
759 | |
760 Semicolons and commas are also electric in @ccmode{}, but since | |
761 these characters do not correspond directly to syntactic symbols, a | |
762 different mechanism is used to determine whether newlines should be | |
763 automatically inserted after these characters. @xref{Customizing | |
26490
2b08d829af86
Fix complaints from makeinfo 4.0.
Eli Zaretskii <eliz@gnu.org>
parents:
25829
diff
changeset
|
764 Semi-colons and Commas}, for details. |
25829 | 765 |
766 | |
767 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
768 @node Other electric commands, Clean-ups, Hanging Semi-colons and commas, Auto-newline insertion | |
769 @comment node-name, next, previous,up | |
770 | |
771 @subsection Other electric commands | |
772 @cindex Other electric commands | |
773 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
774 | |
775 @kindex # | |
776 @findex c-electric-pound | |
777 @vindex c-electric-pound-behavior | |
778 @findex electric-pound (c-) | |
779 @vindex electric-pound-behavior (c-) | |
780 @vindex c-offsets-alist | |
781 @vindex offsets-alist (c-) | |
782 A few other keys also provide electric behavior. For example | |
783 @kbd{#} (@code{c-electric-pound}) is electric when typed as | |
784 the first non-whitespace character on a line. In this case, the | |
785 variable @code{c-electric-pound-behavior} is consulted for the electric | |
786 behavior. This variable takes a list value, although the only element | |
787 currently defined is @code{alignleft}, which tells this command to force | |
788 the @samp{#} character into column zero. This is useful for entering | |
789 C preprocessor macro definitions. | |
790 | |
791 @findex c-electric-star | |
792 @findex c-electric-slash | |
793 @findex electric-star (c-) | |
794 @findex electric-slash (c-) | |
795 @cindex comment-only line | |
796 Stars and slashes (i.e. @kbd{*} and @kbd{/}, @code{c-electric-star} and | |
797 @code{c-electric-slash} respectively) are also electric under | |
798 certain circumstances. If a star is inserted as the second character of | |
799 a C style block comment on a @dfn{comment-only} line, then the comment | |
800 delimiter is indented as defined by @code{c-offsets-alist}. A | |
801 comment-only line is defined as a line which contains only a comment, as | |
802 in: | |
803 @example | |
804 @group | |
805 | |
806 void spam( int i ) | |
807 @{ | |
808 // this is a comment-only line... | |
809 if( i == 7 ) // but this is not | |
810 @{ | |
811 dosomething(i); | |
812 @} | |
813 @} | |
814 | |
815 @end group | |
816 @end example | |
817 | |
818 Likewise, if a slash is inserted as the second slash in a C++ style line | |
819 comment (also only on a comment-only line), then the line is indented as | |
820 defined by @code{c-offsets-alist}. | |
821 | |
822 @findex c-electric-lt-gt | |
823 @findex electric-lt-gt (c-) | |
824 @kindex < | |
825 @kindex > | |
826 Less-than and greater-than signs (@code{c-electric-lt-gt}) are also | |
827 electric, but only in C++ mode. Hitting the second of two @kbd{<} or | |
828 @kbd{>} keys re-indents the line if it is a C++ style stream operator. | |
829 | |
830 | |
831 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
832 @node Clean-ups, , Other electric commands, Auto-newline insertion | |
833 @comment node-name, next, previous,up | |
834 | |
835 @subsection Clean-ups | |
836 @cindex Clean-ups | |
837 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
838 | |
839 @dfn{Clean-ups} are a mechanism complementary to colon and brace | |
840 hanging. On the surface, it would seem that clean-ups overlap the | |
841 functionality provided by the @code{c-hanging-*-alist} variables, and | |
842 similarly, clean-ups are only enabled when auto-newline minor mode is | |
843 enabled. Clean-ups are used however to adjust code ``after-the-fact'', | |
844 i.e. to eliminate some whitespace that is inserted by electric | |
845 commands, or whitespace that contains intervening constructs. | |
846 | |
847 @cindex literal | |
848 You can configure @ccmode{}'s clean-ups by setting the variable | |
849 @code{c-cleanup-list}, which is a list of clean-up symbols. By default, | |
850 @ccmode{} cleans up only the @code{scope-operator} construct, which | |
851 is necessary for proper C++ support. Note that clean-ups are only | |
852 performed when the construct does not occur within a literal (see | |
853 @ref{Auto-newline insertion}), and when there is nothing but whitespace | |
854 appearing between the individual components of the construct. | |
855 | |
856 @vindex c-cleanup-list | |
857 @vindex cleanup-list (c-) | |
858 There are currently only five specific constructs that @ccmode{} | |
859 can clean up, as indicated by these symbols: | |
860 | |
861 @itemize @bullet | |
862 @item | |
863 @code{brace-else-brace} --- cleans up @samp{@} else @{} constructs by | |
864 placing the entire construct on a single line. Clean-up occurs when the | |
865 open brace after the @samp{else} is typed. So for example, this: | |
866 @example | |
867 @group | |
868 | |
869 void spam(int i) | |
870 @{ | |
871 if( i==7 ) | |
872 @{ | |
873 dosomething(); | |
874 @} | |
875 else | |
876 @{ | |
877 | |
878 @end group | |
879 @end example | |
880 @noindent | |
881 appears like this after the open brace is typed: | |
882 @example | |
883 @group | |
884 | |
885 void spam(int i) | |
886 @{ | |
887 if( i==7 ) @{ | |
888 dosomething(); | |
889 @} else @{ | |
890 | |
891 @end group | |
892 @end example | |
893 | |
894 @item | |
895 @code{brace-elseif-brace} --- similar to the @code{brace-else-brace} | |
896 clean-up, but this cleans up @samp{@} else if (...) @{} constructs. For | |
897 example: | |
898 @example | |
899 @group | |
900 | |
901 void spam(int i) | |
902 @{ | |
903 if( i==7 ) | |
904 @{ | |
905 dosomething(); | |
906 @} | |
907 else if( i==3 ) @{ | |
908 | |
909 @end group | |
910 @end example | |
911 @noindent | |
912 appears like this after the open brace is typed: | |
913 @example | |
914 @group | |
915 | |
916 void spam(int i) | |
917 @{ | |
918 if( i==7 ) @{ | |
919 dosomething(); | |
920 @} else if( i==3 ) @{ | |
921 | |
922 @end group | |
923 @end example | |
924 | |
925 @item | |
926 @code{empty-defun-braces} --- cleans up braces following a top-level | |
927 function or class definition that contains no body. Clean up occurs | |
928 when the closing brace is typed. Thus the following: | |
929 @example | |
930 @group | |
931 | |
932 class Spam | |
933 @{ | |
934 @} | |
935 | |
936 @end group | |
937 @end example | |
938 @noindent | |
939 is transformed into this when the close brace is typed: | |
940 @example | |
941 @group | |
942 | |
943 class Spam | |
944 @{@} | |
945 | |
946 @end group | |
947 @end example | |
948 | |
949 @item | |
950 @code{defun-close-semi} --- cleans up the terminating semi-colon on | |
951 top-level function or class definitions when they follow a close | |
952 brace. Clean up occurs when the semi-colon is typed. | |
953 So for example, the following: | |
954 @example | |
955 @group | |
956 | |
957 class Spam | |
958 @{ | |
959 @} | |
960 ; | |
961 | |
962 @end group | |
963 @end example | |
964 @noindent | |
965 is transformed into this when the semi-colon is typed: | |
966 | |
967 @example | |
968 @group | |
969 | |
970 class Spam | |
971 @{ | |
972 @}; | |
973 | |
974 @end group | |
975 @end example | |
976 | |
977 @item | |
978 @code{list-close-comma} --- cleans up commas following braces in array | |
979 and aggregate initializers. Clean up occurs when the comma is typed. | |
980 | |
981 @item | |
982 @code{scope-operator} --- cleans up double colons which may designate a | |
983 C++ scope operator split across multiple lines@footnote{Certain C++ | |
984 constructs introduce ambiguous situations, so @code{scope-operator} | |
985 clean-ups may not always be correct. This usually only occurs when | |
986 scoped identifiers appear in switch label tags.}. Clean up occurs when | |
987 the second colon is typed. You will always want @code{scope-operator} | |
988 in the @code{c-cleanup-list} when you are editing C++ code. | |
989 | |
990 @end itemize | |
991 | |
992 | |
993 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
994 @node Hungry-deletion of whitespace, Auto-fill mode interaction, Auto-newline insertion, Minor Modes | |
995 @comment node-name, next, previous,up | |
996 | |
997 @section Hungry-deletion of whitespace | |
998 @cindex Hungry-deletion of whitespace | |
999 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
1000 | |
1001 Hungry deletion of whitespace, or as it more commonly called, | |
1002 @dfn{hungry-delete mode}, is a simple feature that some people find | |
1003 extremely useful. In fact, you might find yourself wanting | |
1004 hungry-delete in @strong{all} your editing modes! | |
1005 | |
1006 @kindex DEL | |
1007 @kindex Backspace | |
1008 In a nutshell, when hungry-delete mode is enabled, hitting the | |
1009 @key{Backspace} key@footnote{I say ``hit the @key{Backspace} key'' but | |
1010 what I really mean is ``when Emacs receives the @code{BackSpace} key | |
1011 event''. The difference usually isn't significant to most users, but | |
1012 advanced users will realize that under window systems such as X, any | |
1013 physical key (keycap) on the keyboard can be configured to generate any | |
1014 keysym, and thus any Emacs key event. Also, the use of Emacs on TTYs | |
1015 will affect which keycap generates which key event. From a pedantic | |
1016 point of view, here we are only concerned with the key event that | |
1017 Emacs receives.} will consume all preceding whitespace, including | |
1018 newlines and tabs. This can really cut down on the number of | |
1019 @key{Backspace}'s you have to type if, for example you made a mistake on | |
1020 the preceding line. | |
1021 | |
1022 @findex c-electric-backspace | |
1023 @findex electric-backspace (c-) | |
1024 @vindex c-backspace-function | |
1025 @vindex backspace-function (c-) | |
1026 | |
1027 @findex c-electric-delete | |
1028 @findex electric-delete (c-) | |
1029 @vindex c-delete-function | |
1030 @vindex delete-function (c-) | |
1031 @cindex literal | |
1032 | |
1033 @findex backward-delete-char-untabify | |
1034 | |
1035 By default, when you hit the @key{Backspace} key | |
1036 @ccmode{} runs the command @code{c-electric-backspace}, which deletes | |
1037 text in the backwards direction. When deleting a single character, or | |
1038 when @key{Backspace} is hit in a literal | |
1039 (see @ref{Auto-newline insertion}), | |
1040 or when hungry-delete mode is disabled, the function | |
1041 contained in the @code{c-backspace-function} variable is called with one | |
1042 argument (the number of characters to delete). This variable is set to | |
1043 @code{backward-delete-char-untabify} by default. | |
1044 | |
1045 @vindex delete-key-deletes-forward | |
1046 @findex delete-char | |
1047 | |
1048 Similarly, hitting the @key{Delete} key runs the command | |
1049 @code{c-electric-delete}. When deleting a single character, or when | |
1050 @key{Delete} is hit in a literal, or when hungry-delete mode is | |
1051 disabled, the function contained in the @code{c-delete-function} | |
1052 variable is called with one argument (the number of characters to | |
1053 delete). This variable is set to @code{delete-char} by default. | |
1054 | |
1055 However, if @code{delete-key-deletes-forward} is @code{nil}, or your | |
1056 Emacs does not support separation of @key{Backspace} and @key{DEL}, then | |
1057 @code{c-electric-delete} simply calls @code{c-electric-backspace}. | |
1058 | |
1059 | |
1060 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
1061 @node Auto-fill mode interaction, , Hungry-deletion of whitespace, Minor Modes | |
1062 @comment node-name, next, previous,up | |
1063 | |
1064 @section Auto-fill mode interaction | |
1065 @cindex Auto-fill mode interaction | |
1066 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
1067 | |
1068 One other note about minor modes is worth mentioning here. CC Mode now | |
1069 works much better with auto-fill mode (a standard Emacs minor mode) by | |
1070 correctly auto-filling both line (e.g. C++ style) and block (e.g. C | |
1071 style) oriented comments. When @code{auto-fill-mode} is enabled, line | |
1072 oriented comments will also be auto-filled by inserting a newline at the | |
1073 line break, and inserting @samp{//} at the start of the next line. | |
1074 | |
1075 @vindex c-comment-continuation-stars | |
1076 @vindex comment-continuation-stars (c-) | |
1077 @vindex comment-line-break-function | |
1078 When auto-filling block oriented comments, the behavior is dependent on | |
1079 the value of the variable @code{c-comment-continuation-stars}. When | |
1080 this variable is @code{nil}, the old behavior for auto-filling C | |
1081 comments is in effect. In this case, the line is broken by closing the | |
1082 comment and starting a new comment on the next line. | |
1083 | |
1084 If you set @code{c-comment-continuation-stars} to a string, then a long | |
1085 C block comment line is broken by inserting a newline at the line break | |
1086 position, and inserting this string at the beginning of the next comment | |
1087 line. The default value for @code{c-comment-continuation-stars} is | |
1088 @samp{* } (a star followed by a single space)@footnote{To get block | |
1089 comment continuation lines indented under the block comment starter | |
1090 (e.g. the @samp{/*}), it is not enough to set | |
1091 @code{c-comment-continuation-stars} to the empty string. You need to do | |
1092 this, but you also need to set the offset for the @code{c} syntactic | |
1093 symbol to be zero.}. | |
1094 | |
1095 | |
1096 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
1097 @node Commands, Customizing Indentation, Minor Modes, Top | |
1098 @comment node-name, next, previous,up | |
1099 | |
1100 @chapter Commands | |
1101 @cindex Commands | |
1102 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
1103 | |
1104 @menu | |
1105 * Indentation Commands:: | |
1106 * Other Commands:: | |
1107 @end menu | |
1108 | |
1109 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
1110 @node Indentation Commands, Other Commands, , Commands | |
1111 @comment node-name, next, previous,up | |
1112 | |
1113 @section Indentation Commands | |
1114 @cindex Indentation Commands | |
1115 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
1116 | |
1117 Various commands are provided which allow you to conveniently re-indent | |
1118 C constructs. There are several things to | |
1119 note about these indentation commands. First, when you | |
1120 change your programming style, either interactively or through some | |
1121 other means, your file does @emph{not} automatically get re-indented. | |
1122 When you change style parameters, you will typically need to reformat | |
1123 the line, expression, or buffer to see the effects of your changes. | |
1124 | |
1125 @cindex c-hanging- functions | |
1126 @findex c-hanging-braces-alist | |
1127 @findex hanging-braces-alist (c-) | |
1128 Second, changing some variables have no effect on existing code, even | |
1129 when you do re-indent. For example, the @code{c-hanging-*} variables | |
1130 and @code{c-cleanup-list} only affect new code as it is typed in | |
1131 on-the-fly, so changing @code{c-hanging-braces-alist} and re-indenting | |
1132 the buffer will not adjust placement of braces already in the file. | |
1133 | |
1134 @vindex c-progress-interval | |
1135 @vindex progress-interval (c-) | |
1136 Third, re-indenting large portions of code is currently rather | |
1137 inefficient. Improvements have been made since previous releases of | |
1138 @ccmode{}, and much more radical improvements are planned, but for now | |
1139 you need to be aware of this @footnote{In particular, I have had people | |
1140 complain about the speed with which @code{lex(1)} output is re-indented. | |
1141 Lex, yacc, and other code generators usually output some pretty | |
1142 perversely formatted code. @emph{Don't} try to indent this stuff!}. | |
1143 Some provision has been made to at least inform you as to the progress | |
1144 of the re-indentation. The variable @code{c-progress-interval} controls | |
1145 how often a progress message is displayed. Set this variable to | |
1146 @code{nil} to inhibit progress messages, including messages normally | |
1147 printed when indentation is started and completed. | |
1148 | |
1149 Also, except as noted below, re-indentation is always driven by the | |
1150 same mechanisms that control on-the-fly indentation of code. @xref{New | |
26490
2b08d829af86
Fix complaints from makeinfo 4.0.
Eli Zaretskii <eliz@gnu.org>
parents:
25829
diff
changeset
|
1151 Indentation Engine}, for details. |
25829 | 1152 |
1153 @findex c-indent-command | |
1154 @findex indent-command (c-) | |
1155 @vindex c-tab-always-indent | |
1156 @vindex tab-always-indent (c-) | |
1157 @kindex TAB | |
1158 @cindex literal | |
1159 @vindex indent-tabs-mode | |
1160 @vindex c-insert-tab-function | |
1161 @vindex insert-tab-function (c-) | |
1162 @findex tab-to-tab-stop | |
1163 To indent a single line of code, use @kbd{TAB} | |
1164 (@code{c-indent-command}). The behavior of this command is controlled | |
1165 by the variable @code{c-tab-always-indent}. When this variable is | |
1166 @code{t}, @kbd{TAB} always just indents the current line. When | |
1167 @code{nil}, the line is indented only if point is at the left margin, or | |
1168 on or before the first non-whitespace character on the line, otherwise | |
1169 @emph{something else happens}@footnote{Actually what happens is that the | |
1170 function stored in @code{c-insert-tab-function} is called. | |
1171 Normally this just inserts a real tab character, or the equivalent | |
1172 number of spaces, depending on the setting of the variable | |
1173 @code{indent-tabs-mode}. If you preferred, you could set | |
1174 @code{c-insert-tab-function} to @code{tab-to-tab-stop} for example.}. | |
1175 If the value of @code{c-tab-always-indent} is something other than | |
1176 @code{t} or @code{nil} (e.g. @code{'other}), then a real tab | |
1177 character@footnote{The caveat about @code{indent-tabs-mode} in the | |
1178 previous footnote also applies here.} is inserted only when point is | |
1179 inside a literal (see @ref{Auto-newline insertion}), otherwise the line | |
1180 is indented. | |
1181 | |
1182 @kindex M-C-q | |
1183 @findex c-indent-exp | |
1184 @findex indent-exp (c-) | |
1185 To indent an entire balanced brace or parenthesis expression, use | |
1186 @kbd{M-C-q} (@code{c-indent-exp}). Note that point should be on | |
1187 the opening brace or parenthesis of the expression you want to indent. | |
1188 | |
1189 @kindex C-c C-q | |
1190 @findex c-indent-defun | |
1191 @findex indent-defun (c-) | |
1192 Another very convenient keystroke is @kbd{C-c C-q} | |
1193 (@code{c-indent-defun}) when re-indents the entire top-level function or | |
1194 class definition that encompasses point. It leaves point at the | |
1195 same position within the buffer. | |
1196 | |
1197 @kindex M-C-\ | |
1198 @findex indent-region | |
1199 To indent any arbitrary region of code, use @kbd{M-C-\} | |
1200 (@code{indent-region}). This is a standard Emacs command, specially | |
1201 tailored for C code in a @ccmode{} buffer. Note that of course, | |
1202 point and mark must delineate the region you | |
1203 want to indent. | |
1204 | |
1205 @kindex M-C-h | |
1206 @findex c-mark-function | |
1207 @findex mark-function (c-) | |
1208 While not strictly an indentation function, @kbd{M-C-h} | |
1209 (@code{c-mark-function}) is useful for marking the current top-level | |
1210 function or class definition as the current region. | |
1211 | |
1212 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
1213 @node Other Commands, , Indentation Commands, Commands | |
1214 @comment node-name, next, previous,up | |
1215 | |
1216 @section Other Commands | |
1217 @cindex Other Commands | |
1218 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
1219 | |
1220 @ccmode{} contains other useful command for moving around in C | |
1221 code. | |
1222 | |
1223 @table @code | |
1224 @findex c-beginning-of-defun | |
1225 @findex beginning-of-defun (c-) | |
1226 @findex beginning-of-defun | |
1227 @item M-x c-beginning-of-defun | |
1228 Moves point back to the least-enclosing brace. This function is | |
1229 analogous to the Emacs built-in command @code{beginning-of-defun}, | |
1230 except it eliminates the constraint that the top-level opening brace | |
1231 must be in column zero. See @code{beginning-of-defun} for more | |
1232 information. | |
1233 | |
1234 Depending on the coding style being used, you might prefer | |
1235 @code{c-beginning-of-defun} to @code{beginning-of-defun}. If so, | |
1236 consider binding @kbd{C-M-a} to the former instead. For backwards | |
1237 compatibility reasons, the default binding remains in effect. | |
1238 | |
1239 @findex c-end-of-defun | |
1240 @findex end-of-defun (c-) | |
1241 @findex end-of-defun | |
1242 @item M-x c-end-of-defun | |
1243 Moves point to the end of the current top-level definition. This | |
1244 function is analogous to the Emacs built-in command @code{end-of-defun}, | |
1245 except it eliminates the constraint that the top-level opening brace of | |
1246 the defun must be in column zero. See @code{beginning-of-defun} for more | |
1247 information. | |
1248 | |
1249 Depending on the coding style being used, you might prefer | |
1250 @code{c-end-of-defun} to @code{end-of-defun}. If so, | |
1251 consider binding @kbd{C-M-e} to the former instead. For backwards | |
1252 compatibility reasons, the default binding remains in effect. | |
1253 | |
1254 @kindex C-c C-u | |
1255 @findex c-up-conditional | |
1256 @findex up-conditional (c-) | |
1257 @item C-c C-u (c-up-conditional) | |
1258 Move point back to the containing preprocessor conditional, leaving the | |
1259 mark behind. A prefix argument acts as a repeat count. With a negative | |
1260 argument, move point forward to the end of the containing | |
1261 preprocessor conditional. When going backwards, @code{#elif} is treated | |
1262 like @code{#else} followed by @code{#if}. When going forwards, | |
1263 @code{#elif} is ignored.@refill | |
1264 | |
1265 @kindex C-c C-p | |
1266 @findex c-backward-conditional | |
1267 @findex backward-conditional (c-) | |
1268 @item C-c C-p (c-backward-conditional) | |
1269 Move point back over a preprocessor conditional, leaving the mark | |
1270 behind. A prefix argument acts as a repeat count. With a negative | |
1271 argument, move forward. | |
1272 | |
1273 @kindex C-c C-n | |
1274 @findex c-forward-conditional | |
1275 @findex forward-conditional (c-) | |
1276 @item C-c C-n (c-forward-conditional) | |
1277 Move point forward across a preprocessor conditional, leaving the mark | |
1278 behind. A prefix argument acts as a repeat count. With a negative | |
1279 argument, move backward. | |
1280 | |
1281 @kindex ESC a | |
1282 @findex c-beginning-of-statement | |
1283 @findex beginning-of-statement (c-) | |
1284 @item M-a (c-beginning-of-statement) | |
1285 Move point to the beginning of the innermost C statement. If point is | |
1286 already at the beginning of a statement, it moves to the beginning of | |
1287 the closest preceding statement, even if that means moving into a block | |
1288 (you can use @kbd{M-C-b} to move over a balanced block). With prefix | |
1289 argument @var{n}, move back @var{n} @minus{} 1 statements. | |
1290 | |
1291 If point is within a comment, or next to a comment, this command moves | |
1292 by sentences instead of statements. | |
1293 | |
1294 When called from a program, this function takes three optional | |
1295 arguments: the numeric prefix argument, a buffer position limit (used as | |
1296 a starting point for syntactic parsing and as a limit for backward | |
1297 movement), and a flag to indicate whether movement should be by | |
1298 statements (if @code{nil}) or sentence (if non-@code{nil}). | |
1299 | |
1300 @kindex ESC e | |
1301 @findex c-end-of-statement | |
1302 @findex end-of-statement (c-) | |
1303 @item M-e (c-end-of-statement) | |
1304 Move point to the end of the innermost C statement. If point is at the | |
1305 end of a statement, move to the end of the next statement, even if it's | |
1306 inside a nested block (use @kbd{M-C-f} to move to the other side of the | |
1307 block). With prefix argument @var{n}, move forward @var{n} @minus{} 1 | |
1308 statements. | |
1309 | |
1310 If point is within a comment, or next to a comment, this command moves | |
1311 by sentences instead of statements. | |
1312 | |
1313 When called from a program, this function takes three optional | |
1314 arguments: the numeric prefix argument, a buffer position limit (used as | |
1315 a starting point for syntactic parsing and as a limit for backward | |
1316 movement), and a flag to indicate whether movement should be by | |
1317 statements (if @code{nil}) or sentence (if non-@code{nil}). | |
1318 | |
1319 @findex c-forward-into-nomenclature | |
1320 @findex forward-into-nomenclature (c-) | |
1321 @item M-x c-forward-into-nomenclature | |
1322 A popular programming style, especially for object-oriented languages | |
1323 such as C++ is to write symbols in a mixed case format, where the first | |
1324 letter of each word is capitalized, and not separated by underscores. | |
1325 E.g. @samp{SymbolsWithMixedCaseAndNoUnderlines}. | |
1326 | |
1327 This command moves point forward to next capitalized word. With prefix | |
1328 argument @var{n}, move @var{n} times. | |
1329 | |
1330 @findex c-backward-into-nomenclature | |
1331 @findex backward-into-nomenclature (c-) | |
1332 @item M-x c-backward-into-nomenclature | |
1333 Move point backward to beginning of the next capitalized | |
1334 word. With prefix argument @var{n}, move @var{n} times. If | |
1335 @var{n} is negative, move forward. | |
1336 | |
1337 @kindex C-c : | |
1338 @findex c-scope-operator | |
1339 @findex scope-operator (c-) | |
1340 @item C-c : (c-scope-operator) | |
1341 In C++, it is also sometimes desirable to insert the double-colon scope | |
1342 operator without performing the electric behavior of colon insertion. | |
1343 @kbd{C-c :} does just this. | |
1344 | |
1345 @kindex ESC q | |
1346 @findex fill-paragraph | |
1347 @vindex c-hanging-comment-starter-p | |
1348 @vindex c-hanging-comment-ender-p | |
1349 @vindex hanging-comment-starter-p (c-) | |
1350 @vindex hanging-comment-ender-p (c-) | |
1351 @item M-q (fill-paragraph) | |
1352 The command is used to fill a block style (C) or line style (C++) | |
1353 comment, in much the same way that text in the various text modes can be | |
1354 filled@footnote{You should not use specialized filling packages such as | |
1355 @code{filladapt} with CC Mode. They don't work as well for filling as | |
1356 @code{c-fill-paragraph}}. You should never attempt to fill non-comment | |
1357 code sections; you'll end up with garbage! Two variables control how C | |
1358 style block comments are filled, specifically how the comment start and | |
1359 end delimiters are handled. | |
1360 | |
1361 The variable @code{c-hanging-comment-starter-p} controls whether comment | |
1362 start delimiters which appear on a line by themselves, end up on a line | |
1363 by themselves after the fill. When the value is @code{nil}, the comment | |
1364 starter will remain on its own line@footnote{It will not be placed on a | |
1365 separate line if it is not already on a separate line.}. Otherwise, | |
1366 text on the next line will be put on the same line as the comment | |
1367 starter. This is called @dfn{hanging} because the following text hangs | |
1368 on the line with the comment starter@footnote{This variable is @code{t} | |
1369 by default, except in @code{java-mode}. Hanging comment starters mess | |
1370 up Javadoc style comments.} | |
1371 | |
1372 The variable @code{c-hanging-comment-ender-p} controls the analogous | |
1373 behavior for the block comment end delimiter. When the value is | |
1374 @code{nil}, the comment ender will remain on its own line after the | |
1375 file@footnote{The same caveat as above holds true.}. Otherwise, the | |
1376 comment end delimiter will be placed at the end of the previous line. | |
1377 | |
1378 @end table | |
1379 | |
1380 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
1381 @node Customizing Indentation, Syntactic Symbols, Commands, Top | |
1382 @comment node-name, next, previous,up | |
1383 | |
1384 @chapter Customizing Indentation | |
1385 @cindex Customizing Indentation | |
1386 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
1387 | |
1388 @vindex c-offsets-alist | |
1389 @vindex offsets-alist (c-) | |
1390 @cindex c-set-offset | |
1391 @cindex set-offset (c-) | |
1392 The variable @code{c-offsets-alist} contains the mappings between | |
1393 syntactic symbols and the offsets to apply for those symbols. You | |
1394 should never modify this variable directly though. Use the function | |
1395 @code{c-set-offset} instead (see below for details). | |
1396 | |
1397 The @code{c-offsets-alist} variable is where you customize all your | |
1398 indentations. You simply need to decide what additional offset you want | |
1399 to add for every syntactic symbol. You can use the command @kbd{C-c | |
1400 C-o} (@code{c-set-offset}) as the way to set offsets, both interactively | |
1401 and from your mode hook. Also, you can set up @emph{styles} of | |
1402 indentatio. Most likely, you'll | |
1403 find one of the pre-defined styles will suit your needs, but if not, | |
1404 this section will describe how to set up basic editing configurations. | |
26490
2b08d829af86
Fix complaints from makeinfo 4.0.
Eli Zaretskii <eliz@gnu.org>
parents:
25829
diff
changeset
|
1405 @xref{Styles}, for an explanation of how to set up named styles. |
25829 | 1406 |
1407 @cindex c-basic-offset | |
1408 @cindex basic-offset (c-) | |
1409 As mentioned previously, the variable @code{c-offsets-alist} is an | |
1410 association list of syntactic symbols and the offsets to be applied for | |
1411 those symbols. In fact, these offset values can be any of an integer, a | |
1412 function or lambda expression, a variable name, or one of the following | |
1413 symbols: @code{+}, @code{-}, @code{++}, @code{--}, @code{*}, or | |
1414 @code{/}. These symbols describe offset in multiples of the value of | |
1415 the variable @code{c-basic-offset}. By defining a style's indentation | |
1416 in terms of this fundamental variable, you can change the amount of | |
1417 whitespace given to an indentation level while leaving the same | |
1418 relationship between levels. Here are the values that the special | |
1419 symbols correspond to: | |
1420 | |
1421 @table @code | |
1422 | |
1423 @item + | |
1424 @code{c-basic-offset} times 1 | |
1425 @item - | |
1426 @code{c-basic-offset} times -1 | |
1427 @item ++ | |
1428 @code{c-basic-offset} times 2 | |
1429 @item -- | |
1430 @code{c-basic-offset} times -2 | |
1431 @item * | |
1432 @code{c-basic-offset} times 0.5 | |
1433 @item / | |
1434 @code{c-basic-offset} times -0.5 | |
1435 | |
1436 @end table | |
1437 | |
1438 @vindex c-style-variables-are-local-p | |
1439 @vindex style-variables-are-local-p (c-) | |
1440 @noindent | |
1441 So, for example, because most of the default offsets are defined in | |
1442 terms of @code{+}, @code{-}, and @code{0}, if you like the general | |
1443 indentation style, but you use 4 spaces instead of 2 spaces per level, | |
1444 you can probably achieve your style just by changing | |
1445 @code{c-basic-offset} like so (in your @file{.emacs} file): | |
1446 @example | |
1447 | |
1448 (setq c-basic-offset 4) | |
1449 | |
1450 @end example | |
1451 | |
1452 @noindent | |
1453 This would change | |
1454 @example | |
1455 @group | |
1456 | |
1457 int add( int val, int incr, int doit ) | |
1458 @{ | |
1459 if( doit ) | |
1460 @{ | |
1461 return( val + incr ); | |
1462 @} | |
1463 return( val ); | |
1464 @} | |
1465 | |
1466 @end group | |
1467 @end example | |
1468 @noindent | |
1469 to | |
1470 @example | |
1471 @group | |
1472 | |
1473 int add( int val, int incr, int doit ) | |
1474 @{ | |
1475 if( doit ) | |
1476 @{ | |
1477 return( val + incr ); | |
1478 @} | |
1479 return( val ); | |
1480 @} | |
1481 | |
1482 @end group | |
1483 @end example | |
1484 | |
1485 | |
1486 To change indentation styles more radically, you will want to change the | |
1487 value associated with the syntactic symbols in the | |
1488 @code{c-offsets-alist} variable. First, I'll show you how to do that | |
1489 interactively, then I'll describe how to make changes to your | |
1490 @file{.emacs} file so that your changes are more permanent. | |
1491 | |
1492 @menu | |
1493 * Interactive Customization:: | |
1494 * Permanent Customization:: | |
1495 * Styles:: | |
1496 * Advanced Customizations:: | |
1497 @end menu | |
1498 | |
1499 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
1500 @node Interactive Customization, Permanent Customization, , Customizing Indentation | |
1501 @comment node-name, next, previous,up | |
1502 | |
1503 @section Interactive Customization | |
1504 @cindex Interactive Customization | |
1505 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
1506 | |
1507 As an example of how to customize indentation, let's change the | |
1508 style of this example@footnote{In this an subsequent examples, the | |
1509 original code is formatted using the @samp{gnu} style unless otherwise | |
1510 indicated. @xref{Styles}.}: | |
1511 @example | |
1512 @group | |
1513 | |
1514 1: int add( int val, int incr, int doit ) | |
1515 2: @{ | |
1516 3: if( doit ) | |
1517 4: @{ | |
1518 5: return( val + incr ); | |
1519 6: @} | |
1520 7: return( val ); | |
1521 8: @} | |
1522 | |
1523 @end group | |
1524 @end example | |
1525 @noindent | |
1526 to: | |
1527 @example | |
1528 @group | |
1529 | |
1530 1: int add( int val, int incr, int doit ) | |
1531 2: @{ | |
1532 3: if( doit ) | |
1533 4: @{ | |
1534 5: return( val + incr ); | |
1535 6: @} | |
1536 7: return( val ); | |
1537 8: @} | |
1538 | |
1539 @end group | |
1540 @end example | |
1541 | |
1542 In other words, we want to change the indentation of braces that open a | |
1543 block following a condition so that the braces line up under the | |
1544 conditional, instead of being indented. Notice that the construct we | |
1545 want to change starts on line 4. To change the indentation of a line, | |
1546 we need to see which syntactic components affect the offset calculations | |
1547 for that line. Hitting @kbd{C-c C-s} on line 4 yields: | |
1548 @example | |
1549 | |
1550 ((substatement-open . 44)) | |
1551 | |
1552 @end example | |
1553 | |
1554 @findex c-set-offset | |
1555 @findex set-offset (c-) | |
1556 @kindex C-c C-o | |
1557 @noindent | |
1558 so we know that to change the offset of the open brace, we need to | |
1559 change the indentation for the @code{substatement-open} syntactic | |
1560 symbol. To do this interactively, just hit @kbd{C-c C-o} | |
1561 (@code{c-set-offset}). This prompts you for the syntactic symbol to | |
1562 change, providing a reasonable default. In this case, the default is | |
1563 @code{substatement-open}, which is just the syntactic symbol we want to | |
1564 change! | |
1565 | |
1566 After you hit return, @ccmode{} will then prompt you for the new | |
1567 offset value, with the old value as the default. The default in this | |
1568 case is @samp{+}, but we want no extra indentation so enter | |
1569 @samp{0} and @kbd{RET}. This will associate the offset 0 with the | |
1570 syntactic symbol @code{substatement-open} in the @code{c-offsets-alist} | |
1571 variable. | |
1572 | |
1573 @findex c-indent-defun | |
1574 @findex indent-defun (c-) | |
1575 @kindex C-c C-q | |
1576 To check your changes quickly, just hit @kbd{C-c C-q} | |
1577 (@code{c-indent-defun}) to reindent the entire function. The example | |
1578 should now look like: | |
1579 @example | |
1580 @group | |
1581 | |
1582 1: int add( int val, int incr, int doit ) | |
1583 2: @{ | |
1584 3: if( doit ) | |
1585 4: @{ | |
1586 5: return( val + incr ); | |
1587 6: @} | |
1588 7: return( val ); | |
1589 8: @} | |
1590 | |
1591 @end group | |
1592 @end example | |
1593 | |
1594 Notice how just changing the open brace offset on line 4 is all we | |
1595 needed to do. Since the other affected lines are indented relative to | |
1596 line 4, they are automatically indented the way you'd expect. For more | |
1597 complicated examples, this may not always work. The general approach to | |
1598 take is to always start adjusting offsets for lines higher up in the | |
1599 file, then re-indent and see if any following lines need further | |
1600 adjustments. | |
1601 | |
1602 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
1603 @node Permanent Customization, Styles, Interactive Customization, Customizing Indentation | |
1604 @comment node-name, next, previous,up | |
1605 | |
1606 @section Permanent Customization | |
1607 @cindex Permanent Customization | |
1608 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
1609 | |
1610 @vindex c-mode-common-hook | |
1611 @vindex c-mode-hook | |
1612 @vindex c++-mode-hook | |
1613 @vindex objc-mode-hook | |
1614 @vindex java-mode-hook | |
1615 @vindex idl-mode-hook | |
1616 @vindex c-initialization-hook | |
1617 @vindex initialization-hook (c-) | |
1618 @cindex hooks | |
1619 To make your changes permanent, you need to add some lisp code to your | |
1620 @file{.emacs} file, but first you need to decide whether your styles | |
1621 should be global in every buffer, or local to each specific buffer. | |
1622 | |
1623 If you edit primarily one style of code, you may want to make the | |
1624 @ccmode{} style variables have global values so that every buffer will | |
1625 share the style settings. This will allow you to set the @ccmode{} | |
1626 variables at the top level of your @file{.emacs} file, and is the | |
1627 way @ccmode{} works by default. | |
1628 | |
1629 @vindex c-mode-common-hook | |
1630 @vindex mode-common-hook (c-) | |
1631 @vindex c-style-variables-are-local-p | |
1632 @vindex style-variables-are-local-p (c-) | |
1633 If you edit many different styles of code at | |
1634 the same time, you might want to make the @ccmode{} style variables | |
1635 have buffer local values. If you do this, then you will need to set any | |
1636 @ccmode{} style variables in a hook function (e.g. off of | |
1637 @code{c-mode-common-hook} instead of at the top level of your | |
1638 @file{.emacs} file). The recommended way to do this is to set the | |
1639 variable @code{c-style-variables-are-local-p} to @code{t} | |
1640 @strong{before} @ccmode{} is loaded into your Emacs session. | |
1641 | |
1642 @ccmode{} provides several hooks that you can | |
1643 use to customize the mode according to your coding style. Each language | |
1644 mode has its own hook, adhering to standard Emacs major mode | |
1645 conventions. There is also one general hook and one package | |
1646 initialization hook: | |
1647 | |
1648 @itemize @bullet | |
1649 | |
1650 @item | |
1651 @code{c-mode-hook} --- for C buffers only | |
1652 @item | |
1653 @code{c++-mode-hook} --- for C++ buffers only | |
1654 @item | |
1655 @code{objc-mode-hook} --- for Objective-C buffers only | |
1656 @item | |
1657 @code{java-mode-hook} --- for Java buffers only | |
1658 @item | |
1659 @code{idl-mode-hook} --- for IDL buffers only | |
1660 @item | |
1661 @code{c-mode-common-hook} --- common across all languages | |
1662 @item | |
1663 @code{c-initialization-hook} --- hook run only once per Emacs session, | |
1664 when @ccmode{} is initialized. | |
1665 | |
1666 @end itemize | |
1667 | |
1668 The language hooks get run as the last thing when you enter that | |
1669 language mode. The @code{c-mode-common-hook} is run by all | |
1670 supported modes @emph{before} the language specific hook, and thus can | |
1671 contain customizations that are common across all languages. Most of | |
1672 the examples in this section will assume you are using the common | |
1673 hook@footnote{The interaction between @code{java-mode} and the hook | |
1674 variables is slightly different than for the other modes. | |
1675 @code{java-mode} sets the style (see @ref{Styles}) of the buffer to | |
1676 @samp{java} @emph{before} running the @code{c-mode-common-hook} or | |
1677 @code{java-mode-hook}. You need to be aware of this so that style | |
1678 settings in @code{c-mode-common-hook} don't clobber your Java style.}. | |
1679 | |
1680 Here's a simplified example of what you can add to your @file{.emacs} | |
1681 file to make the changes described in the previous section | |
1682 (@ref{Interactive Customization}) more permanent. See the Emacs manuals | |
1683 for more information on customizing Emacs via hooks. @xref{Sample | |
26490
2b08d829af86
Fix complaints from makeinfo 4.0.
Eli Zaretskii <eliz@gnu.org>
parents:
25829
diff
changeset
|
1684 .emacs File}, for a more complete sample @file{.emacs} file. |
25829 | 1685 @example |
1686 @group | |
1687 | |
1688 (defun my-c-mode-common-hook () | |
1689 ;; my customizations for all of c-mode and related modes | |
1690 (c-set-offset 'substatement-open 0) | |
1691 ;; other customizations can go here | |
1692 ) | |
1693 (add-hook 'c-mode-common-hook 'my-c-mode-common-hook) | |
1694 | |
1695 @end group | |
1696 @end example | |
1697 | |
1698 For complex customizations, you will probably want to set up a | |
1699 @emph{style} that groups all your customizations under a single | |
1700 name. | |
1701 | |
1702 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
1703 @node Styles, Advanced Customizations, Permanent Customization, Customizing Indentation | |
1704 @comment node-name, next, previous,up | |
1705 | |
1706 @section Styles | |
1707 @cindex Styles | |
1708 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
1709 | |
1710 Most people only need to edit code formatted in just a few well-defined | |
1711 and consistent styles. For example, their organization might impose a | |
1712 ``blessed'' style that all its programmers must conform to. Similarly, | |
1713 people who work on GNU software will have to use the GNU coding style on | |
1714 C code. Some shops are more lenient, allowing a variety of coding | |
1715 styles, and as programmers come and go, there could be a number of | |
1716 styles in use. For this reason, @ccmode{} makes it convenient for | |
1717 you to set up logical groupings of customizations called @dfn{styles}, | |
1718 associate a single name for any particular style, and pretty easily | |
1719 start editing new or existing code using these styles. | |
1720 | |
1721 @menu | |
1722 * Built-in Styles:: | |
1723 * Adding Styles:: | |
1724 * File Styles:: | |
1725 @end menu | |
1726 | |
1727 | |
1728 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
1729 @node Built-in Styles, Adding Styles, , Styles | |
1730 @comment node-name, next, previous,up | |
1731 | |
1732 @subsection Built-in Styles | |
1733 @cindex Built-in Styles | |
1734 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
1735 | |
1736 If you're lucky, one of @ccmode{}'s built-in styles might be just | |
1737 what you're looking for. These include: | |
1738 | |
1739 @itemize @bullet | |
1740 @cindex GNU style | |
1741 @item | |
1742 @code{gnu} --- coding style blessed by the Free Software Foundation | |
1743 for C code in GNU programs. This is the default style for all newly | |
1744 created buffers, but you can change this by setting the variable | |
1745 @code{c-default-style}. | |
1746 | |
1747 @cindex K&R style | |
1748 @item | |
1749 @code{k&r} --- The classic Kernighan and Ritchie style for C code. | |
1750 | |
1751 @cindex BSD style | |
1752 @item | |
1753 @code{bsd} --- Also known as ``Allman style'' after Eric Allman. | |
1754 | |
1755 @cindex Whitesmith style | |
1756 @item | |
1757 @code{whitesmith} --- Popularized by the examples that came with | |
1758 Whitesmiths C, an early commercial C compiler. | |
1759 | |
1760 @cindex Stroustrup style | |
1761 @item | |
1762 @code{stroustrup} --- The classic Stroustrup style for C++ code. | |
1763 | |
1764 @cindex Ellemtel style | |
1765 @item | |
1766 @code{ellemtel} --- Popular C++ coding standards as defined by | |
1767 ``Programming in C++, Rules and Recommendations'', Erik Nyquist and Mats | |
1768 Henricson, Ellemtel @footnote{This document is ftp'able from | |
1769 @code{euagate.eua.ericsson.se}}. | |
1770 | |
1771 @cindex Linux style | |
1772 @item | |
1773 @code{linux} --- C coding standard for Linux development. | |
1774 | |
1775 @cindex Python style | |
1776 @item | |
1777 @code{python} --- C coding standard for Python extension | |
1778 modules@footnote{Python is a high level scripting language with a C/C++ | |
1779 foreign function interface. For more information, see | |
1780 @code{<http://www.python.org/>}.}. | |
1781 | |
1782 @cindex Java style | |
1783 @cindex java-mode | |
1784 @item | |
1785 @code{java} --- The style for editing Java code. Note that this style is | |
1786 automatically installed when you enter @code{java-mode}. | |
1787 | |
1788 @cindex User style | |
1789 @cindex .emacs file | |
1790 @vindex c-default-style | |
1791 @vindex default-style (c-) | |
1792 @item | |
1793 @code{user} --- This is a special style for several reasons. First, if | |
1794 you customize @ccmode{} by using either the new Custom interface or by | |
1795 doing @code{setq}'s at the top level of your @file{.emacs} file, these | |
1796 settings will be captured in the @code{user} style. Also, all other | |
1797 styles implicitly inherit their settings from @code{user} style. This | |
26490
2b08d829af86
Fix complaints from makeinfo 4.0.
Eli Zaretskii <eliz@gnu.org>
parents:
25829
diff
changeset
|
1798 means that for any styles you add via @code{c-add-style} (@pxref{Adding |
25829 | 1799 Styles}) you need only define the differences between your new style and |
1800 @code{user} style. | |
1801 | |
1802 Note however that @code{user} style is @emph{not} the default style. | |
1803 @code{gnu} is the default style for all newly created buffers, but you | |
1804 can change this by setting variable @code{c-default-style}. Be careful | |
1805 if you customize @ccmode{} as described above; since your changes will | |
1806 be captured in the @code{user} style, you will also have to change | |
1807 @code{c-default-style} to "user" to see the effect of your | |
1808 customizations. | |
1809 | |
1810 @end itemize | |
1811 | |
1812 @findex c-set-style | |
1813 @findex set-style (c-) | |
1814 @kindex C-c . | |
1815 If you'd like to experiment with these built-in styles you can simply | |
1816 type the following in a @ccmode{} buffer: | |
1817 @example | |
1818 @group | |
1819 | |
1820 @kbd{C-c . @var{STYLE-NAME} RET} | |
1821 | |
1822 @end group | |
1823 @end example | |
1824 @noindent | |
1825 @kbd{C-c .} runs the command @code{c-set-style}. Note that all style | |
1826 names are case insensitive, even the ones you define. | |
1827 | |
1828 Setting a style in this way does @emph{not} automatically re-indent your | |
1829 file. For commands that you can use to view the effect of your changes, | |
1830 see @ref{Commands}. | |
1831 | |
1832 Once you find a built-in style you like, you can make the change | |
1833 permanent by adding some lisp to your @file{.emacs} file. Let's say for | |
1834 example that you want to use the @samp{ellemtel} style in all your | |
1835 files. You would add this: | |
1836 @example | |
1837 @group | |
1838 | |
1839 (defun my-c-mode-common-hook () | |
1840 ;; use Ellemtel style for all C like languages | |
1841 (c-set-style "ellemtel") | |
1842 ;; other customizations can go here | |
1843 ) | |
1844 (add-hook 'c-mode-common-hook 'my-c-mode-common-hook) | |
1845 | |
1846 @end group | |
1847 @end example | |
1848 | |
1849 @vindex c-indentation-style | |
1850 @vindex indentation-style (c-) | |
1851 Note that for BOCM compatibility, @samp{gnu} is the default | |
1852 style, and any non-style based customizations you make (i.e. in | |
1853 @code{c-mode-common-hook} in your | |
1854 @file{.emacs} file) will be based on @samp{gnu} style unless you do | |
1855 a @code{c-set-style} as the first thing in your hook. The variable | |
1856 @code{c-indentation-style} always contains the buffer's current style name, | |
1857 as a string. | |
1858 | |
1859 | |
1860 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
1861 @node Adding Styles, File Styles, Built-in Styles, Styles | |
1862 @comment node-name, next, previous,up | |
1863 | |
1864 @subsection Adding Styles | |
1865 @cindex Adding Styles | |
1866 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
1867 | |
1868 @vindex c-style-alist | |
1869 @vindex style-alist (c-) | |
1870 @findex c-add-style | |
1871 @findex add-style (c-) | |
1872 If none of the built-in styles is appropriate, you'll probably want to | |
1873 add a new @dfn{style definition}. Styles are kept in the | |
1874 @code{c-style-alist} variable, but you should never modify this variable | |
1875 directly. Instead, @ccmode{} provides the function | |
1876 @code{c-add-style} that you can use to easily add new styles or change | |
1877 existing styles. This function takes two arguments, a @var{stylename} | |
1878 string, and an association list @var{description} of style | |
1879 customizations. If @var{stylename} is not already in | |
1880 @code{c-style-alist}, the new style is added, otherwise the style is | |
1881 changed to the new @var{description}. | |
1882 This function also takes an optional third argument, which if | |
1883 non-@code{nil}, automatically applies the new style to the current | |
1884 buffer. | |
1885 | |
1886 @comment TBD: The next paragraph is bogus. I really need to better | |
1887 @comment document adding styles, including setting up inherited styles. | |
1888 | |
1889 The sample @file{.emacs} file provides a concrete example of how a new | |
1890 style can be added and automatically set. @xref{Sample .emacs File}. | |
1891 | |
1892 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
1893 @node File Styles, , Adding Styles, Styles | |
1894 @comment node-name, next, previous,up | |
1895 | |
1896 @subsection File Styles | |
1897 @cindex File Styles | |
1898 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
1899 | |
1900 @cindex local variables | |
1901 | |
1902 The Emacs manual describes how you can customize certain variables on a | |
1903 per-file basis by including a @dfn{Local Variable} block at the end of | |
1904 the file. So far, you've only seen a functional interface to @ccmode{} | |
1905 customization, which is highly inconvenient for use in a Local Variable | |
1906 block. @ccmode{} provides two variables that make it easier for you to | |
1907 customize your style on a per-file basis. | |
1908 It works via the standard Emacs hook variable | |
1909 @code{hack-local-variables-hook}. | |
1910 | |
1911 @vindex c-file-style | |
1912 @vindex file-style (c-) | |
1913 @vindex c-file-offsets | |
1914 @vindex file-offsets (c-) | |
1915 | |
1916 The variable @code{c-file-style} can be set to a style name string. | |
1917 When the file is visited, @ccmode{} will automatically set the | |
1918 file's style to this style using @code{c-set-style}. | |
1919 | |
1920 @vindex c-offsets-alist | |
1921 @vindex offsets-alist (c-) | |
1922 @findex c-set-offset | |
1923 @findex set-offset (c-) | |
1924 Another variable, @code{c-file-offsets}, takes an association list | |
1925 similar to what is allowed in @code{c-offsets-alist}. When the file is | |
1926 visited, @ccmode{} will automatically institute these offets using | |
1927 @code{c-set-offset}. | |
1928 | |
1929 Note that file style settings (i.e. @code{c-file-style}) are applied | |
1930 before file offset settings (i.e. @code{c-file-offsets}). Also, if | |
1931 either of these are set in a file's local variable section, all the | |
1932 style variable values are made local to that buffer. | |
1933 | |
1934 | |
1935 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
1936 @node Advanced Customizations, , Styles, Customizing Indentation | |
1937 @comment node-name, next, previous,up | |
1938 | |
1939 @section Advanced Customizations | |
1940 @cindex Advanced Customizations | |
1941 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
1942 | |
1943 @vindex c-style-alist | |
1944 @vindex style-alist (c-) | |
1945 @vindex c-basic-offset | |
1946 @vindex basic-offset (c-) | |
1947 For most users, @ccmode{} will support their coding styles with | |
1948 very little need for more advanced customizations. Usually, one of the | |
1949 standard styles defined in @code{c-style-alist} will do the trick. At | |
1950 most, perhaps one of the syntactic symbol offsets will need to be | |
1951 tweaked slightly, or maybe @code{c-basic-offset} will need to be | |
1952 changed. However, some styles require a more flexible framework for | |
1953 customization, and one of the real strengths of @ccmode{} is that | |
1954 the syntactic analysis model provides just such a framework. This allows | |
1955 you to implement custom indentation calculations for situations not | |
1956 handled by the mode directly. | |
1957 | |
1958 @vindex c-style-variables-are-local-p | |
1959 @vindex style-variables-are-local-p | |
1960 Note that the style controlling variables can either have global values, | |
1961 or can be buffer local (e.g. different in every buffer). If all the C | |
1962 files you edit tend to have the same style, you might want to keep the | |
1963 variables global. If you tend to edit files with many different styles, | |
1964 you will have to make the variables buffer local. The variable | |
1965 @code{c-style-variables-are-local-p} controls this. | |
1966 | |
1967 When @code{c-style-variables-are-local-p} is non-nil, then the style | |
1968 variables will have a different settable value for each buffer, | |
1969 otherwise all buffers will share the same values. By default, its value | |
1970 is @code{nil} (i.e. global values). You @strong{must} set this variable | |
1971 before @ccmode{} is loaded into your Emacs session, and once the | |
1972 variables are made buffer local, they cannot be made global again | |
1973 (unless you restart Emacs of course!) | |
1974 | |
1975 @menu | |
1976 * Custom Indentation Functions:: | |
1977 * Custom Brace and Colon Hanging:: | |
1978 * Customizing Semi-colons and Commas:: | |
1979 * Other Special Indentations:: | |
1980 @end menu | |
1981 | |
1982 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
1983 @node Custom Indentation Functions, Custom Brace and Colon Hanging, , Advanced Customizations | |
1984 @comment node-name, next, previous,up | |
1985 | |
1986 @subsection Custom Indentation Functions | |
1987 @cindex Custom Indentation Functions | |
1988 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
1989 | |
1990 @cindex Custom Indentation Functions | |
1991 The most flexible way to customize @ccmode{} is by writing @dfn{custom | |
1992 indentation functions} and associating them with specific syntactic | |
1993 symbols (see @ref{Syntactic Symbols}). @ccmode{} itself uses custom | |
1994 indentation functions to provide more sophisticated indentation, for | |
1995 example when lining up C++ stream operator blocks: | |
1996 @example | |
1997 @group | |
1998 | |
1999 1: void main(int argc, char**) | |
2000 2: @{ | |
2001 3: cout << "There were " | |
2002 4: << argc | |
2003 5: << "arguments passed to the program" | |
2004 6: << endl; | |
2005 7: @} | |
2006 | |
2007 @end group | |
2008 @end example | |
2009 | |
2010 In this example, lines 4 through 6 are assigned the @code{stream-op} | |
2011 syntactic symbol. Here, @code{stream-op} has an offset of @code{+}, and | |
2012 with a @code{c-basic-offset} of 2, you can see that lines 4 through 6 | |
2013 are simply indented two spaces to the right of line 3. But perhaps we'd | |
2014 like @ccmode{} to be a little more intelligent so that it aligns | |
2015 all the @samp{<<} symbols in lines 3 through 6. To do this, we have | |
2016 to write a custom indentation function which finds the column of first | |
2017 stream operator on the first line of the statement. Here is sample | |
2018 lisp code implementing this: | |
2019 @example | |
2020 @group | |
2021 | |
2022 (defun c-lineup-streamop (langelem) | |
2023 ;; lineup stream operators | |
2024 (save-excursion | |
2025 (let* ((relpos (cdr langelem)) | |
2026 (curcol (progn (goto-char relpos) | |
2027 (current-column)))) | |
2028 (re-search-forward "<<\\|>>" (c-point 'eol) 'move) | |
2029 (goto-char (match-beginning 0)) | |
2030 (- (current-column) curcol)))) | |
2031 | |
2032 @end group | |
2033 @end example | |
2034 @noindent | |
2035 Custom indent functions take a single argument, which is a syntactic | |
2036 component cons cell (see @ref{Syntactic Analysis}). The | |
2037 function returns an integer offset value that will be added to the | |
2038 running total indentation for the line. Note that what actually gets | |
2039 returned is the difference between the column that the first stream | |
2040 operator is on, and the column of the buffer relative position passed in | |
2041 the function's argument. Remember that @ccmode{} automatically | |
2042 adds in the column of the component's relative buffer position and we | |
2043 don't the column offset added in twice. | |
2044 | |
2045 @cindex stream-op syntactic symbol | |
2046 @findex c-lineup-streamop | |
2047 @findex lineup-streamop (c-) | |
2048 Now, to associate the function @code{c-lineup-streamop} with the | |
2049 @code{stream-op} syntactic symbol, we can add something like the | |
2050 following to our @code{c++-mode-hook}@footnote{It probably makes more | |
2051 sense to add this to @code{c++-mode-hook} than @code{c-mode-common-hook} | |
2052 since stream operators are only relevent for C++.}: | |
2053 @example | |
2054 | |
2055 (c-set-offset 'stream-op 'c-lineup-streamop) | |
2056 | |
2057 @end example | |
2058 | |
2059 @kindex C-c C-q | |
2060 Now the function looks like this after re-indenting (using @kbd{C-c | |
2061 C-q}): | |
2062 @example | |
2063 @group | |
2064 | |
2065 1: void main(int argc, char**) | |
2066 2: @{ | |
2067 3: cout << "There were " | |
2068 4: << argc | |
2069 5: << "arguments passed to the program" | |
2070 6: << endl; | |
2071 7: @} | |
2072 | |
2073 @end group | |
2074 @end example | |
2075 | |
2076 @vindex c-offsets-alist | |
2077 @vindex offsets-alist (c-) | |
2078 Custom indentation functions can be as simple or as complex as you like, | |
2079 and any syntactic symbol that appears in @code{c-offsets-alist} can have | |
2080 a custom indentation function associated with it. @ccmode{} comes | |
2081 with several standard custom indentation functions, not all of which are | |
2082 used by the default styles. | |
2083 | |
2084 @itemize @bullet | |
2085 @findex c-lineup-arglist | |
2086 @findex lineup-arglist (c-) | |
2087 @item | |
2088 @code{c-lineup-arglist} --- lines up function argument lines under the | |
2089 argument on the previous line. | |
2090 | |
2091 @findex c-lineup-arglist-intro-after-paren | |
2092 @findex lineup-arglist-intro-after-paren (c-) | |
2093 @item | |
2094 @code{c-lineup-arglist-intro-after-paren} --- similar to | |
2095 @code{c-lineup-arglist}, but works for argument lists that begin with an | |
2096 open parenthesis followed by a newline. | |
2097 | |
2098 @findex c-lineup-arglist-close-under-paren | |
2099 @findex lineup-arglist-close-under-paren (c-) | |
2100 @item | |
2101 @code{c-lineup-arglist-close-under-paren} --- set your | |
2102 @code{arglist-close} syntactic symbol to this line-up function so that | |
2103 parentheses that close argument lists will line up under the parenthesis | |
2104 that opened the argument list. | |
2105 | |
2106 @findex c-lineup-close-paren | |
2107 @findex lineup-close-paren (c-) | |
2108 @item | |
2109 @code{c-lineup-close-paren} --- lines up the closing parenthesis under | |
2110 its corresponding open parenthesis if that one is followed by code. | |
2111 Otherwise, if the open parenthesis ends its line, no indentation is | |
2112 added. Works with any @code{@dots{}-close} symbol. | |
2113 | |
2114 @findex c-lineup-streamop | |
2115 @findex lineup-streamop (c-) | |
2116 @item | |
2117 @code{c-lineup-streamop} --- lines up C++ stream operators | |
2118 (e.g. @samp{<<} and @samp{>>}). | |
2119 | |
2120 @findex c-lineup-multi-inher | |
2121 @findex lineup-multi-inher (c-) | |
2122 @item | |
2123 @code{c-lineup-multi-inher} --- lines up multiple inheritance lines. | |
2124 | |
2125 @findex c-indent-one-line-block | |
2126 @findex indent-one-line-block (c-) | |
2127 @item | |
2128 @code{c-indent-one-line-block} --- adds @code{c-basic-offset} to the | |
2129 indentation if the line is a one line block, otherwise 0. Intended to | |
2130 be used with any opening brace symbol, e.g. @code{substatement-open}. | |
2131 | |
2132 @findex c-lineup-C-comments | |
2133 @findex lineup-C-comments (c-) | |
2134 @item | |
2135 @code{c-lineup-C-comments} --- lines up C block comment continuation | |
2136 lines. | |
2137 | |
2138 @findex c-lineup-comment | |
2139 @findex lineup-comment (c-) | |
2140 @vindex c-comment-only-line-offset | |
2141 @vindex comment-only-line-offset (c-) | |
2142 @item | |
2143 @code{c-lineup-comment} --- lines up comment only lines according to | |
2144 the variable @code{c-comment-only-line-offset}. | |
2145 | |
2146 @findex c-lineup-runin-statements | |
2147 @findex lineup-runin-statements (c-) | |
2148 @item | |
2149 @code{c-lineup-runin-statements} --- lines up @code{statement}s for coding | |
2150 standards which place the first statement in a block on the same line as | |
2151 the block opening brace@footnote{Run-in style doesn't really work too | |
2152 well. You might need to write your own custom indentation functions to | |
2153 better support this style.}. | |
2154 | |
2155 @findex c-lineup-math | |
2156 @findex lineup-math (c-) | |
2157 @item | |
2158 @code{c-lineup-math} --- lines up math @code{statement-cont} lines under | |
2159 the previous line after the equals sign. | |
2160 | |
2161 @findex c-lineup-ObjC-method-call | |
2162 @findex lineup-ObjC-method-call (c-) | |
2163 @item | |
2164 @code{c-lineup-ObjC-method-call} --- for Objective-C code, lines up | |
2165 selector arguments just after the message receiver. | |
2166 | |
2167 @findex c-lineup-ObjC-method-args | |
2168 @findex lineup-ObjC-method-args (c-) | |
2169 @item | |
2170 @code{c-lineup-ObjC-method-args} --- for Objective-C code, lines up the | |
2171 colons that separate arguments by aligning colons vertically. | |
2172 | |
2173 @findex c-lineup-ObjC-method-args-2 | |
2174 @findex lineup-ObjC-method-args-2 (c-) | |
2175 @item | |
2176 @code{c-lineup-ObjC-method-args-2} --- similar to | |
2177 @code{c-lineup-ObjC-method-args} but lines up the colon on the current | |
2178 line with the colon on the previous line. | |
2179 | |
2180 @findex c-lineup-dont-change | |
2181 @findex lineup-dont-change (c-) | |
2182 @item | |
2183 @code{c-lineup-dont-change} --- this lineup function returns the | |
2184 indentation of the current line. Think of it as an identity function | |
2185 for lineups; it is used for @code{cpp-macro-cont} lines. | |
2186 | |
2187 @end itemize | |
2188 | |
2189 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
2190 @node Custom Brace and Colon Hanging, Customizing Semi-colons and Commas, Custom Indentation Functions, Advanced Customizations | |
2191 @comment node-name, next, previous,up | |
2192 | |
2193 @subsection Custom Brace and Colon Hanging | |
2194 @cindex Custom Brace and Colon Hanging | |
2195 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
2196 | |
2197 @vindex c-hanging-braces-alist | |
2198 @vindex hanging-braces-alist (c-) | |
2199 Syntactic symbols aren't the only place where you can customize | |
2200 @ccmode{} with the lisp equivalent of callback functions. Brace | |
2201 ``hanginess'' can also be determined by custom functions associated with | |
2202 syntactic symbols on the @code{c-hanging-braces-alist} variable. | |
2203 Remember that @var{ACTION}'s are typically a list containing some | |
2204 combination of the symbols @code{before} and @code{after} (see | |
2205 @ref{Hanging Braces}). However, an @var{ACTION} can also be a function | |
2206 which gets called when a brace matching that syntactic symbol is | |
2207 entered. | |
2208 | |
2209 @cindex customizing brace hanging | |
2210 These @var{ACTION} functions are called with two arguments: the | |
2211 syntactic symbol for the brace, and the buffer position at which the | |
2212 brace was inserted. The @var{ACTION} function is expected to return a | |
2213 list containing some combination of @code{before} and @code{after}. The | |
2214 function can also return @code{nil}. This return value has the normal | |
2215 brace hanging semantics. | |
2216 | |
2217 As an example, @ccmode{} itself uses this feature to dynamically | |
2218 determine the hanginess of braces which close ``do-while'' | |
2219 constructs: | |
2220 @example | |
2221 @group | |
2222 | |
2223 void do_list( int count, char** atleast_one_string ) | |
2224 @{ | |
2225 int i=0; | |
2226 do @{ | |
2227 handle_string( atleast_one_string[i] ); | |
2228 i++; | |
2229 @} while( i < count ); | |
2230 @} | |
2231 | |
2232 @end group | |
2233 @end example | |
2234 | |
2235 @findex c-snug-do-while | |
2236 @findex snug-do-while (c-) | |
2237 @ccmode{} assigns the @code{block-close} syntactic symbol to the | |
2238 brace that closes the @code{do} construct, and normally we'd like the | |
2239 line that follows a @code{block-close} brace to begin on a separate | |
2240 line. However, with ``do-while'' constructs, we want the | |
2241 @code{while} clause to follow the closing brace. To do this, we | |
2242 associate the @code{block-close} symbol with the @var{ACTION} function | |
2243 @code{c-snug-do-while}: | |
2244 @example | |
2245 | |
2246 (defun c-snug-do-while (syntax pos) | |
2247 "Dynamically calculate brace hanginess for do-while statements. | |
2248 Using this function, `while' clauses that end a `do-while' block will | |
2249 remain on the same line as the brace that closes that block. | |
2250 | |
2251 See `c-hanging-braces-alist' for how to utilize this function as an | |
2252 ACTION associated with `block-close' syntax." | |
2253 (save-excursion | |
2254 (let (langelem) | |
2255 (if (and (eq syntax 'block-close) | |
2256 (setq langelem (assq 'block-close c-syntactic-context)) | |
2257 (progn (goto-char (cdr langelem)) | |
2258 (if (= (following-char) ?@{) | |
2259 (forward-sexp -1)) | |
2260 (looking-at "\\<do\\>[^_]"))) | |
2261 '(before) | |
2262 '(before after))))) | |
2263 | |
2264 @end example | |
2265 | |
2266 This function simply looks to see if the brace closes a ``do-while'' | |
2267 clause and if so, returns the list @samp{(before)} indicating | |
2268 that a newline should be inserted before the brace, but not after it. | |
2269 In all other cases, it returns the list @samp{(before after)} so | |
2270 that the brace appears on a line by itself. | |
2271 | |
2272 @vindex c-syntactic-context | |
2273 @vindex syntactic-context (c-) | |
2274 During the call to the brace hanging @var{ACTION} function, the variable | |
2275 @code{c-syntactic-context} is bound to the full syntactic analysis list. | |
2276 | |
2277 @cindex customizing colon hanging | |
2278 @vindex c-hanging-colon-alist | |
2279 @vindex hanging-colon-alist (c-) | |
2280 Note that for symmetry, colon hanginess should be customizable by | |
2281 allowing function symbols as @var{ACTION}s on the | |
2282 @code{c-hanging-colon-alist} variable. Since no use has actually been | |
2283 found for this feature, it isn't currently implemented! | |
2284 | |
2285 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
2286 @node Customizing Semi-colons and Commas, Other Special Indentations, Custom Brace and Colon Hanging, Advanced Customizations | |
2287 @comment node-name, next, previous,up | |
2288 | |
2289 @subsection Customizing Semi-colons and Commas | |
2290 @cindex Customizing Semi-colons and Commas | |
2291 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
2292 | |
2293 @cindex Customizing Semi-colons and Commas | |
2294 @vindex c-hanging-semi&comma-criteria | |
2295 @vindex hanging-semi&comma-criteria (c-) | |
2296 You can also customize the insertion of newlines after semi-colons and | |
2297 commas, when the auto-newline minor mode is enabled (see @ref{Minor | |
2298 Modes}). This is controlled by the variable | |
2299 @code{c-hanging-semi&comma-criteria}, which contains a list of functions | |
2300 that are called in the order they appear. Each function is called with | |
2301 zero arguments, and is expected to return one of the following values: | |
2302 | |
2303 @itemize @bullet | |
2304 @item | |
2305 non-@code{nil} --- A newline is inserted, and no more functions from the | |
2306 list are called. | |
2307 | |
2308 @item | |
2309 @code{stop} --- No more functions from the list are called, but no | |
2310 newline is inserted. | |
2311 | |
2312 @item | |
2313 @code{nil} --- No determination is made, and the next function in the | |
2314 list is called. | |
2315 | |
2316 @end itemize | |
2317 | |
2318 If every function in the list is called without a determination being | |
2319 made, then no newline is added. The default value for this variable is a | |
2320 list containing a single function which inserts newlines only after | |
2321 semi-colons which do not appear inside parenthesis lists (i.e. those | |
2322 that separate @code{for}-clause statements). | |
2323 | |
2324 @findex c-semi&comma-no-newlines-before-nonblanks | |
2325 @findex semi&comma-no-newlines-before-nonblanks (c-) | |
2326 Here's an example of a criteria function, provided by @ccmode{}, that | |
2327 will prevent newlines from being inserted after semicolons when there is | |
2328 a non-blank following line. Otherwise, it makes no determination. To | |
2329 use, add this to the front of the @code{c-hanging-semi&comma-criteria} | |
2330 list. | |
2331 | |
2332 @example | |
2333 @group | |
2334 | |
2335 (defun c-semi&comma-no-newlines-before-nonblanks () | |
2336 (save-excursion | |
2337 (if (and (eq last-command-char ?\;) | |
2338 (zerop (forward-line 1)) | |
2339 (not (looking-at "^[ \t]*$"))) | |
2340 'stop | |
2341 nil))) | |
2342 | |
2343 @end group | |
2344 @end example | |
2345 | |
2346 @findex c-semi&comma-inside-parenlist | |
2347 @findex c-semi&comma-no-newlines-for-oneline-inliners | |
2348 @findex semi&comma-inside-parenlist (c-) | |
2349 @findex semi&comma-no-newlines-for-oneline-inliners (c-) | |
2350 The default value of @code{c-hanging-semi&comma-criteria} is a list | |
2351 containing just the function @code{c-semi&comma-inside-parenlist}, which | |
2352 suppresses newlines after semicolons inside parenthesis lists | |
2353 (e.g. @code{for}-loops). In addition to | |
2354 @code{c-semi&comma-no-newlines-before-nonblanks} described above, | |
2355 @ccmode{} also comes with the criteria function | |
2356 @code{c-semi&comma-no-newlines-for-oneline-inliners}, which suppresses | |
2357 newlines after semicolons inside one-line inline method definitions | |
2358 (i.e. in C++ or Java). | |
2359 | |
2360 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
2361 @node Other Special Indentations, , Customizing Semi-colons and Commas, Advanced Customizations | |
2362 @comment node-name, next, previous,up | |
2363 | |
2364 @subsection Other Special Indentations | |
2365 @cindex Customizing Semi-colons and Commas | |
2366 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
2367 | |
2368 @vindex c-label-minimum-indentation | |
2369 @vindex label-minimum-indentation (c-) | |
2370 In @samp{gnu} style (see @ref{Built-in Styles}), a minimum indentation | |
2371 is imposed on lines inside top-level constructs. This minimum | |
2372 indentation is controlled by the variable | |
2373 @code{c-label-minimum-indentation}. The default value for this variable | |
2374 is 1. | |
2375 | |
2376 @vindex c-special-indent-hook | |
2377 @vindex special-indent-hook (c-) | |
2378 One other customization variable is available in @ccmode{}: | |
2379 @code{c-special-indent-hook}. This is a standard hook variable that is | |
2380 called after every line is indented by @ccmode{}. You can use it | |
2381 to do any special indentation or line adjustments your style dictates, | |
2382 such as adding extra indentation to constructors or destructor | |
2383 declarations in a class definition, etc. Note however, that you should | |
2384 not change point or mark inside your @code{c-special-indent-hook} | |
2385 functions (i.e. you'll probably want to wrap your function in a | |
2386 @code{save-excursion}). | |
2387 | |
2388 Setting @code{c-special-indent-hook} in your style definition is handled | |
2389 slightly differently than other variables. In your style definition, | |
2390 you should set the value for | |
2391 @code{c-special-indent-hook} to a function or list of functions, which | |
2392 will be appended to @code{c-special-indent-hook} using @code{add-hook}. | |
2393 That way, the current setting for the buffer local value of | |
2394 @code{c-special-indent-hook} won't be overridden. | |
2395 | |
2396 @kindex M-; | |
2397 @findex indent-for-comment | |
2398 @vindex c-indent-comments-syntactically-p | |
2399 @vindex indent-comments-syntactically-p (c-) | |
2400 @vindex comment-column | |
2401 | |
2402 Normally, the standard Emacs command @kbd{M-;} | |
2403 (@code{indent-for-comment}) will indent comment only lines to | |
2404 @code{comment-column}. Some users however, prefer that @kbd{M-;} act | |
2405 just like @kbd{TAB} for purposes of indenting comment-only lines; | |
2406 i.e. they want the comments to always indent as they would for normal | |
2407 code, regardless of whether @kbd{TAB} or @kbd{M-;} were used. This | |
2408 behavior is controlled by the variable | |
2409 @code{c-indent-comments-syntactically-p}. When @code{nil} (the | |
2410 default), @kbd{M-;} indents comment-only lines to @code{comment-column}, | |
2411 otherwise, they are indented just as they would be if @kbd{TAB} were | |
2412 typed. | |
2413 | |
2414 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
2415 @node Syntactic Symbols, Performance Issues, Customizing Indentation, Top | |
2416 @comment node-name, next, previous,up | |
2417 | |
2418 @chapter Syntactic Symbols | |
2419 @cindex Syntactic Symbols | |
2420 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
2421 | |
2422 @vindex c-offsets-alist | |
2423 @vindex offsets-alist (c-) | |
2424 | |
2425 Here is a complete list of the recognized syntactic symbols as described | |
2426 in the @code{c-offsets-alist} variable, along with a brief description. | |
2427 More detailed descriptions follow below. | |
2428 | |
2429 @itemize @bullet | |
2430 @item | |
2431 @code{string} --- inside multi-line string | |
2432 @item | |
2433 @code{c} --- inside a multi-line C style block comment | |
2434 @item | |
2435 @code{defun-open} --- brace that opens a function definition | |
2436 @item | |
2437 @code{defun-close} --- brace that closes a function definition | |
2438 @item | |
2439 @code{defun-block-intro} --- the first line in a top-level defun | |
2440 @item | |
2441 @code{class-open} --- brace that opens a class definition | |
2442 @item | |
2443 @code{class-close} --- brace that closes a class definition | |
2444 @item | |
2445 @code{inline-open} --- brace that opens an in-class inline method | |
2446 @item | |
2447 @code{inline-close} --- brace that closes an in-class inline method | |
2448 @item | |
2449 @code{func-decl-cont} --- the region between a function definition's | |
2450 argument list and the function opening brace (excluding K&R argument | |
2451 declarations). In C, you cannot put anything but whitespace and comments | |
2452 between them; in C++ and Java, @code{throws} declarations and other | |
2453 things can appear in this context. | |
2454 @item | |
2455 @code{knr-argdecl-intro} --- first line of a K&R C argument declaration | |
2456 @item | |
2457 @code{knr-argdecl} --- subsequent lines in a K&R C argument declaration | |
2458 @item | |
2459 @code{topmost-intro} --- the first line in a topmost definition | |
2460 @item | |
2461 @code{topmost-intro-cont} --- topmost definition continuation lines | |
2462 @item | |
2463 @code{member-init-intro} --- first line in a member initialization list | |
2464 @item | |
2465 @code{member-init-cont} --- subsequent member initialization list lines | |
2466 @item | |
2467 @code{inher-intro} --- first line of a multiple inheritance list | |
2468 @item | |
2469 @code{inher-cont} --- subsequent multiple inheritance lines | |
2470 @item | |
2471 @code{block-open} --- statement block open brace | |
2472 @item | |
2473 @code{block-close} --- statement block close brace | |
2474 @item | |
2475 @code{brace-list-open} --- open brace of an enum or static array list | |
2476 @item | |
2477 @code{brace-list-close} --- close brace of an enum or static array list | |
2478 @item | |
2479 @code{brace-list-intro} --- first line in an enum or static array list | |
2480 @item | |
2481 @code{brace-list-entry} --- subsequent lines in an enum or static array list | |
2482 @item | |
2483 @code{statement} --- a C statement | |
2484 @item | |
2485 @code{statement-cont} --- a continuation of a C statement | |
2486 @item | |
2487 @code{statement-block-intro} --- the first line in a new statement block | |
2488 @item | |
2489 @code{statement-case-intro} --- the first line in a case `block' | |
2490 @item | |
2491 @code{statement-case-open} --- the first line in a case block starting | |
2492 with brace | |
2493 @item | |
2494 @code{substatement} --- the first line after a conditional | |
2495 @item | |
2496 @code{substatement-open} --- the brace that opens a substatement block | |
2497 @item | |
2498 @code{case-label} --- a case or default label | |
2499 @item | |
2500 @code{access-label} --- C++ access control label | |
2501 @item | |
2502 @code{label} --- any non-special C label | |
2503 @item | |
2504 @code{do-while-closure} --- the `while' that ends a | |
2505 @code{do}-@code{while} construct | |
2506 @item | |
2507 @code{else-clause} --- the `else' of an @code{if}-@code{else} construct | |
2508 @item | |
2509 @code{comment-intro} --- a line containing only a comment introduction | |
2510 @item | |
2511 @code{arglist-intro} --- the first line in an argument list | |
2512 @item | |
2513 @code{arglist-cont} --- subsequent argument list lines when no arguments | |
2514 follow on the same line as the the arglist opening paren | |
2515 @item | |
2516 @code{arglist-cont-nonempty} --- subsequent argument list lines when at | |
2517 least one argument follows on the same line as the arglist opening paren | |
2518 @item | |
2519 @code{arglist-close} --- the solo close paren of an argument list | |
2520 @item | |
2521 @code{stream-op} --- lines continuing a stream operator | |
2522 @item | |
2523 @code{inclass} --- the line is nested inside a class definition | |
2524 @item | |
2525 @code{cpp-macro} --- the start of a C preprocessor macro definition | |
2526 @item | |
2527 @code{cpp-macro-cont} --- subsequent lines of a multi-line C | |
2528 preprocessor macro definition | |
2529 @item | |
2530 @code{friend} --- a C++ friend declaration | |
2531 @item | |
2532 @code{objc-method-intro} --- the first line of an Objective-C method definition | |
2533 @item | |
2534 @code{objc-method-args-cont} --- lines continuing an Objective-C method | |
2535 definition | |
2536 @item | |
2537 @code{objc-method-call-cont} --- lines continuing an Objective-C method call | |
2538 @item | |
2539 @code{extern-lang-open} --- brace that opens an external language block | |
2540 @item | |
2541 @code{extern-lang-close} --- brace that closes an external language block | |
2542 @item | |
2543 @code{inextern-lang} --- analogous to `inclass' syntactic symbol, but | |
2544 used inside external language blocks (e.g. @code{extern "C" @{}). | |
2545 @item | |
2546 @code{namespace-open} --- brace that opens a C++ namespace block. | |
2547 @item | |
2548 @code{namespace-close} --- brace that closes a C++ namespace block. | |
2549 @item | |
2550 @code{innamespace} --- analogous to `inextern-lang' syntactic symbol, | |
2551 but used inside C++ namespace blocks. | |
2552 @item | |
2553 @code{template-args-cont} --- C++ template argument list continuations | |
2554 @end itemize | |
2555 | |
2556 @cindex -open syntactic symbols | |
2557 @cindex -close syntactic symbols | |
2558 Most syntactic symbol names follow a general naming convention. When a | |
2559 line begins with an open or close brace, the syntactic symbol will | |
2560 contain the suffix @code{-open} or @code{-close} respectively. | |
2561 | |
2562 @cindex -intro syntactic symbols | |
2563 @cindex -cont syntactic symbols | |
2564 @cindex -block-intro syntactic symbols | |
2565 Usually, a distinction is made between the first line that introduces a | |
2566 construct and lines that continue a construct, and the syntactic symbols | |
2567 that represent these lines will contain the suffix @code{-intro} or | |
2568 @code{-cont} respectively. As a sub-classification of this scheme, a | |
2569 line which is the first of a particular brace block construct will | |
2570 contain the suffix @code{-block-intro}. | |
2571 | |
2572 @kindex C-c C-s | |
2573 Let's look at some examples to understand how this works. Remember that | |
2574 you can check the syntax of any line by using @kbd{C-c C-s}. | |
2575 @example | |
2576 @group | |
2577 | |
2578 1: void | |
2579 2: swap( int& a, int& b ) | |
2580 3: @{ | |
2581 4: int tmp = a; | |
2582 5: a = b; | |
2583 6: b = tmp; | |
2584 7: int ignored = | |
2585 8: a + b; | |
2586 9: @} | |
2587 | |
2588 @end group | |
2589 @end example | |
2590 | |
2591 @cindex topmost-intro syntactic symbol | |
2592 @cindex topmost-intro-cont syntactic symbol | |
2593 @cindex defun-open syntactic symbol | |
2594 @cindex defun-close syntactic symbol | |
2595 @cindex defun-block-intro syntactic symbol | |
2596 Line 1 shows a @code{topmost-intro} since it is the first line that | |
2597 introduces a top-level construct. Line 2 is a continuation of the | |
2598 top-level construct introduction so it has the syntax | |
2599 @code{topmost-intro-cont}. Line 3 shows a @code{defun-open} since it is | |
2600 the brace that opens a top-level function definition. Line 9 is a | |
2601 @code{defun-close} since it contains the brace that closes the top-level | |
2602 function definition. Line 4 is a @code{defun-block-intro}, i.e. it is | |
2603 the first line of a brace-block, enclosed in a | |
2604 top-level function definition. | |
2605 | |
2606 @cindex statement syntactic symbol | |
2607 @cindex statement-cont syntactic symbol | |
2608 Lines 5, 6, and 7 are all given @code{statement} syntax since there | |
2609 isn't much special about them. Note however that line 8 is given | |
2610 @code{statement-cont} syntax since it continues the statement begun | |
2611 on the previous line. | |
2612 | |
2613 Here's another example, which illustrates some C++ class syntactic | |
2614 symbols: | |
2615 @example | |
2616 @group | |
2617 | |
2618 1: class Bass | |
2619 2: : public Guitar, | |
2620 3: public Amplifiable | |
2621 4: @{ | |
2622 5: public: | |
2623 6: Bass() | |
2624 7: : eString( new BassString( 0.105 )), | |
2625 8: aString( new BassString( 0.085 )), | |
2626 9: dString( new BassString( 0.065 )), | |
2627 10: gString( new BassString( 0.045 )) | |
2628 11: @{ | |
2629 12: eString.tune( 'E' ); | |
2630 13: aString.tune( 'A' ); | |
2631 14: dString.tune( 'D' ); | |
2632 15: gString.tune( 'G' ); | |
2633 16: @} | |
2634 17: friend class Luthier; | |
2635 18: @} | |
2636 | |
2637 @end group | |
2638 @end example | |
2639 | |
2640 @cindex class-open syntactic symbol | |
2641 @cindex class-close syntactic symbol | |
2642 As in the previous example, line 1 has the @code{topmost-intro} syntax. | |
2643 Here however, the brace that opens a C++ class definition on line 4 is | |
2644 assigned the @code{class-open} syntax. Note that in C++, classes, | |
2645 structs, and unions are essentially equivalent syntactically (and are | |
2646 very similar semantically), so replacing the @code{class} keyword in the | |
2647 example above with @code{struct} or @code{union} would still result in a | |
2648 syntax of @code{class-open} for line 4 @footnote{This is the case even | |
2649 for C and Objective-C. For consistency, structs in all supported | |
2650 languages are syntactically equivalent to classes. Note however that | |
2651 the keyword @code{class} is meaningless in C and Objective-C.}. | |
2652 Similarly, line 18 is assigned @code{class-close} syntax. | |
2653 | |
2654 @cindex inher-intro syntactic symbol | |
2655 @cindex inher-cont syntactic symbol | |
2656 Line 2 introduces the inheritance list for the class so it is assigned | |
2657 the @code{inher-intro} syntax, and line 3, which continues the | |
2658 inheritance list is given @code{inher-cont} syntax. | |
2659 | |
2660 @cindex access-label syntactic symbol | |
2661 @cindex inclass syntactic symbol | |
2662 Hitting @kbd{C-c C-s} on line 5 shows the following analysis: | |
2663 | |
2664 @example | |
2665 @group | |
2666 | |
2667 @code{((inclass . 1) (access-label . 67))} | |
2668 | |
2669 @end group | |
2670 @end example | |
2671 | |
2672 @noindent | |
2673 The primary syntactic symbol for this line is @code{access-label} as | |
2674 this a label keyword that specifies access protection in C++. However, | |
2675 because this line is also a top-level construct inside a class | |
2676 definition, the analysis actually shows two syntactic symbols. The | |
2677 other syntactic symbol assigned to this line is @code{inclass}. | |
2678 Similarly, line 6 is given both @code{inclass} and @code{topmost-intro} | |
2679 syntax: | |
2680 | |
2681 @example | |
2682 @group | |
2683 | |
2684 @code{((inclass . 58) (topmost-intro . 60))} | |
2685 | |
2686 @end group | |
2687 @end example | |
2688 | |
2689 @cindex member-init-intro syntactic symbol | |
2690 @cindex member-init-cont syntactic symbol | |
2691 Line 7 introduces a C++ member initialization list and as such is given | |
2692 @code{member-init-intro} syntax. Note that in this case it is | |
2693 @emph{not} assigned @code{inclass} since this is not considered a | |
2694 top-level construct. Lines 8 through 10 are all assigned | |
2695 @code{member-init-cont} since they continue the member initialization | |
2696 list started on line 7. | |
2697 | |
2698 @cindex in-class inline methods | |
2699 @cindex inline-open syntactic symbol | |
2700 @cindex inline-close syntactic symbol | |
2701 Line 11's analysis is a bit more complicated: | |
2702 | |
2703 @example | |
2704 @group | |
2705 | |
2706 @code{((inclass . 1) (inline-open))} | |
2707 | |
2708 @end group | |
2709 @end example | |
2710 | |
2711 This line is assigned a syntax of both @code{inline-open} and | |
2712 @code{inclass} because it opens an @dfn{in-class} C++ inline method | |
2713 definition. This is distinct from, but related to, the C++ notion of an | |
2714 inline function in that its definition occurs inside an enclosing class | |
2715 definition, which in C++ implies that the function should be inlined. | |
2716 If though, the definition of the @code{Bass} constructor appeared | |
2717 outside the class definition, the construct would be given the | |
2718 @code{defun-open} syntax, even if the keyword @code{inline} appeared | |
2719 before the method name, as in: | |
2720 @example | |
2721 @group | |
2722 | |
2723 class Bass | |
2724 : public Guitar, | |
2725 public Amplifiable | |
2726 @{ | |
2727 public: | |
2728 Bass(); | |
2729 @} | |
2730 | |
2731 inline | |
2732 Bass::Bass() | |
2733 : eString( new BassString( 0.105 )), | |
2734 aString( new BassString( 0.085 )), | |
2735 dString( new BassString( 0.065 )), | |
2736 gString( new BassString( 0.045 )) | |
2737 @{ | |
2738 eString.tune( 'E' ); | |
2739 aString.tune( 'A' ); | |
2740 dString.tune( 'D' ); | |
2741 gString.tune( 'G' ); | |
2742 @} | |
2743 | |
2744 @end group | |
2745 @end example | |
2746 | |
2747 @cindex friend syntactic symbol | |
2748 Returning to the previous example, line 16 is given @code{inline-close} | |
2749 syntax, while line 12 is given @code{defun-block-open} syntax, and lines | |
2750 13 through 15 are all given @code{statement} syntax. Line 17 is | |
2751 interesting in that its syntactic analysis list contains three | |
2752 elements: | |
2753 | |
2754 @example | |
2755 | |
2756 @code{((friend) (inclass . 58) (topmost-intro . 380))} | |
2757 | |
2758 @end example | |
2759 | |
2760 The @code{friend} syntactic symbol is a modifier that typically does not | |
2761 have a relative buffer position. | |
2762 | |
2763 Template definitions introduce yet another syntactic symbol: | |
2764 | |
2765 @example | |
2766 @group | |
2767 | |
2768 1: ThingManager <int, | |
2769 2: Framework::Callback *, | |
2770 3: Mutex> framework_callbacks; | |
2771 | |
2772 @end group | |
2773 @end example | |
2774 | |
2775 Here, line 1 is analyzed as a @code{topmost-intro}, but lines 2 and 3 | |
2776 are both analyzed as @code{template-args-cont} lines. | |
2777 | |
2778 Here is another (totally contrived) example which illustrates how syntax | |
2779 is assigned to various conditional constructs: | |
2780 @example | |
2781 @group | |
2782 | |
2783 1: void spam( int index ) | |
2784 2: @{ | |
2785 3: for( int i=0; i<index; i++ ) | |
2786 4: @{ | |
2787 5: if( i == 10 ) | |
2788 6: @{ | |
2789 7: do_something_special(); | |
2790 8: @} | |
2791 9: else | |
2792 10: do_something( i ); | |
2793 11: @} | |
2794 12: do @{ | |
2795 13: another_thing( i-- ); | |
2796 14: @} | |
2797 15: while( i > 0 ); | |
2798 16: @} | |
2799 | |
2800 | |
2801 @end group | |
2802 @end example | |
2803 | |
2804 @noindent | |
2805 Only the lines that illustrate new syntactic symbols will be discussed. | |
2806 | |
2807 @cindex substatement-open syntactic symbol | |
2808 @cindex substatement-block-intro syntactic symbol | |
2809 @cindex block-close syntactic symbol | |
2810 Line 4 has a brace which opens a conditional's substatement block. It | |
2811 is thus assigned @code{substatement-open} syntax, and since line 5 is | |
2812 the first line in the substatement block, it is assigned | |
2813 @code{substatement-block-intro} syntax. Lines 6 and 7 are assigned | |
2814 similar syntax. Line 8 contains the brace that closes the inner | |
2815 substatement block. It is given the syntax @code{block-close}, | |
2816 as are lines 11 and 14. | |
2817 | |
2818 @cindex else-clause syntactic symbol | |
2819 @cindex substatement syntactic symbol | |
2820 Line 9 is a little different --- since it contains the keyword | |
2821 @code{else} matching the @code{if} statement introduced on line 5, it is | |
2822 given the @code{else-clause} syntax. Note also that line 10 is slightly | |
2823 different too. Because @code{else} is considered a conditional | |
2824 introducing keyword @footnote{The list of conditional keywords are (in | |
2825 C, C++, Objective-C, and Java): @code{for}, @code{if}, @code{do}, | |
2826 @code{else}, @code{while}, and @code{switch}. C++ and Java have two | |
2827 additional conditional keywords: @code{try} and @code{catch}. Java also | |
2828 has the @code{finally} and @code{synchronized} keywords.}, and because | |
2829 the following substatement is not a brace block, line 10 is assigned the | |
2830 @code{substatement} syntax. | |
2831 | |
2832 @cindex do-while-closure syntactic symbol | |
2833 One other difference is seen on line 15. The @code{while} construct | |
2834 that closes a @code{do} conditional is given the special syntax | |
2835 @code{do-while-closure} if it appears on a line by itself. Note that if | |
2836 the @code{while} appeared on the same line as the preceding close brace, | |
2837 that line would have been assigned @code{block-close} syntax instead. | |
2838 | |
2839 Switch statements have their own set of syntactic symbols. Here's an | |
2840 example: | |
2841 @example | |
2842 @group | |
2843 | |
2844 1: void spam( enum Ingredient i ) | |
2845 2: @{ | |
2846 3: switch( i ) @{ | |
2847 4: case Ham: | |
2848 5: be_a_pig(); | |
2849 6: break; | |
2850 7: case Salt: | |
2851 8: drink_some_water(); | |
2852 9: break; | |
2853 10: default: | |
2854 11: @{ | |
2855 12: what_is_it(); | |
2856 13: break; | |
2857 14: @} | |
2858 15: @} | |
2859 14: @} | |
2860 | |
2861 @end group | |
2862 @end example | |
2863 | |
2864 @cindex case-label syntactic symbol | |
2865 @cindex statement-case-intro syntactic symbol | |
2866 @cindex statement-case-open syntactic symbol | |
2867 Here, lines 4, 7, and 10 are all assigned @code{case-label} syntax, | |
2868 while lines 5 and 8 are assigned @code{statement-case-intro}. Line 11 | |
2869 is treated slightly differently since it contains a brace that opens a | |
2870 block --- it is given @code{statement-case-open} syntax. | |
2871 | |
2872 @cindex brace lists | |
2873 There are a set of syntactic symbols that are used to recognize | |
2874 constructs inside of brace lists. A brace list is defined as an | |
2875 @code{enum} or aggregate initializer list, such as might statically | |
2876 initialize an array of structs. For example: | |
2877 @example | |
2878 @group | |
2879 | |
2880 1: static char* ingredients[] = | |
2881 2: @{ | |
2882 3: "Ham", | |
2883 4: "Salt", | |
2884 5: NULL | |
2885 6: @} | |
2886 | |
2887 @end group | |
2888 @end example | |
2889 | |
2890 @cindex brace-list-open syntactic symbol | |
2891 @cindex brace-list-intro syntactic symbol | |
2892 @cindex brace-list-close syntactic symbol | |
2893 @cindex brace-list-entry syntactic symbol | |
2894 Following convention, line 2 in this example is assigned | |
2895 @code{brace-list-open} syntax, and line 3 is assigned | |
2896 @code{brace-list-intro} syntax. Likewise, line 6 is assigned | |
2897 @code{brace-list-close} syntax. Lines 4 and 5 however, are assigned | |
2898 @code{brace-list-entry} syntax, as would all subsequent lines in this | |
2899 initializer list. | |
2900 | |
2901 External language definition blocks also have their own syntactic | |
2902 symbols. In this example: | |
2903 @example | |
2904 @group | |
2905 | |
2906 1: extern "C" | |
2907 2: @{ | |
2908 3: int thing_one( int ); | |
2909 4: int thing_two( double ); | |
2910 5: @} | |
2911 | |
2912 @end group | |
2913 @end example | |
2914 | |
2915 @cindex extern-lang-open syntactic symbol | |
2916 @cindex extern-lang-close syntactic symbol | |
2917 @cindex inextern-lang syntactic symbol | |
2918 @cindex inclass syntactic symbol | |
2919 @noindent | |
2920 line 2 is given the @code{extern-lang-open} syntax, while line 5 is given | |
2921 the @code{extern-lang-close} syntax. The analysis for line 3 yields: | |
2922 @code{((inextern-lang) (topmost-intro . 14))}, where | |
2923 @code{inextern-lang} is a modifier similar in purpose to @code{inclass}. | |
2924 | |
2925 Similarly, C++ namespace constructs have their own associated syntactic | |
2926 symbols. In this example: | |
2927 @example | |
2928 @group | |
2929 | |
2930 1: namespace foo | |
2931 2: @{ | |
2932 3: void xxx() @{@} | |
2933 4: @} | |
2934 | |
2935 @end group | |
2936 @end example | |
2937 | |
2938 @cindex namespace-open syntactic-symbol | |
2939 @cindex namespace-close syntactic-symbol | |
2940 @cindex innamespace syntactic-symbol | |
2941 @noindent | |
2942 line 2 is given the @code{namespace-open} syntax, while line 4 is given | |
2943 the @code{namespace-close} syntax. The analysis for line 3 yields: | |
2944 @code{((innamespace) (topmost-intro . 17))}, where @code{innamespace} is | |
2945 a modifier similar in purpose to @code{inextern-lang} and @code{inclass}. | |
2946 | |
2947 A number of syntactic symbols are associated with parenthesis lists, | |
2948 a.k.a argument lists, as found in function declarations and function | |
2949 calls. This example illustrates these: | |
2950 @example | |
2951 @group | |
2952 | |
2953 1: void a_function( int line1, | |
2954 2: int line2 ); | |
2955 3: | |
2956 4: void a_longer_function( | |
2957 5: int line1, | |
2958 6: int line2 | |
2959 7: ); | |
2960 8: | |
2961 9: void call_them( int line1, int line2 ) | |
2962 10: @{ | |
2963 11: a_function( | |
2964 12: line1, | |
2965 13: line2 | |
2966 14: ); | |
2967 15: | |
2968 16: a_longer_function( line1, | |
2969 17: line2 ); | |
2970 18: @} | |
2971 | |
2972 @end group | |
2973 @end example | |
2974 | |
2975 @cindex arglist-intro syntactic symbol | |
2976 @cindex arglist-close syntactic symbol | |
2977 Lines 5 and 12 are assigned @code{arglist-intro} syntax since they are | |
2978 the first line following the open parenthesis, and lines 7 and 14 are | |
2979 assigned @code{arglist-close} syntax since they contain the parenthesis | |
2980 that closes the argument list. | |
2981 | |
2982 @cindex arglist-cont-nonempty syntactic symbol | |
2983 @cindex arglist-cont syntactic symbol | |
2984 Lines that continue argument lists can be assigned one of two syntactic | |
2985 symbols. For example, Lines 2 and 17 | |
2986 are assigned @code{arglist-cont-nonempty} syntax. What this means | |
2987 is that they continue an argument list, but that the line containing the | |
2988 parenthesis that opens the list is @emph{not empty} following the open | |
2989 parenthesis. Contrast this against lines 6 and 13 which are assigned | |
2990 @code{arglist-cont} syntax. This is because the parenthesis that opens | |
2991 their argument lists is the last character on that line. | |
2992 | |
2993 Note that there is no @code{arglist-open} syntax. This is because any | |
2994 parenthesis that opens an argument list, appearing on a separate line, | |
2995 is assigned the @code{statement-cont} syntax instead. | |
2996 | |
2997 A few miscellaneous syntactic symbols that haven't been previously | |
2998 covered are illustrated by this C++ example: | |
2999 @example | |
3000 @group | |
3001 | |
3002 1: void Bass::play( int volume ) | |
3003 2: const | |
3004 3: @{ | |
3005 4: /* this line starts a multi-line | |
3006 5: * comment. This line should get `c' syntax */ | |
3007 6: | |
3008 7: char* a_multiline_string = "This line starts a multi-line \ | |
3009 8: string. This line should get `string' syntax."; | |
3010 9: | |
3011 10: note: | |
3012 11: @{ | |
3013 12: #ifdef LOCK | |
3014 13: Lock acquire(); | |
3015 14: #endif // LOCK | |
3016 15: slap_pop(); | |
3017 16: cout << "I played " | |
3018 17: << "a note\n"; | |
3019 18: @} | |
3020 19: @} | |
3021 | |
3022 @end group | |
3023 @end example | |
3024 | |
3025 @cindex modifier syntactic symbol | |
3026 The lines to note in this example include: | |
3027 | |
3028 @itemize @bullet | |
3029 | |
3030 @cindex func-decl-cont syntactic symbol | |
3031 @item | |
3032 line 2, assigned the @code{func-decl-cont} syntax; | |
3033 | |
3034 @cindex comment-intro syntactic symbol | |
3035 @item | |
3036 line 4, assigned both @code{defun-block-intro} @emph{and} | |
3037 @code{comment-intro} syntax; | |
3038 | |
3039 @cindex c syntactic symbol | |
3040 @item | |
3041 line 5, assigned @code{c} syntax; | |
3042 | |
3043 @item | |
3044 @cindex syntactic whitespace | |
3045 line 6 which, even though it contains nothing but whitespace, is | |
3046 assigned @code{defun-block-intro}. Note that the appearance of the | |
3047 comment on lines 4 and 5 do not cause line 6 to be assigned | |
3048 @code{statement} syntax because comments are considered to be | |
3049 @dfn{syntactic whitespace}, which are ignored when analyzing | |
3050 code; | |
3051 | |
3052 @cindex string syntactic symbol | |
3053 @item | |
3054 line 8, assigned @code{string} syntax; | |
3055 | |
3056 @cindex label syntactic symbol | |
3057 @item | |
3058 line 10, assigned @code{label} syntax; | |
3059 | |
3060 @cindex block-open syntactic symbol | |
3061 @item | |
3062 line 11, assigned @code{block-open} syntax; | |
3063 | |
3064 @cindex cpp-macro syntactic symbol | |
3065 @cindex cpp-macro-cont syntactic symbol | |
3066 @item | |
3067 lines 12 and 14, assigned @code{cpp-macro} syntax. | |
3068 | |
3069 @cindex stream-op syntactic symbol | |
3070 @item | |
3071 line 17, assigned @code{stream-op} syntax. | |
3072 | |
3073 @end itemize | |
3074 | |
3075 @cindex multi-line macros | |
3076 @cindex syntactic whitespace | |
3077 Multi-line C preprocessor macros are now (somewhat) supported. At least | |
3078 CC Mode now recognizes the fact that it is inside a multi-line macro, | |
3079 and it properly skips such macros as syntactic whitespace. In this | |
3080 example: | |
3081 @example | |
3082 @group | |
3083 | |
3084 1: #define LIST_LOOP(cons, listp) \ | |
3085 2: for (cons = listp; !NILP (cons); cons = XCDR (cons)) \ | |
3086 3: if (!CONSP (cons)) \ | |
3087 4: signal_error ("Invalid list format", listp); \ | |
3088 5: else | |
3089 | |
3090 @end group | |
3091 @end example | |
3092 @noindent | |
3093 line 1 is given the syntactic symbol @code{cpp-macro}. This first line | |
3094 of a macro is always given this symbol. The second and subsequent lines | |
3095 (e.g. lines 2 through 5) are given the @code{cpp-macro-cont} syntactic | |
3096 symbol, with a relative buffer position pointing to the @code{#} which | |
3097 starts the macro definition. | |
3098 | |
3099 In Objective-C buffers, there are three additional syntactic symbols | |
3100 assigned to various message calling constructs. Here's an example | |
3101 illustrating these: | |
3102 @example | |
3103 @group | |
3104 | |
3105 1: - (void)setDelegate:anObject | |
3106 2: withStuff:stuff | |
3107 3: @{ | |
3108 4: [delegate masterWillRebind:self | |
3109 5: toDelegate:anObject | |
3110 6: withExtraStuff:stuff]; | |
3111 7: @} | |
3112 | |
3113 @end group | |
3114 @end example | |
3115 | |
3116 @cindex objc-method-intro syntactic symbol | |
3117 @cindex objc-method-args-cont syntactic symbol | |
3118 @cindex objc-method-call-cont syntactic symbol | |
3119 Here, line 1 is assigned @code{objc-method-intro} syntax, and line 2 is | |
3120 assigned @code{objc-method-args-cont} syntax. Lines 5 and 6 are both | |
3121 assigned @code{objc-method-call-cont} syntax. | |
3122 | |
3123 @cindex knr-argdecl-intro syntactic symbol | |
3124 @cindex knr-argdecl syntactic symbol | |
3125 Two other syntactic symbols can appear in old style, non-prototyped C | |
3126 code @footnote{a.k.a. K&R C, or Kernighan & Ritchie C}: | |
3127 @example | |
3128 @group | |
3129 | |
3130 1: int add_three_integers(a, b, c) | |
3131 2: int a; | |
3132 3: int b; | |
3133 4: int c; | |
3134 5: @{ | |
3135 6: return a + b + c; | |
3136 7: @} | |
3137 | |
3138 @end group | |
3139 @end example | |
3140 | |
3141 Here, line 2 is the first line in an argument declaration list and so is | |
3142 given the @code{knr-argdecl-intro} syntactic symbol. Subsequent lines | |
3143 (i.e. lines 3 and 4 in this example), are given @code{knr-argdecl} | |
3144 syntax. | |
3145 | |
3146 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
3147 @node Performance Issues, Frequently Asked Questions, Syntactic Symbols, Top | |
3148 @comment node-name, next, previous,up | |
3149 | |
3150 @chapter Performance Issues | |
3151 @cindex Performance Issues | |
3152 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
3153 | |
3154 C and its derivative languages are highly complex creatures. Often, | |
3155 ambiguous code situations arise that require @ccmode{} to scan | |
3156 large portions of the buffer to determine syntactic context. Such | |
3157 pathological code@footnote{such as the output of @code{lex(1)}!} | |
3158 can cause @ccmode{} to perform fairly badly. | |
3159 This section identifies some of the coding styles to watch out for, and | |
3160 suggests some workarounds that you can use to improve performance. | |
3161 | |
3162 Because @ccmode{} has to scan the buffer backwards from the current | |
3163 insertion point, and because C's syntax is fairly difficult to parse in | |
3164 the backwards direction, @ccmode{} often tries to find the nearest | |
3165 position higher up in the buffer from which to begin a forward scan. | |
3166 The farther this position is from the current insertion point, the | |
3167 slower the mode gets. Some coding styles can even force @ccmode{} | |
3168 to scan from the beginning of the buffer for every line of code! | |
3169 | |
3170 @findex beginning-of-defun | |
3171 @findex defun-prompt-regexp | |
3172 One of the simplest things you can do to reduce scan time, is make sure | |
3173 any brace that opens a top-level construct@footnote{e.g. a function in | |
3174 C, or outermost class definition in C++ or Java.} always appears in the | |
3175 leftmost column. This is actually an Emacs constraint, as embodied in | |
3176 the @code{beginning-of-defun} function which @ccmode{} uses | |
3177 heavily. If you insist on hanging top-level open braces on the right | |
3178 side of the line, then you might want to set the variable | |
3179 @code{defun-prompt-regexp} to something reasonable @footnote{Note that | |
3180 this variable is only defined in Emacs 19.}, however that ``something | |
3181 reasonable'' is difficult to define, so @ccmode{} doesn't do it | |
3182 for you. | |
3183 | |
3184 @vindex c-Java-defun-prompt-regexp | |
3185 @vindex Java-defun-prompt-regexp (c-) | |
3186 A special note about @code{defun-prompt-regexp} in Java mode: while much | |
3187 of the early sample Java code seems to encourage a style where the brace | |
3188 that opens a class is hung on the right side of the line, this is not a | |
3189 good style to pursue in Emacs. @ccmode{} comes with a variable | |
3190 @code{c-Java-defun-prompt-regexp} which tries to define a regular | |
3191 expression usable for this style, but there are problems with it. In | |
3192 some cases it can cause @code{beginning-of-defun} to hang@footnote{This | |
3193 has been observed in Emacs 19.34 and XEmacs 19.15.}. For this reason, | |
3194 it is not used by default, but if you feel adventurous, you can set | |
3195 @code{defun-prompt-regexp} to it in your mode hook. In any event, | |
3196 setting and rely on @code{defun-prompt-regexp} will definitely slow | |
3197 things down! | |
3198 | |
3199 You will probably notice pathological behavior from @ccmode{} when | |
3200 working in files containing large amounts of C preprocessor macros. | |
3201 This is because Emacs cannot skip backwards over these lines as quickly | |
3202 as it can comment. | |
3203 | |
3204 @vindex c-recognize-knr-p | |
3205 @vindex recognize-knr-p (c-) | |
3206 Previous versions of @ccmode{} had potential performance problems | |
3207 when recognizing K&R style function argument declarations. This was | |
3208 because there are ambiguities in the C syntax when K&R style argument | |
3209 lists are used@footnote{It is hard to distinguish them from top-level | |
3210 declarations.}. @ccmode{} has adopted BOCM's convention for | |
3211 limiting the search: it assumes that argdecls are indented at least one | |
3212 space, and that the function headers are not indented at all. With | |
3213 current versions of @ccmode{}, user customization of | |
3214 @code{c-recognize-knr-p} is deprecated. Just don't put argdecls in | |
3215 column zero! | |
3216 | |
3217 @cindex @file{cc-lobotomy.el} file | |
3218 @vindex cc-lobotomy-pith-list | |
3219 You might want to investigate the speed-ups contained in the | |
3220 file @file{cc-lobotomy.el}, which comes as part of the @ccmode{} | |
3221 distribution, but is completely unsupported. | |
3222 As mentioned previous, @ccmode{} always trades speed for accuracy, | |
3223 however it is recognized that sometimes you need speed and can sacrifice | |
3224 some accuracy in indentation. The file @file{cc-lobotomy.el} contains | |
3225 hacks that will ``dumb down'' @ccmode{} in some specific ways, making | |
3226 that trade-off of accurancy for speed. I won't go into details of its | |
3227 use here; you should read the comments at the top of the file, and look | |
3228 at the variable @code{cc-lobotomy-pith-list} for details. | |
3229 | |
3230 | |
3231 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
3232 @node Frequently Asked Questions, Getting the latest CC Mode release, Performance Issues, Top | |
3233 @comment node-name, next, previous,up | |
3234 | |
3235 @chapter Frequently Asked Questions | |
3236 @cindex Frequently Asked Questions | |
3237 @comment FAQ | |
3238 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
3239 | |
3240 @kindex C-x h | |
3241 @kindex ESC C-\ | |
3242 @kindex ESC C-x | |
3243 @kindex C-c C-q | |
3244 @kindex ESC C-q | |
3245 @kindex ESC C-u | |
3246 @kindex RET | |
3247 @kindex C-j | |
3248 @findex newline-and-indent | |
3249 @quotation | |
3250 | |
3251 @strong{Q.} @emph{How do I re-indent the whole file?} | |
3252 | |
3253 @strong{A.} Visit the file and hit @kbd{C-x h} to mark the whole | |
3254 buffer. Then hit @kbd{ESC C-\}. | |
3255 @sp 1 | |
3256 | |
3257 @strong{Q.} @emph{How do I re-indent the entire function? | |
3258 @kbd{ESC C-x} doesn't work.} | |
3259 | |
3260 @strong{A.} @kbd{ESC C-x} is reserved for future Emacs use. | |
3261 To re-indent the entire function hit @kbd{C-c C-q}. | |
3262 @sp 1 | |
3263 | |
3264 @strong{Q.} @emph{How do I re-indent the current block?} | |
3265 | |
3266 @strong{A.} First move to the brace which opens the block with | |
3267 @kbd{ESC C-u}, then re-indent that expression with | |
3268 @kbd{ESC C-q}. | |
3269 @sp 1 | |
3270 | |
3271 @strong{Q.} @emph{Why doesn't the @kbd{RET} key indent the line to | |
3272 where the new text should go after inserting the newline?} | |
3273 | |
3274 @strong{A.} Emacs' convention is that @kbd{RET} just adds a newline, | |
3275 and that @kbd{C-j} adds a newline and indents it. You can make | |
3276 @kbd{RET} do this too by adding this to your | |
3277 @code{c-mode-common-hook} (see the sample @file{.emacs} file | |
3278 @ref{Sample .emacs File}): | |
3279 @example | |
3280 | |
3281 (define-key c-mode-base-map "\C-m" 'newline-and-indent) | |
3282 | |
3283 @end example | |
3284 | |
3285 This is a very common question. If you want this to be the default | |
3286 behavior, don't lobby me, lobby RMS! @code{:-)} | |
3287 @sp 1 | |
3288 | |
3289 @strong{Q.} @emph{I put @code{(c-set-offset 'substatement-open 0)} | |
3290 in my @file{.emacs} file but I get an error saying that | |
3291 @code{c-set-offset}'s function definition is void.} | |
3292 | |
3293 @strong{A.} This means that @ccmode{} wasn't loaded into your | |
3294 Emacs session by the time the @code{c-set-offset} call was reached, | |
3295 mostly likely because @ccmode{} is being autoloaded. Instead | |
3296 of putting the @code{c-set-offset} line in your top-level | |
3297 @file{.emacs} file, put it in your @code{c-mode-common-hook}, or | |
3298 simply add the following to the top of your @file{.emacs} file: | |
3299 @example | |
3300 | |
3301 (require 'cc-mode) | |
3302 | |
3303 @end example | |
3304 | |
3305 See the sample @file{.emacs} file @ref{Sample .emacs File} for | |
3306 details. | |
3307 | |
3308 @sp 1 | |
3309 @strong{Q.} @emph{How do I make strings, comments, keywords, and other | |
3310 constructs appear in different colors, or in bold face, etc.?} | |
3311 | |
3312 @strong{A.} ``Syntax Colorization'' is a standard Emacs feature, | |
3313 controlled by @code{font-lock-mode}. It is not part of @ccmode{}. | |
3314 | |
3315 @sp 1 | |
3316 @strong{Q.} @emph{@kbd{M-a} and @kbd{M-e} used to move over entire | |
3317 balanced brace lists, but now they move into blocks. How do I get the | |
3318 old behavior back?} | |
3319 | |
3320 @strong{A.} Use @kbd{C-M-f} and @kbd{C-M-b} to move over balanced brace | |
3321 blocks. Use @kbd{M-a} and @kbd{M-e} to move by statements, which will | |
3322 move into blocks. | |
3323 | |
3324 @end quotation | |
3325 | |
3326 | |
3327 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
3328 @node Getting the latest CC Mode release, Sample .emacs File, Frequently Asked Questions, Top | |
3329 @comment node-name, next, previous,up | |
3330 | |
3331 @chapter Getting the latest CC Mode release | |
3332 @cindex Getting the latest CC Mode release | |
3333 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
3334 | |
3335 @ccmode{} is now standard with the latest versions of Emacs 19 and | |
3336 XEmacs 19. It is also the standard for Emacs 20 and XEmacs 20. You | |
3337 would typically just use the version that comes with your X/Emacs. | |
3338 These may be slightly out of date due to release schedule skew, so you | |
3339 should always check the canonical site for the latest version. | |
3340 | |
3341 @example | |
3342 @group | |
3343 | |
3344 World Wide Web: | |
3345 | |
3346 @code{http://www.python.org/ftp/emacs/} | |
3347 | |
3348 Anonymous FTP: | |
3349 | |
3350 @code{ftp://ftp.python.org/pub/emacs/} | |
3351 | |
3352 @end group | |
3353 @end example | |
3354 | |
3355 There are many files under these directories; you can pick up the entire | |
3356 distribution (named @code{cc-mode.tar.gz}; a gzip'd tar file), or any of | |
3357 the individual files, including PostScript documentation. | |
3358 | |
3359 If you do not have World Wide Web, or anonymous ftp access, you can get | |
3360 the distribution through an anonymous ftp-to-mail gateway, such as the | |
3361 one run by DEC at: | |
3362 @example | |
3363 | |
3364 @code{ftpmail@@decwrl.dec.com} | |
3365 | |
3366 @end example | |
3367 To get @ccmode{} via email, send the following message in the body of | |
3368 your mail to that address: | |
3369 @example | |
3370 | |
3371 reply <a valid net address back to you> | |
3372 connect ftp.python.org | |
3373 binary | |
3374 uuencode | |
3375 chdir pub/emacs | |
3376 get cc-mode.tar.gz | |
3377 | |
3378 @end example | |
3379 @noindent | |
3380 or just send the message "help" for more information on ftpmail. | |
3381 Response times will vary with the number of requests in the queue. I am | |
3382 in no way connected to this service, so I make no claims or guarantees | |
3383 about its availability! | |
3384 | |
3385 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
3386 @node Sample .emacs File, Limitations and Known Bugs, Getting the latest CC Mode release, Top | |
3387 @comment node-name, next, previous,up | |
3388 | |
3389 @chapter Sample .emacs file | |
3390 @cindex Sample .emacs file | |
3391 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
3392 | |
3393 @example | |
3394 ;; Here's a sample .emacs file that might help you along the way. Just | |
3395 ;; copy this region and paste it into your .emacs file. You may want to | |
3396 ;; change some of the actual values. | |
3397 | |
3398 (defconst my-c-style | |
3399 '((c-tab-always-indent . t) | |
3400 (c-comment-only-line-offset . 4) | |
3401 (c-hanging-braces-alist . ((substatement-open after) | |
3402 (brace-list-open))) | |
3403 (c-hanging-colons-alist . ((member-init-intro before) | |
3404 (inher-intro) | |
3405 (case-label after) | |
3406 (label after) | |
3407 (access-label after))) | |
3408 (c-cleanup-list . (scope-operator | |
3409 empty-defun-braces | |
3410 defun-close-semi)) | |
3411 (c-offsets-alist . ((arglist-close . c-lineup-arglist) | |
3412 (substatement-open . 0) | |
3413 (case-label . 4) | |
3414 (block-open . 0) | |
3415 (knr-argdecl-intro . -))) | |
3416 (c-echo-syntactic-information-p . t) | |
3417 ) | |
3418 "My C Programming Style") | |
3419 | |
3420 ;; Customizations for all of c-mode, c++-mode, and objc-mode | |
3421 (defun my-c-mode-common-hook () | |
3422 ;; add my personal style and set it for the current buffer | |
3423 (c-add-style "PERSONAL" my-c-style t) | |
3424 ;; offset customizations not in my-c-style | |
3425 (c-set-offset 'member-init-intro '++) | |
3426 ;; other customizations | |
3427 (setq tab-width 8 | |
3428 ;; this will make sure spaces are used instead of tabs | |
3429 indent-tabs-mode nil) | |
3430 ;; we like auto-newline and hungry-delete | |
3431 (c-toggle-auto-hungry-state 1) | |
3432 ;; keybindings for all supported languages. We can put these in | |
3433 ;; c-mode-base-map because c-mode-map, c++-mode-map, objc-mode-map, | |
3434 ;; java-mode-map, and idl-mode-map inherit from it. | |
3435 (define-key c-mode-base-map "\C-m" 'newline-and-indent) | |
3436 ) | |
3437 | |
3438 (add-hook 'c-mode-common-hook 'my-c-mode-common-hook) | |
3439 @end example | |
3440 | |
3441 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
3442 @node Limitations and Known Bugs, Mailing Lists and Submitting Bug Reports, Sample .emacs File, Top | |
3443 @comment node-name, next, previous,up | |
3444 @chapter Limitations and Known Bugs | |
3445 @cindex Limitations and Known Bugs | |
3446 @comment * Limitations and Known Bugs | |
3447 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
3448 | |
3449 @itemize @bullet | |
3450 @item | |
3451 Re-indenting large regions or expressions can be slow. | |
3452 | |
3453 @item | |
3454 Add-on fill packages may not work as well as @ccmode{}'s built-in | |
3455 filling routines. I no longer recommend you use @code{filladapt} to | |
3456 fill comments. | |
3457 | |
3458 @cindex c-indent-exp | |
3459 @cindex indent-exp (c-) | |
3460 @item | |
3461 @code{c-indent-exp} has not been fully optimized. It essentially | |
3462 equivalent to hitting @kbd{TAB} (@code{c-indent-command}) on every | |
3463 line. Some information is cached from line to line, but such caching | |
3464 invariable causes inaccuracies in analysis in some bizarre situations. | |
3465 | |
3466 @end itemize | |
3467 | |
3468 @c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
3469 @node Mailing Lists and Submitting Bug Reports, Concept Index, Limitations and Known Bugs, Top | |
3470 @comment node-name, next, previous,up | |
3471 @chapter Mailing Lists and Submitting Bug Reports | |
3472 @cindex Mailing Lists and Submitting Bug Reports | |
3473 @c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
3474 | |
3475 @kindex C-c C-b | |
3476 @findex c-submit-bug-report | |
3477 @findex submit-bug-report (c-) | |
3478 @cindex beta testers mailing list | |
3479 @cindex announcement mailing list | |
3480 To report bugs, use the @kbd{C-c C-b} (@code{c-submit-bug-report}) | |
3481 command. This provides vital information I need to reproduce your | |
3482 problem. Make sure you include a concise, but complete code example. | |
3483 Please try to boil your example down to just the essential code needed | |
3484 to reproduce the problem, and include an exact recipe of steps needed to | |
3485 expose the bug. Be especially sure to include any code that appears | |
3486 @emph{before} your bug example, if you think it might affect my ability | |
3487 to reproduce it. | |
3488 | |
3489 Bug reports are now sent to the following email addresses: | |
3490 @code{cc-mode-help@@python.org} and | |
3491 @code{bug-gnu-emacs@@gnu.org}; the latter is mirrored on the | |
3492 Usenet newsgroup @code{gnu.emacs.bug}. You can send other questions and | |
3493 suggestions (kudos? @code{;-)} to @code{cc-mode-help@@python.org}, or | |
3494 @code{help-gnu-emacs@@gnu.org} which is mirrored on newsgroup | |
3495 @code{gnu.emacs.help}. | |
3496 | |
3497 If you want to get announcements of new CC Mode releases, send the | |
3498 word @emph{subscribe} in the body of a message to | |
3499 @code{cc-mode-announce-request@@python.org}. Announcements will also be | |
3500 posted to the Usenet newsgroup @code{gnu.emacs.sources}. Note that the | |
3501 @code{cc-mode-victims@@python.org} mailing list was recently | |
3502 decommissioned. | |
3503 | |
3504 @c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
3505 @node Concept Index, Command Index, Mailing Lists and Submitting Bug Reports, Top | |
3506 @comment node-name, next, previous, up | |
3507 @unnumbered Concept Index | |
3508 @c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
3509 | |
3510 @printindex cp | |
3511 | |
3512 | |
3513 @c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
3514 @node Command Index, Key Index, Concept Index, Top | |
3515 @comment node-name, next, previous, up | |
3516 @unnumbered Command Index | |
3517 @c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
3518 | |
3519 @ifinfo | |
3520 | |
3521 @end ifinfo | |
3522 Since all @ccmode{} commands are prepended with the string | |
3523 @samp{c-}, each appears under its @code{c-@var{<thing>}} name and its | |
3524 @code{@var{<thing>} (c-)} name. | |
3525 @iftex | |
3526 @sp 2 | |
3527 @end iftex | |
3528 @printindex fn | |
3529 | |
3530 | |
3531 @c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
3532 @node Key Index, Variable Index, Command Index, Top | |
3533 @comment node-name, next, previous, up | |
3534 @unnumbered Key Index | |
3535 @c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
3536 | |
3537 @printindex ky | |
3538 | |
3539 | |
3540 @c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
3541 @node Variable Index, , Key Index, Top | |
3542 @comment node-name, next, previous, up | |
3543 @unnumbered Variable Index | |
3544 @c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
3545 | |
3546 @ifinfo | |
3547 | |
3548 @end ifinfo | |
3549 Since all @ccmode{} variables are prepended with the string | |
3550 @samp{c-}, each appears under its @code{c-@var{<thing>}} name and its | |
3551 @code{@var{<thing>} (c-)} name. | |
3552 @iftex | |
3553 @sp 2 | |
3554 @end iftex | |
3555 @printindex vr | |
3556 @page | |
3557 @summarycontents | |
3558 @contents | |
3559 @bye | |
3560 |