Commit | Line | Data |
---|---|---|
6bf7aab6 DL |
1 | \input texinfo |
2 | ||
3 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
4 | @comment %**start of header (This is for running Texinfo on a region) | |
5 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
6 | ||
d7bd46ed GM |
7 | @comment No overfull hbox marks in the dvi file. |
8 | @finalout | |
6bf7aab6 | 9 | |
94cae5a8 | 10 | @setfilename ../info/ccmode |
cb7f2e96 | 11 | @settitle CC Mode Manual |
d7bd46ed | 12 | @footnotestyle end |
6bf7aab6 DL |
13 | |
14 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
15 | @comment @setchapternewpage odd !! we don't want blank pages !! | |
16 | @comment %**end of header (This is for running Texinfo on a region) | |
17 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
18 | ||
19 | ||
20 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
21 | @comment | |
22 | @comment Texinfo manual for CC Mode | |
23 | @comment Generated from the original README file by Krishna Padmasola | |
24 | @comment <krishna@earth-gw.njit.edu> | |
cb7f2e96 GM |
25 | @comment |
26 | @comment Authors: | |
27 | @comment Barry A. Warsaw | |
28 | @comment Martin Stjernholm | |
29 | @comment | |
f214c025 | 30 | @comment Maintained by Martin Stjernholm <bug-cc-mode@gnu.org> |
6bf7aab6 DL |
31 | @comment |
32 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
33 | ||
cb7f2e96 GM |
34 | @macro copyrightblurb |
35 | Copyright @copyright{} 1995, 96, 97, 98, 99, 2000, 01 Free Software Foundation, Inc. | |
36 | @end macro | |
37 | ||
38 | @comment Info directory entry for use by install-info. The indentation | |
39 | @comment here is by request from the FSF folks. | |
f214c025 GM |
40 | @dircategory Emacs |
41 | @direntry | |
94cae5a8 | 42 | * CC Mode: (ccmode). Emacs mode for editing C, C++, Objective-C, |
a367c22c | 43 | Java, Pike, and IDL code. |
f214c025 | 44 | @end direntry |
6bf7aab6 DL |
45 | |
46 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
cb7f2e96 | 47 | @comment The following lines inserts the copyright notice |
6bf7aab6 DL |
48 | @comment into the Info file. |
49 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
50 | ||
a367c22c | 51 | @ifnottex |
94cae5a8 GM |
52 | Copyright @copyright{} 1995, 96, 97, 98, 99, 2000, 2001 Free Software Foundation, Inc. |
53 | ||
54 | Permission is granted to copy, distribute and/or modify this document | |
55 | under the terms of the GNU Free Documentation License, Version 1.1 or | |
56 | any later version published by the Free Software Foundation; with the | |
57 | Invariant Sections being ``The GNU Manifesto'', ``Distribution'' and | |
58 | ``GNU GENERAL PUBLIC LICENSE'', with the Front-Cover texts being ``A GNU | |
59 | Manual'', and with the Back-Cover Texts as in (a) below. A copy of the | |
60 | license is included in the section entitled ``GNU Free Documentation | |
61 | License'' in the Emacs manual. | |
62 | ||
63 | (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify | |
64 | this GNU Manual, like GNU software. Copies published by the Free | |
65 | Software Foundation raise funds for GNU development.'' | |
66 | ||
67 | This document is part of a collection distributed under the GNU Free | |
68 | Documentation License. If you want to distribute this document | |
69 | separately from the collection, you can do so by adding a copy of the | |
70 | license to the document, as described in section 6 of the license. | |
a367c22c | 71 | @end ifnottex |
6bf7aab6 DL |
72 | |
73 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
cb7f2e96 | 74 | @comment TeX title page |
6bf7aab6 DL |
75 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
76 | ||
77 | @titlepage | |
78 | @sp 10 | |
79 | ||
cb7f2e96 | 80 | @center @titlefont{CC Mode 5.28} |
6bf7aab6 DL |
81 | @sp 2 |
82 | @center @subtitlefont{A GNU Emacs mode for editing C and C-like languages} | |
83 | @sp 2 | |
cb7f2e96 | 84 | @center Barry A. Warsaw, Martin Stjernholm |
6bf7aab6 DL |
85 | |
86 | @page | |
87 | @vskip 0pt plus 1filll | |
94cae5a8 GM |
88 | Copyright @copyright{} 1995, 96, 97, 98, 99, 2000, 2001 Free Software Foundation, Inc. |
89 | @sp 1 | |
90 | Permission is granted to copy, distribute and/or modify this document | |
91 | under the terms of the GNU Free Documentation License, Version 1.1 or | |
92 | any later version published by the Free Software Foundation; with the | |
93 | Invariant Sections being ``The GNU Manifesto'', ``Distribution'' and | |
94 | ``GNU GENERAL PUBLIC LICENSE'', with the Front-Cover texts being ``A GNU | |
95 | Manual'', and with the Back-Cover Texts as in (a) below. A copy of the | |
96 | license is included in the section entitled ``GNU Free Documentation | |
97 | License'' in the Emacs manual. | |
98 | ||
99 | (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify | |
100 | this GNU Manual, like GNU software. Copies published by the Free | |
101 | Software Foundation raise funds for GNU development.'' | |
102 | ||
103 | This document is part of a collection distributed under the GNU Free | |
104 | Documentation License. If you want to distribute this document | |
105 | separately from the collection, you can do so by adding a copy of the | |
106 | license to the document, as described in section 6 of the license. | |
6bf7aab6 DL |
107 | @end titlepage |
108 | ||
6bf7aab6 DL |
109 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
110 | @comment The Top node contains the master menu for the Info file. | |
111 | @comment This appears only in the Info file, not the printed manual. | |
112 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
113 | ||
d7bd46ed GM |
114 | @node Top, Introduction, (dir), (dir) |
115 | @comment node-name, next, previous, up | |
116 | ||
117 | @macro ccmode | |
118 | CC Mode | |
119 | @end macro | |
120 | ||
121 | @ifinfo | |
122 | @top @ccmode{} | |
6bf7aab6 | 123 | |
d7bd46ed GM |
124 | @ccmode{} is a GNU Emacs mode for editing files containing C, C++, |
125 | Objective-C, Java, CORBA IDL, and Pike code. It provides syntax-based | |
126 | indentation and has several handy commands and some minor modes to make | |
127 | the editing easier. Note that @ccmode{} does @emph{not} provide | |
128 | font-locking; there are other Emacs packages for that. | |
129 | @end ifinfo | |
6bf7aab6 DL |
130 | |
131 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
132 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
133 | ||
134 | @menu | |
d7bd46ed GM |
135 | * Introduction:: |
136 | * Getting Connected:: | |
6bf7aab6 DL |
137 | * New Indentation Engine:: |
138 | * Minor Modes:: | |
d7bd46ed | 139 | * Text Filling and Line Breaking:: |
6bf7aab6 DL |
140 | * Commands:: |
141 | * Customizing Indentation:: | |
142 | * Syntactic Symbols:: | |
d7bd46ed | 143 | * Indentation Functions:: |
6bf7aab6 | 144 | * Performance Issues:: |
cb7f2e96 | 145 | * Limitations and Known Bugs:: |
6bf7aab6 | 146 | * Frequently Asked Questions:: |
d7bd46ed | 147 | * Getting the Latest CC Mode Release:: |
d7bd46ed | 148 | * Mailing Lists and Submitting Bug Reports:: |
cb7f2e96 | 149 | * Sample .emacs File:: |
d7bd46ed GM |
150 | |
151 | --- Indices --- | |
152 | ||
153 | * Concept Index:: | |
154 | * Command Index:: | |
155 | * Key Index:: | |
156 | * Variable Index:: | |
157 | ||
158 | --- The Detailed Node Listing --- | |
159 | ||
160 | New Indentation Engine | |
161 | ||
162 | * Syntactic Analysis:: | |
163 | * Indentation Calculation:: | |
164 | ||
165 | Minor Modes | |
166 | ||
167 | * Auto-newline Insertion:: | |
168 | * Hungry-deletion of Whitespace:: | |
169 | ||
170 | Auto-newline Insertion | |
171 | ||
172 | * Hanging Braces:: | |
173 | * Hanging Colons:: | |
174 | * Hanging Semi-colons and Commas:: | |
175 | * Other Electric Commands:: | |
176 | * Clean-ups:: | |
177 | ||
178 | Commands | |
179 | ||
180 | * Indentation Commands:: | |
181 | * Movement Commands:: | |
182 | * Other Commands:: | |
183 | ||
184 | Customizing Indentation | |
185 | ||
186 | * Interactive Customization:: | |
187 | * Permanent Customization:: | |
188 | * Hooks:: | |
189 | * Styles:: | |
190 | * Advanced Customizations:: | |
191 | ||
192 | Styles | |
193 | ||
194 | * Built-in Styles:: | |
195 | * Adding Styles:: | |
196 | * File Styles:: | |
197 | ||
198 | Advanced Customizations | |
199 | ||
200 | * Custom Indentation Functions:: | |
201 | * Custom Brace and Colon Hanging:: | |
202 | * Customizing Semi-colons and Commas:: | |
203 | * Other Special Indentations:: | |
6bf7aab6 DL |
204 | @end menu |
205 | ||
d7bd46ed | 206 | |
6bf7aab6 | 207 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
d7bd46ed GM |
208 | @node Introduction, Getting Connected, Top, Top |
209 | @comment node-name, next, previous, up | |
210 | @chapter Introduction | |
6bf7aab6 DL |
211 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
212 | ||
6bf7aab6 DL |
213 | @cindex BOCM |
214 | ||
d7bd46ed GM |
215 | Welcome to @ccmode{}, a GNU Emacs mode for editing files containing C, |
216 | C++, Objective-C, Java, CORBA IDL, and Pike code. This incarnation of | |
217 | the mode is descendant from @file{c-mode.el} (also called "Boring Old C | |
218 | Mode" or BOCM @t{:-)}, and @file{c++-mode.el} version 2, which Barry has | |
219 | been maintaining since 1992. @ccmode{} represents a significant | |
220 | milestone in the mode's life. It has been fully merged back with Emacs | |
221 | 19's @file{c-mode.el}. Also a new, more intuitive and flexible mechanism | |
222 | for controlling indentation has been developed. Late in 1997, Martin | |
223 | joined the @ccmode{} Maintainers Team, and implemented the Pike support. | |
f214c025 | 224 | As of 2000 Martin has taken over as the sole maintainer. |
d7bd46ed GM |
225 | |
226 | This manual describes @ccmode{} | |
227 | @comment The following line must appear on its own, so that the automated | |
cb7f2e96 | 228 | version 5.28. |
d7bd46ed | 229 | @comment Release.py script can update the version number automatically |
6bf7aab6 DL |
230 | |
231 | @ccmode{} supports the editing of K&R and ANSI C, @dfn{ARM} | |
d7bd46ed GM |
232 | @footnote{@cite{The Annotated C++ Reference Manual}, by Ellis and |
233 | Stroustrup.} C++, Objective-C, Java, CORBA's Interface Definition | |
234 | Language, and Pike@footnote{A C-like scripting language with its roots | |
235 | in the LPC language used in some MUD engines. See | |
236 | @uref{http://pike.idonex.se/}.} files. In this way, you can easily set | |
237 | up consistent coding styles for use in editing all of these languages. | |
238 | @ccmode{} does @emph{not} handle font-locking (a.k.a. syntax coloring, | |
239 | keyword highlighting) or anything of that nature, for any of these | |
240 | modes. Font-locking is handled by other Emacs packages. | |
6bf7aab6 DL |
241 | |
242 | This manual will describe the following: | |
243 | ||
244 | @itemize @bullet | |
245 | @item | |
246 | How to get started using @ccmode{}. | |
247 | ||
248 | @item | |
249 | How the new indentation engine works. | |
250 | ||
251 | @item | |
252 | How to customize the new indentation engine. | |
253 | ||
254 | @end itemize | |
255 | ||
256 | @findex c-mode | |
257 | @findex c++-mode | |
258 | @findex objc-mode | |
259 | @findex java-mode | |
260 | @findex idl-mode | |
d7bd46ed | 261 | @findex pike-mode |
94cae5a8 | 262 | Note that the name of this package is ``@ccmode{},'' but there is no top |
6bf7aab6 DL |
263 | level @code{cc-mode} entry point. All of the variables, commands, and |
264 | functions in @ccmode{} are prefixed with @code{c-@var{<thing>}}, and | |
d7bd46ed GM |
265 | @code{c-mode}, @code{c++-mode}, @code{objc-mode}, @code{java-mode}, |
266 | @code{idl-mode}, and @code{pike-mode} entry points are provided. This | |
267 | package is intended to be a replacement for @file{c-mode.el} and | |
268 | @file{c++-mode.el}. | |
6bf7aab6 DL |
269 | |
270 | @cindex @file{cc-compat.el} file | |
271 | This distribution also contains a file | |
272 | called @file{cc-compat.el} which should ease your transition from BOCM | |
273 | to @ccmode{}. If you have a BOCM configuration you are really happy | |
274 | with, and want to postpone learning how to configure @ccmode{}, take a | |
275 | look at that file. It maps BOCM configuration variables to @ccmode{}'s | |
276 | new indentation model. It is not actively supported so for the long | |
277 | run, you should learn how to customize @ccmode{} to support your coding | |
278 | style. | |
279 | ||
280 | A special word of thanks goes to Krishna Padmasola for his work in | |
281 | converting the original @file{README} file to Texinfo format. I'd also | |
282 | like to thank all the @ccmode{} victims who help enormously during the | |
283 | early beta stages of @ccmode{}'s development. | |
284 | ||
285 | ||
286 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
d7bd46ed GM |
287 | @node Getting Connected, New Indentation Engine, Introduction, Top |
288 | @comment node-name, next, previous, up | |
289 | @chapter Getting Connected | |
6bf7aab6 DL |
290 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
291 | ||
292 | If you got this version of @ccmode{} with Emacs or XEmacs, it should | |
293 | work just fine right out of the box. Note however that you may not have | |
294 | the latest @ccmode{} release and may want to upgrade your copy. | |
295 | ||
296 | If you are upgrading an existing @ccmode{} installation, please see the | |
297 | @file{README} file for installation details. @ccmode{} may not work | |
298 | with older versions of Emacs or XEmacs. See the @ccmode{} release notes | |
299 | Web pages for the latest information on Emacs version and package | |
d7bd46ed | 300 | compatibility (@pxref{Getting the Latest CC Mode Release}). |
6bf7aab6 DL |
301 | |
302 | @cindex @file{cc-mode-18.el} file | |
d7bd46ed GM |
303 | @emph{Note that @ccmode{} no longer |
304 | works with Emacs 18!}, so if you haven't upgraded from Emacs 18 by now, | |
305 | you are out of luck. | |
6bf7aab6 DL |
306 | |
307 | @findex c-version | |
308 | @findex version (c-) | |
309 | You can find out what version of @ccmode{} you are using by visiting a C | |
310 | file and entering @kbd{M-x c-version RET}. You should see this message in | |
311 | the echo area: | |
312 | @example | |
313 | ||
314 | Using CC Mode version 5.XX | |
315 | ||
316 | @end example | |
317 | ||
318 | @noindent | |
319 | where @samp{XX} is the minor release number. | |
320 | ||
321 | ||
322 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
d7bd46ed GM |
323 | @node New Indentation Engine, Minor Modes, Getting Connected, Top |
324 | @comment node-name, next, previous, up | |
325 | @chapter New Indentation Engine | |
326 | @cindex indentation engine | |
6bf7aab6 DL |
327 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
328 | ||
329 | @ccmode{} has a new indentation engine, providing a simplified, yet | |
330 | flexible and general mechanism for customizing indentation. It separates | |
331 | indentation calculation into two steps: first, @ccmode{} analyzes the | |
332 | line of code being indented to determine the kind of language construct | |
333 | it's looking at, then it applies user defined offsets to the current | |
334 | line based on this analysis. | |
335 | ||
336 | This section will briefly cover how indentation is calculated in | |
337 | @ccmode{}. It is important to understand the indentation model | |
338 | being used so that you will know how to customize @ccmode{} for | |
339 | your personal coding style. | |
340 | ||
341 | @menu | |
342 | * Syntactic Analysis:: | |
343 | * Indentation Calculation:: | |
344 | @end menu | |
345 | ||
346 | ||
347 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
d7bd46ed GM |
348 | @node Syntactic Analysis, Indentation Calculation, , New Indentation Engine |
349 | @comment node-name, next, previous, up | |
350 | @section Syntactic Analysis | |
351 | @cindex syntactic analysis | |
6bf7aab6 DL |
352 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
353 | ||
6bf7aab6 DL |
354 | @cindex relative buffer position |
355 | @cindex syntactic symbol | |
356 | @cindex syntactic component | |
357 | @cindex syntactic component list | |
6bf7aab6 DL |
358 | The first thing @ccmode{} does when indenting a line of code, is to |
359 | analyze the line, determining the @dfn{syntactic component list} of the | |
d7bd46ed GM |
360 | construct on that line. A syntactic component consists of a pair of |
361 | information (in lisp parlance, a @emph{cons cell}), where the first part | |
362 | is a @dfn{syntactic symbol}, and the second part is a @dfn{relative | |
6bf7aab6 | 363 | buffer position}. Syntactic symbols describe elements of C code |
d7bd46ed GM |
364 | @footnote{Unless otherwise noted, the term ``C code'' to refers to all |
365 | the C-like languages.}, e.g. @code{statement}, @code{substatement}, | |
366 | @code{class-open}, @code{class-close}, etc. @xref{Syntactic Symbols}, | |
367 | for a complete list of currently recognized syntactic symbols and their | |
368 | semantics. The style variable @code{c-offsets-alist} also contains the | |
369 | list of currently supported syntactic symbols. | |
6bf7aab6 DL |
370 | |
371 | Conceptually, a line of C code is always indented relative to the | |
372 | indentation of some line higher up in the buffer. This is represented | |
373 | by the relative buffer position in the syntactic component. | |
374 | ||
375 | Here is an example. Suppose we had the following code as the only thing | |
d7bd46ed GM |
376 | in a C++ buffer @footnote{The line numbers in this and future examples |
377 | don't actually appear in the buffer, of course!}: | |
6bf7aab6 DL |
378 | @example |
379 | @group | |
380 | ||
381 | 1: void swap( int& a, int& b ) | |
382 | 2: @{ | |
383 | 3: int tmp = a; | |
384 | 4: a = b; | |
385 | 5: b = tmp; | |
386 | 6: @} | |
387 | ||
388 | @end group | |
389 | @end example | |
390 | ||
391 | @kindex C-c C-s | |
392 | @findex c-show-syntactic-information | |
393 | @findex show-syntactic-information (c-) | |
394 | We can use the command @kbd{C-c C-s} | |
395 | (@code{c-show-syntactic-information}) to simply report what the | |
396 | syntactic analysis is for the current line. Running this command on | |
397 | line 4 of this example, we'd see in the echo area@footnote{With a universal | |
398 | argument (i.e. @kbd{C-u C-c C-s}) the analysis is inserted into the | |
399 | buffer as a comment | |
400 | on the current line.}: | |
401 | @example | |
402 | ||
403 | ((statement . 35)) | |
404 | ||
405 | @end example | |
406 | ||
407 | This tells us that the line is a statement and it is indented relative | |
408 | to buffer position 35, which happens to be the @samp{i} in @code{int} on | |
409 | line 3. If you were to move point to line 3 and hit @kbd{C-c C-s}, you | |
410 | would see: | |
411 | @example | |
412 | ||
413 | ((defun-block-intro . 29)) | |
414 | ||
415 | @end example | |
416 | ||
417 | This indicates that the @samp{int} line is the first statement in a top | |
418 | level function block, and is indented relative to buffer position 29, | |
419 | which is the brace just after the function header. | |
420 | ||
421 | Here's another example: | |
422 | @example | |
423 | @group | |
424 | ||
425 | 1: int add( int val, int incr, int doit ) | |
426 | 2: @{ | |
427 | 3: if( doit ) | |
428 | 4: @{ | |
429 | 5: return( val + incr ); | |
430 | 6: @} | |
431 | 7: return( val ); | |
432 | 8: @} | |
433 | ||
434 | @end group | |
435 | @end example | |
436 | ||
437 | @noindent | |
438 | Hitting @kbd{C-c C-s} on line 4 gives us: | |
439 | @example | |
440 | ||
441 | ((substatement-open . 46)) | |
442 | ||
443 | @end example | |
444 | ||
445 | @cindex substatement | |
d7bd46ed | 446 | @cindex substatement block |
6bf7aab6 DL |
447 | @noindent |
448 | which tells us that this is a brace that @emph{opens} a substatement | |
449 | block. @footnote{A @dfn{substatement} is the line after a | |
450 | conditional statement, such as @code{if}, @code{else}, @code{while}, | |
451 | @code{do}, @code{switch}, etc. A @dfn{substatement | |
452 | block} is a brace block following one of these conditional statements.} | |
453 | ||
454 | @cindex comment-only line | |
455 | Syntactic component lists can contain more than one component, and | |
456 | individual syntactic components need not have relative buffer positions. | |
457 | The most common example of this is a line that contains a @dfn{comment | |
458 | only line}. | |
459 | @example | |
460 | @group | |
461 | ||
462 | 1: void draw_list( List<Drawables>& drawables ) | |
463 | 2: @{ | |
464 | 3: // call the virtual draw() method on each element in list | |
465 | 4: for( int i=0; i < drawables.count(), ++i ) | |
466 | 5: @{ | |
467 | 6: drawables[i].draw(); | |
468 | 7: @} | |
469 | 8: @} | |
470 | ||
471 | @end group | |
472 | @end example | |
473 | ||
474 | @noindent | |
475 | Hitting @kbd{C-c C-s} on line 3 of this example gives: | |
476 | @example | |
477 | ||
478 | ((comment-intro) (defun-block-intro . 46)) | |
479 | ||
480 | @end example | |
481 | ||
482 | @noindent | |
483 | and you can see that the syntactic component list contains two syntactic | |
484 | components. Also notice that the first component, | |
485 | @samp{(comment-intro)} has no relative buffer position. | |
486 | ||
487 | ||
488 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
d7bd46ed GM |
489 | @node Indentation Calculation, , Syntactic Analysis, New Indentation Engine |
490 | @comment node-name, next, previous, up | |
491 | @section Indentation Calculation | |
492 | @cindex indentation calculation | |
6bf7aab6 DL |
493 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
494 | ||
6bf7aab6 | 495 | Indentation for a line is calculated using the syntactic |
d7bd46ed | 496 | component list derived in step 1 above (@pxref{Syntactic Analysis}). |
6bf7aab6 DL |
497 | Each component contributes to the final total indentation of the line in |
498 | two ways. | |
499 | ||
500 | First, the syntactic symbols are looked up in the @code{c-offsets-alist} | |
d7bd46ed GM |
501 | style variable, which is an association list of syntactic symbols and |
502 | the offsets to apply for those symbols. These offsets are added to a | |
6bf7aab6 DL |
503 | running total. |
504 | ||
505 | Second, if the component has a relative buffer position, @ccmode{} | |
506 | adds the column number of that position to the running total. By adding | |
507 | up the offsets and columns for every syntactic component on the list, | |
508 | the final total indentation for the current line is computed. | |
509 | ||
510 | Let's use our two code examples above to see how this works. Here is | |
511 | our first example again: | |
512 | @example | |
513 | @group | |
514 | ||
515 | 1: void swap( int& a, int& b ) | |
516 | 2: @{ | |
517 | 3: int tmp = a; | |
518 | 4: a = b; | |
519 | 5: b = tmp; | |
520 | 6: @} | |
521 | ||
522 | @end group | |
523 | @end example | |
524 | ||
6bf7aab6 DL |
525 | Let's say point is on line 3 and we hit the @kbd{TAB} key to re-indent |
526 | the line. Remember that the syntactic component list for that | |
527 | line is: | |
528 | @example | |
529 | ||
530 | ((defun-block-intro . 29)) | |
531 | ||
532 | @end example | |
533 | ||
534 | @noindent | |
535 | @ccmode{} looks up @code{defun-block-intro} in the | |
d7bd46ed GM |
536 | @code{c-offsets-alist} style variable. Let's say it finds the value |
537 | @samp{4}; it adds this to the running total (initialized to zero), | |
538 | yielding a running total indentation of 4 spaces. | |
6bf7aab6 DL |
539 | |
540 | Next @ccmode{} goes to buffer position 29 and asks for the current | |
541 | column. This brace is in column zero, so @ccmode{} | |
542 | adds @samp{0} to the running total. Since there is only one syntactic | |
543 | component on the list for this line, indentation calculation is | |
544 | complete, and the total indentation for the line | |
545 | is 4 spaces. | |
546 | ||
547 | Here's another example: | |
548 | @example | |
549 | @group | |
550 | ||
551 | 1: int add( int val, int incr, int doit ) | |
552 | 2: @{ | |
553 | 3: if( doit ) | |
554 | 4: @{ | |
555 | 5: return( val + incr ); | |
556 | 6: @} | |
557 | 7: return( val ); | |
558 | 8: @} | |
559 | ||
560 | @end group | |
561 | @end example | |
562 | ||
563 | If we were to hit @kbd{TAB} on line 4 in the above example, the same | |
564 | basic process is performed, despite the differences in the syntactic | |
565 | component list. Remember that the list for this line is: | |
566 | @example | |
567 | ||
568 | ((substatement-open . 46)) | |
569 | ||
570 | @end example | |
571 | ||
572 | Here, @ccmode{} first looks up the @code{substatement-open} symbol | |
573 | in @code{c-offsets-alist}. Let's say it finds the value @samp{4}. This | |
574 | yields a running total of 4. @ccmode{} then goes to | |
575 | buffer position 46, which is the @samp{i} in @code{if} on line 3. This | |
576 | character is in the fourth column on that line so adding this to the | |
577 | running total yields an indentation for the line of 8 spaces. | |
578 | ||
579 | Simple, huh? | |
580 | ||
581 | Actually, the mode usually just does The Right Thing without you having | |
582 | to think about it in this much detail. But when customizing | |
583 | indentation, it's helpful to understand the general indentation model | |
584 | being used. | |
585 | ||
586 | @vindex c-echo-syntactic-information-p | |
587 | @vindex echo-syntactic-information-p (c-) | |
6bf7aab6 DL |
588 | As you configure @ccmode{}, you might want to set the variable |
589 | @code{c-echo-syntactic-information-p} to non-@code{nil} so that the | |
590 | syntactic component list and calculated offset will always be echoed in | |
591 | the minibuffer when you hit @kbd{TAB}. | |
592 | ||
593 | ||
594 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
d7bd46ed GM |
595 | @node Minor Modes, Text Filling and Line Breaking, New Indentation Engine, Top |
596 | @comment node-name, next, previous, up | |
597 | @chapter Minor Modes | |
6bf7aab6 DL |
598 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
599 | ||
600 | @ccmode{} contains two minor-mode-like features that you should | |
601 | find useful while you enter new C code. The first is called | |
602 | @dfn{auto-newline} mode, and the second is called @dfn{hungry-delete} | |
603 | mode. These minor modes can be toggled on and off independently, and | |
604 | @ccmode{} can be configured so that it starts up with any | |
605 | combination of these minor modes. By default, both of these minor modes | |
606 | are turned off. | |
607 | ||
608 | The state of the minor modes is always reflected in the minor mode list | |
609 | on the modeline of the @ccmode{} buffer. When auto-newline mode is | |
d7bd46ed GM |
610 | enabled, you will see @samp{C/a} on the mode line @footnote{The @samp{C} |
611 | would be replaced with @samp{C++}, @samp{ObjC}, @samp{Java}, @samp{IDL}, | |
612 | or @samp{Pike} for the respective languages.}. When hungry delete mode | |
613 | is enabled you would see @samp{C/h} and when both modes are enabled, | |
614 | you'd see @samp{C/ah}. | |
6bf7aab6 DL |
615 | |
616 | @kindex C-c C-a | |
617 | @kindex C-c C-d | |
618 | @kindex C-c C-t | |
619 | @findex c-toggle-hungry-state | |
620 | @findex c-toggle-auto-state | |
621 | @findex c-toggle-auto-hungry-state | |
622 | @findex toggle-hungry-state (c-) | |
623 | @findex toggle-auto-state (c-) | |
624 | @findex toggle-auto-hungry-state (c-) | |
47d7776c | 625 | @ccmode{} provides key bindings which allow you to toggle the minor |
6bf7aab6 DL |
626 | modes on the fly while editing code. To toggle just the auto-newline |
627 | state, hit @kbd{C-c C-a} (@code{c-toggle-auto-state}). When you do | |
628 | this, you should see the @samp{a} indicator either appear or disappear | |
629 | on the modeline. Similarly, to toggle just the hungry-delete state, use | |
630 | @kbd{C-c C-d} (@code{c-toggle-hungry-state}), and to toggle both states, | |
631 | use @kbd{C-c C-t} (@code{c-toggle-auto-hungry-state}). | |
632 | ||
633 | To set up the auto-newline and hungry-delete states to your preferred | |
634 | values, you would need to add some lisp to your @file{.emacs} file that | |
635 | called one of the @code{c-toggle-*-state} functions directly. When | |
636 | called programmatically, each function takes a numeric value, where | |
637 | a positive number enables the minor mode, a negative number disables the | |
638 | mode, and zero toggles the current state of the mode. | |
639 | ||
640 | So for example, if you wanted to enable both auto-newline and | |
641 | hungry-delete for all your C file editing, you could add the following | |
642 | to your @file{.emacs} file: | |
643 | @example | |
644 | ||
645 | (add-hook 'c-mode-common-hook | |
43aef553 | 646 | (lambda () (c-toggle-auto-hungry-state 1))) |
6bf7aab6 DL |
647 | |
648 | @end example | |
649 | ||
650 | ||
651 | @cindex electric characters | |
652 | ||
653 | @menu | |
d7bd46ed GM |
654 | * Auto-newline Insertion:: |
655 | * Hungry-deletion of Whitespace:: | |
6bf7aab6 DL |
656 | @end menu |
657 | ||
6bf7aab6 | 658 | |
d7bd46ed GM |
659 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
660 | @node Auto-newline Insertion, Hungry-deletion of Whitespace, , Minor Modes | |
661 | @comment node-name, next, previous, up | |
662 | @section Auto-newline Insertion | |
663 | @cindex auto-newline insertion | |
6bf7aab6 DL |
664 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
665 | ||
666 | @cindex electric commands | |
667 | Auto-newline minor mode works by enabling certain @dfn{electric | |
668 | commands}. Electric commands are typically bound to special characters | |
669 | such as the left and right braces, colons, semi-colons, etc., which when | |
670 | typed, perform some magic formatting in addition to inserting the typed | |
671 | character. As a general rule, electric commands are only electric when | |
672 | the following conditions apply: | |
673 | ||
674 | @itemize @bullet | |
675 | @item | |
676 | Auto-newline minor mode is enabled, as evidenced by a @samp{C/a} or | |
677 | @samp{C/ah} indicator on the modeline. | |
678 | ||
679 | @cindex literal | |
680 | @cindex syntactic whitespace | |
681 | @item | |
682 | The character was not typed inside of a literal @footnote{A | |
683 | @dfn{literal} is defined as any comment, string, or C preprocessor macro | |
684 | definition. These constructs are also known as @dfn{syntactic | |
685 | whitespace} since they are usually ignored when scanning C code.}. | |
686 | ||
687 | @item | |
688 | @kindex C-u | |
689 | No numeric argument was supplied to the command (i.e. it was typed as | |
690 | normal, with no @kbd{C-u} prefix). | |
691 | ||
692 | @end itemize | |
693 | ||
694 | @menu | |
695 | * Hanging Braces:: | |
696 | * Hanging Colons:: | |
d7bd46ed GM |
697 | * Hanging Semi-colons and Commas:: |
698 | * Other Electric Commands:: | |
6bf7aab6 DL |
699 | * Clean-ups:: |
700 | @end menu | |
701 | ||
6bf7aab6 | 702 | |
d7bd46ed GM |
703 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
704 | @node Hanging Braces, Hanging Colons, , Auto-newline Insertion | |
705 | @comment node-name, next, previous, up | |
706 | @subsection Hanging Braces | |
707 | @cindex hanging braces | |
6bf7aab6 DL |
708 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
709 | ||
710 | @findex c-electric-brace | |
711 | @findex electric-brace (c-) | |
712 | @vindex c-hanging-braces-alist | |
713 | @vindex hanging-braces-alist (c-) | |
6bf7aab6 DL |
714 | When you type either an open or close brace (i.e. @kbd{@{} or @kbd{@}}), |
715 | the electric command @code{c-electric-brace} gets run. This command has | |
716 | two electric formatting behaviors. First, it will perform some | |
717 | re-indentation of the line the brace was typed on, and second, it will | |
718 | add various newlines before and/or after the typed brace. | |
719 | Re-indentation occurs automatically whenever the electric behavior is | |
720 | enabled. If the brace ends up on a line other than the one it was typed | |
721 | on, then that line is also re-indented. | |
722 | ||
723 | @cindex class-open syntactic symbol | |
724 | @cindex class-close syntactic symbol | |
725 | @cindex defun-open syntactic symbol | |
726 | @cindex defun-close syntactic symbol | |
727 | @cindex inline-open syntactic symbol | |
728 | @cindex inline-close syntactic symbol | |
729 | @cindex brace-list-open syntactic symbol | |
730 | @cindex brace-list-close syntactic symbol | |
731 | @cindex brace-list-intro syntactic symbol | |
d7bd46ed | 732 | @cindex brace-entry-open syntactic symbol |
6bf7aab6 DL |
733 | @cindex block-open syntactic symbol |
734 | @cindex block-close syntactic symbol | |
735 | @cindex substatement-open syntactic symbol | |
736 | @cindex statement-case-open syntactic symbol | |
737 | @cindex extern-lang-open syntactic symbol | |
738 | @cindex extern-lang-close syntactic symbol | |
d7bd46ed GM |
739 | @cindex namespace-open syntactic symbol |
740 | @cindex namespace-close syntactic symbol | |
741 | @cindex inexpr-class-open symbol | |
742 | @cindex inexpr-class-close symbol | |
743 | ||
744 | The default in auto-newline mode is to insert newlines both before and | |
745 | after a brace, but that can be controlled by the | |
746 | @code{c-hanging-braces-alist} style variable. This variable contains a | |
6bf7aab6 DL |
747 | mapping between syntactic symbols related to braces, and a list of |
748 | places to insert a newline. The syntactic symbols that are useful for | |
749 | this list are: @code{class-open}, @code{class-close}, @code{defun-open}, | |
750 | @code{defun-close}, @code{inline-open}, @code{inline-close}, | |
751 | @code{brace-list-open}, @code{brace-list-close}, | |
d7bd46ed GM |
752 | @code{brace-list-intro}, @code{brace-entry-open}, @code{block-open}, |
753 | @code{block-close}, @code{substatement-open}, | |
754 | @code{statement-case-open}, @code{extern-lang-open}, | |
755 | @code{extern-lang-close}, @code{namespace-open}, @code{namespace-close}, | |
756 | @code{inexpr-class-open}, and @code{inexpr-class-close}@footnote{Note | |
757 | that the aggregate constructs in Pike mode, @samp{(@{}, @samp{@})}, | |
758 | @samp{([}, @samp{])}, and @samp{(<}, @samp{>)}, do not count as brace | |
759 | lists in this regard, even though they do for normal indentation | |
760 | purposes. It's currently not possible to set automatic newlines on | |
761 | these constructs.}. @xref{Syntactic Symbols}, for a more detailed | |
762 | description of these syntactic symbols, except for | |
763 | @code{inexpr-class-open} and @code{inexpr-class-close}, which aren't | |
764 | actual syntactic symbols. | |
765 | ||
766 | The braces of anonymous inner classes in Java are given the special | |
767 | symbols @code{inexpr-class-open} and @code{inexpr-class-close}, so that | |
768 | they can be distinguished from the braces of normal classes@footnote{The | |
769 | braces of anonymous classes produces a combination of | |
770 | @code{inexpr-class}, and @code{class-open} or @code{class-close} in | |
771 | normal indentation analysis.}. | |
772 | ||
6bf7aab6 DL |
773 | The value associated with each syntactic symbol in this association list |
774 | is called an @var{ACTION} which can be either a function or a list. | |
393759c7 | 775 | @xref{Custom Brace and Colon Hanging}, for a more detailed discussion of |
6bf7aab6 DL |
776 | using a function as a brace hanging @var{ACTION}. |
777 | ||
778 | When the @var{ACTION} is a list, it can contain any combination of the | |
779 | symbols @code{before} and @code{after}, directing @ccmode{} where to | |
780 | put newlines in relationship to the brace being inserted. Thus, if the | |
781 | list contains only the symbol @code{after}, then the brace is said to | |
782 | @dfn{hang} on the right side of the line, as in: | |
783 | @example | |
784 | @group | |
785 | ||
786 | // here, open braces always `hang' | |
787 | void spam( int i ) @{ | |
788 | if( i == 7 ) @{ | |
789 | dosomething(i); | |
790 | @} | |
791 | @} | |
792 | ||
793 | ||
794 | @end group | |
795 | @end example | |
796 | ||
797 | When the list contains both @code{after} and @code{before}, the braces | |
798 | will appear on a line by themselves, as shown by the close braces in the | |
799 | above example. The list can also be empty, in which case no newlines | |
800 | are added either before or after the brace. | |
801 | ||
d7bd46ed GM |
802 | If a syntactic symbol is missing entirely from |
803 | @code{c-hanging-braces-alist}, it's treated in the same way as an | |
804 | @var{ACTION} with a list containing @code{before} and @code{after}, so | |
805 | that braces by default end up on their own line. | |
806 | ||
6bf7aab6 DL |
807 | For example, the default value of @code{c-hanging-braces-alist} is: |
808 | @example | |
809 | @group | |
810 | ||
d7bd46ed GM |
811 | ((brace-list-open) |
812 | (brace-entry-open) | |
813 | (substatement-open after) | |
814 | (block-close . c-snug-do-while) | |
815 | (extern-lang-open after) | |
816 | (inexpr-class-open after) | |
817 | (inexpr-class-close before)) | |
6bf7aab6 DL |
818 | |
819 | @end group | |
820 | @end example | |
821 | ||
d7bd46ed GM |
822 | @noindent which says that @code{brace-list-open} and |
823 | @code{brace-entry-open} braces should both hang on the right side, and | |
824 | allow subsequent text to follow on the same line as the brace. Also, | |
825 | @code{substatement-open}, @code{extern-lang-open}, and | |
826 | @code{inexpr-class-open} braces should hang on the right side, but | |
827 | subsequent text should follow on the next line. The opposite holds for | |
828 | @code{inexpr-class-close} braces; they won't hang, but the following | |
829 | text continues on the same line. Here, in the @code{block-close} entry, | |
830 | you also see an example of using a function as an @var{ACTION}. In all | |
831 | other cases, braces are put on a line by themselves. | |
6bf7aab6 DL |
832 | |
833 | A word of caution: it is not a good idea to hang top-level construct | |
834 | introducing braces, such as @code{class-open} or @code{defun-open}. | |
835 | Emacs makes an assumption that such braces will always appear in column | |
d7bd46ed | 836 | zero, hanging them can introduce performance problems. |
393759c7 | 837 | @xref{Performance Issues}, for more information. |
6bf7aab6 DL |
838 | |
839 | ||
840 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
d7bd46ed GM |
841 | @node Hanging Colons, Hanging Semi-colons and Commas, Hanging Braces, Auto-newline Insertion |
842 | @comment node-name, next, previous, up | |
843 | @subsection Hanging Colons | |
844 | @cindex hanging colons | |
6bf7aab6 DL |
845 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
846 | ||
847 | @vindex hanging-colons-alist (c-) | |
848 | @vindex c-hanging-colons-alist | |
d7bd46ed GM |
849 | Using a mechanism similar to brace hanging (@pxref{Hanging Braces}), |
850 | colons can also be made to hang using the style variable | |
6bf7aab6 | 851 | @code{c-hanging-colons-alist}. The syntactic symbols appropriate for |
cb7f2e96 | 852 | this association list are: @code{case-label}, @code{label}, |
6bf7aab6 DL |
853 | @code{access-label}, @code{member-init-intro}, and @code{inher-intro}. |
854 | Note however that for @code{c-hanging-colons-alist}, @var{ACTION}s as | |
855 | functions are not supported. See also @ref{Custom Brace and Colon | |
856 | Hanging} for details. | |
857 | ||
6bf7aab6 DL |
858 | In C++, double-colons are used as a scope operator but because these |
859 | colons always appear right next to each other, newlines before and after | |
860 | them are controlled by a different mechanism, called @dfn{clean-ups} in | |
393759c7 | 861 | @ccmode{}. @xref{Clean-ups}, for details. |
6bf7aab6 DL |
862 | |
863 | ||
864 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
d7bd46ed GM |
865 | @node Hanging Semi-colons and Commas, Other Electric Commands, Hanging Colons, Auto-newline Insertion |
866 | @comment node-name, next, previous, up | |
867 | @subsection Hanging Semi-colons and Commas | |
868 | @cindex hanging semi-colons | |
869 | @cindex hanging commas | |
6bf7aab6 DL |
870 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
871 | ||
872 | Semicolons and commas are also electric in @ccmode{}, but since | |
873 | these characters do not correspond directly to syntactic symbols, a | |
874 | different mechanism is used to determine whether newlines should be | |
875 | automatically inserted after these characters. @xref{Customizing | |
393759c7 | 876 | Semi-colons and Commas}, for details. |
6bf7aab6 DL |
877 | |
878 | ||
879 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
d7bd46ed GM |
880 | @node Other Electric Commands, Clean-ups, Hanging Semi-colons and Commas, Auto-newline Insertion |
881 | @comment node-name, next, previous, up | |
882 | @subsection Other Electric Commands | |
6bf7aab6 DL |
883 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
884 | ||
885 | @kindex # | |
886 | @findex c-electric-pound | |
887 | @vindex c-electric-pound-behavior | |
888 | @findex electric-pound (c-) | |
889 | @vindex electric-pound-behavior (c-) | |
6bf7aab6 DL |
890 | A few other keys also provide electric behavior. For example |
891 | @kbd{#} (@code{c-electric-pound}) is electric when typed as | |
892 | the first non-whitespace character on a line. In this case, the | |
893 | variable @code{c-electric-pound-behavior} is consulted for the electric | |
894 | behavior. This variable takes a list value, although the only element | |
895 | currently defined is @code{alignleft}, which tells this command to force | |
896 | the @samp{#} character into column zero. This is useful for entering | |
897 | C preprocessor macro definitions. | |
898 | ||
899 | @findex c-electric-star | |
900 | @findex c-electric-slash | |
901 | @findex electric-star (c-) | |
902 | @findex electric-slash (c-) | |
6bf7aab6 DL |
903 | Stars and slashes (i.e. @kbd{*} and @kbd{/}, @code{c-electric-star} and |
904 | @code{c-electric-slash} respectively) are also electric under | |
905 | certain circumstances. If a star is inserted as the second character of | |
d7bd46ed | 906 | a C style block comment on a comment-only line, then the comment |
6bf7aab6 DL |
907 | delimiter is indented as defined by @code{c-offsets-alist}. A |
908 | comment-only line is defined as a line which contains only a comment, as | |
909 | in: | |
910 | @example | |
911 | @group | |
912 | ||
913 | void spam( int i ) | |
914 | @{ | |
915 | // this is a comment-only line... | |
916 | if( i == 7 ) // but this is not | |
917 | @{ | |
918 | dosomething(i); | |
919 | @} | |
920 | @} | |
921 | ||
922 | @end group | |
923 | @end example | |
924 | ||
925 | Likewise, if a slash is inserted as the second slash in a C++ style line | |
926 | comment (also only on a comment-only line), then the line is indented as | |
927 | defined by @code{c-offsets-alist}. | |
928 | ||
929 | @findex c-electric-lt-gt | |
930 | @findex electric-lt-gt (c-) | |
931 | @kindex < | |
932 | @kindex > | |
933 | Less-than and greater-than signs (@code{c-electric-lt-gt}) are also | |
934 | electric, but only in C++ mode. Hitting the second of two @kbd{<} or | |
935 | @kbd{>} keys re-indents the line if it is a C++ style stream operator. | |
936 | ||
d7bd46ed GM |
937 | @findex c-electric-paren |
938 | @findex electric-paren (c-) | |
939 | @kindex ( | |
940 | @kindex ) | |
941 | The normal parenthesis characters @samp{(} and @samp{)} also reindent | |
942 | the current line if they are used in normal code. This is useful for | |
943 | getting the closing parenthesis of an argument list aligned | |
944 | automatically. | |
6bf7aab6 | 945 | |
6bf7aab6 | 946 | |
d7bd46ed GM |
947 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
948 | @node Clean-ups, , Other Electric Commands, Auto-newline Insertion | |
949 | @comment node-name, next, previous, up | |
950 | @subsection Clean-ups | |
951 | @cindex clean-ups | |
6bf7aab6 DL |
952 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
953 | ||
cb7f2e96 GM |
954 | @dfn{Clean-ups} are mechanisms complementary to colon and brace hanging. |
955 | On the surface, it would seem that clean-ups overlap the functionality | |
956 | provided by the @code{c-hanging-*-alist} variables. Clean-ups are | |
94cae5a8 | 957 | however used to adjust code ``after-the-fact,'' i.e. to adjust the |
cb7f2e96 GM |
958 | whitespace in constructs after they are typed. |
959 | ||
960 | Most of the clean-ups are only applicable to counteract automatically | |
961 | inserted newlines, and will therefore only have any effect if the | |
962 | auto-newline minor mode is turned on. Others will work all the time. | |
6bf7aab6 | 963 | |
d7bd46ed GM |
964 | @vindex c-cleanup-list |
965 | @vindex cleanup-list (c-) | |
6bf7aab6 | 966 | @cindex literal |
d7bd46ed | 967 | You can configure @ccmode{}'s clean-ups by setting the style variable |
6bf7aab6 | 968 | @code{c-cleanup-list}, which is a list of clean-up symbols. By default, |
d7bd46ed GM |
969 | @ccmode{} cleans up only the @code{scope-operator} construct, which is |
970 | necessary for proper C++ support. Note that clean-ups are only | |
971 | performed when the construct does not occur within a literal | |
972 | (@pxref{Auto-newline Insertion}), and when there is nothing but | |
973 | whitespace appearing between the individual components of the construct. | |
6bf7aab6 | 974 | |
cb7f2e96 GM |
975 | These are the clean-ups that only are active in the auto-newline minor |
976 | mode: | |
6bf7aab6 DL |
977 | |
978 | @itemize @bullet | |
979 | @item | |
cb7f2e96 | 980 | @code{brace-else-brace} --- Clean up @samp{@} else @{} constructs by |
6bf7aab6 DL |
981 | placing the entire construct on a single line. Clean-up occurs when the |
982 | open brace after the @samp{else} is typed. So for example, this: | |
983 | @example | |
984 | @group | |
985 | ||
986 | void spam(int i) | |
987 | @{ | |
988 | if( i==7 ) | |
989 | @{ | |
990 | dosomething(); | |
991 | @} | |
992 | else | |
993 | @{ | |
994 | ||
995 | @end group | |
996 | @end example | |
997 | @noindent | |
998 | appears like this after the open brace is typed: | |
999 | @example | |
1000 | @group | |
1001 | ||
1002 | void spam(int i) | |
1003 | @{ | |
1004 | if( i==7 ) @{ | |
1005 | dosomething(); | |
1006 | @} else @{ | |
1007 | ||
1008 | @end group | |
1009 | @end example | |
1010 | ||
1011 | @item | |
cb7f2e96 | 1012 | @code{brace-elseif-brace} --- Similar to the @code{brace-else-brace} |
6bf7aab6 DL |
1013 | clean-up, but this cleans up @samp{@} else if (...) @{} constructs. For |
1014 | example: | |
1015 | @example | |
1016 | @group | |
1017 | ||
1018 | void spam(int i) | |
1019 | @{ | |
1020 | if( i==7 ) | |
1021 | @{ | |
1022 | dosomething(); | |
1023 | @} | |
d7bd46ed GM |
1024 | else if( i==3 ) |
1025 | @{ | |
6bf7aab6 DL |
1026 | |
1027 | @end group | |
1028 | @end example | |
1029 | @noindent | |
d7bd46ed GM |
1030 | appears like this after the open parenthesis is typed: |
1031 | @example | |
1032 | @group | |
1033 | ||
1034 | void spam(int i) | |
1035 | @{ | |
1036 | if( i==7 ) @{ | |
1037 | dosomething(); | |
1038 | @} else if( i==3 ) | |
1039 | @{ | |
1040 | ||
1041 | @end group | |
1042 | @end example | |
1043 | @noindent | |
1044 | and like this after the open brace is typed: | |
6bf7aab6 DL |
1045 | @example |
1046 | @group | |
1047 | ||
1048 | void spam(int i) | |
1049 | @{ | |
1050 | if( i==7 ) @{ | |
1051 | dosomething(); | |
1052 | @} else if( i==3 ) @{ | |
1053 | ||
1054 | @end group | |
1055 | @end example | |
1056 | ||
d7bd46ed | 1057 | @item |
cb7f2e96 | 1058 | @code{brace-catch-brace} --- Analogous to @code{brace-elseif-brace}, but |
d7bd46ed GM |
1059 | cleans up @samp{@} catch (...) @{} in C++ and Java mode. |
1060 | ||
6bf7aab6 | 1061 | @item |
cb7f2e96 | 1062 | @code{empty-defun-braces} --- Clean up braces following a top-level |
6bf7aab6 DL |
1063 | function or class definition that contains no body. Clean up occurs |
1064 | when the closing brace is typed. Thus the following: | |
1065 | @example | |
1066 | @group | |
1067 | ||
1068 | class Spam | |
1069 | @{ | |
1070 | @} | |
1071 | ||
1072 | @end group | |
1073 | @end example | |
1074 | @noindent | |
1075 | is transformed into this when the close brace is typed: | |
1076 | @example | |
1077 | @group | |
1078 | ||
1079 | class Spam | |
1080 | @{@} | |
1081 | ||
1082 | @end group | |
1083 | @end example | |
1084 | ||
1085 | @item | |
cb7f2e96 | 1086 | @code{defun-close-semi} --- Clean up the terminating semi-colon on |
6bf7aab6 | 1087 | top-level function or class definitions when they follow a close |
cb7f2e96 | 1088 | brace. Clean up occurs when the semi-colon is typed. |
6bf7aab6 DL |
1089 | So for example, the following: |
1090 | @example | |
1091 | @group | |
1092 | ||
1093 | class Spam | |
1094 | @{ | |
1095 | @} | |
1096 | ; | |
1097 | ||
1098 | @end group | |
1099 | @end example | |
1100 | @noindent | |
1101 | is transformed into this when the semi-colon is typed: | |
1102 | ||
1103 | @example | |
1104 | @group | |
1105 | ||
1106 | class Spam | |
1107 | @{ | |
1108 | @}; | |
1109 | ||
1110 | @end group | |
1111 | @end example | |
1112 | ||
1113 | @item | |
cb7f2e96 | 1114 | @code{list-close-comma} --- Clean up commas following braces in array |
6bf7aab6 DL |
1115 | and aggregate initializers. Clean up occurs when the comma is typed. |
1116 | ||
1117 | @item | |
cb7f2e96 | 1118 | @code{scope-operator} --- Clean up double colons which may designate a |
6bf7aab6 DL |
1119 | C++ scope operator split across multiple lines@footnote{Certain C++ |
1120 | constructs introduce ambiguous situations, so @code{scope-operator} | |
1121 | clean-ups may not always be correct. This usually only occurs when | |
1122 | scoped identifiers appear in switch label tags.}. Clean up occurs when | |
1123 | the second colon is typed. You will always want @code{scope-operator} | |
1124 | in the @code{c-cleanup-list} when you are editing C++ code. | |
1125 | ||
1126 | @end itemize | |
1127 | ||
cb7f2e96 GM |
1128 | The following clean-ups are always active when they occur on |
1129 | @code{c-cleanup-list}, and are thus not affected by the auto-newline | |
1130 | minor mode: | |
1131 | ||
1132 | @itemize @bullet | |
1133 | @item | |
1134 | @code{space-before-funcall} --- Insert a space between the function name | |
1135 | and the opening parenthesis of a function call. This produces function | |
1136 | calls in the style mandated by the GNU coding standards, | |
1137 | e.g. @samp{signal (SIGINT, SIG_IGN)} and @samp{abort ()}. Clean up | |
1138 | occurs when the opening parenthesis is typed. | |
1139 | ||
1140 | @item | |
1141 | @code{compact-empty-funcall} --- Clean up any space between the function | |
1142 | name and the opening parenthesis of a function call that have no | |
1143 | arguments. This is typically used together with | |
1144 | @code{space-before-funcall} if you prefer the GNU function call style | |
1145 | for functions with arguments but think it looks ugly when it's only an | |
1146 | empty parenthesis pair. I.e. you will get @samp{signal (SIGINT, | |
1147 | SIG_IGN)}, but @samp{abort()}. Clean up occurs when the closing | |
1148 | parenthesis is typed. | |
1149 | ||
1150 | @end itemize | |
1151 | ||
6bf7aab6 DL |
1152 | |
1153 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
d7bd46ed GM |
1154 | @node Hungry-deletion of Whitespace, , Auto-newline Insertion, Minor Modes |
1155 | @comment node-name, next, previous, up | |
1156 | @section Hungry-deletion of Whitespace | |
1157 | @cindex hungry-deletion of whitespace | |
6bf7aab6 DL |
1158 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
1159 | ||
1160 | Hungry deletion of whitespace, or as it more commonly called, | |
1161 | @dfn{hungry-delete mode}, is a simple feature that some people find | |
1162 | extremely useful. In fact, you might find yourself wanting | |
1163 | hungry-delete in @strong{all} your editing modes! | |
1164 | ||
1165 | @kindex DEL | |
1166 | @kindex Backspace | |
1167 | In a nutshell, when hungry-delete mode is enabled, hitting the | |
1168 | @key{Backspace} key@footnote{I say ``hit the @key{Backspace} key'' but | |
1169 | what I really mean is ``when Emacs receives the @code{BackSpace} key | |
94cae5a8 | 1170 | event.'' The difference usually isn't significant to most users, but |
6bf7aab6 DL |
1171 | advanced users will realize that under window systems such as X, any |
1172 | physical key (keycap) on the keyboard can be configured to generate any | |
1173 | keysym, and thus any Emacs key event. Also, the use of Emacs on TTYs | |
1174 | will affect which keycap generates which key event. From a pedantic | |
1175 | point of view, here we are only concerned with the key event that | |
1176 | Emacs receives.} will consume all preceding whitespace, including | |
1177 | newlines and tabs. This can really cut down on the number of | |
1178 | @key{Backspace}'s you have to type if, for example you made a mistake on | |
1179 | the preceding line. | |
1180 | ||
1181 | @findex c-electric-backspace | |
1182 | @findex electric-backspace (c-) | |
1183 | @vindex c-backspace-function | |
1184 | @vindex backspace-function (c-) | |
1185 | ||
1186 | @findex c-electric-delete | |
1187 | @findex electric-delete (c-) | |
1188 | @vindex c-delete-function | |
1189 | @vindex delete-function (c-) | |
1190 | @cindex literal | |
1191 | ||
1192 | @findex backward-delete-char-untabify | |
1193 | ||
d7bd46ed GM |
1194 | By default, when you hit the @key{Backspace} key @ccmode{} runs the |
1195 | command @code{c-electric-backspace}, which deletes text in the backwards | |
1196 | direction. When deleting a single character, or when @key{Backspace} is | |
1197 | hit in a literal (@pxref{Auto-newline Insertion}), or when hungry-delete | |
1198 | mode is disabled, the function contained in the | |
1199 | @code{c-backspace-function} variable is called with one argument (the | |
1200 | number of characters to delete). This variable is set to | |
6bf7aab6 DL |
1201 | @code{backward-delete-char-untabify} by default. |
1202 | ||
1203 | @vindex delete-key-deletes-forward | |
1204 | @findex delete-char | |
1205 | ||
d7bd46ed GM |
1206 | The default behavior of the @key{Delete} key depends on the flavor of |
1207 | Emacs you are using. By default in XEmacs 20.3 and beyond, the | |
1208 | @key{Delete} key is bound to @code{c-electric-delete}. You control the | |
1209 | direction that the @key{Delete} key deletes by setting the variable | |
1210 | @code{delete-key-deletes-forward}, a standard XEmacs variable. When | |
1211 | this variable is non-@code{nil} and hungry-delete mode is enabled, | |
1212 | @code{c-electric-delete} will consume all whitespace @emph{following} | |
1213 | point. When @code{delete-key-deletes-forward} is @code{nil}, it deletes | |
1214 | all whitespace @emph{preceding} point@footnote{i.e. it literally calls | |
1215 | @code{c-electric-backspace}.} When deleting a single character, or if | |
1216 | @key{Delete} is hit in a literal, or hungry-delete mode is disabled, the | |
1217 | function contained in @code{c-delete-function} is called with one | |
1218 | argument: the number of characters to delete. This variable is set to | |
1219 | @code{delete-char} by default. | |
1220 | ||
1221 | In Emacs 19 or Emacs 20, both the @key{Delete} and @key{Backspace} keys | |
1222 | are bound to @code{c-electric-backspace}, however you can change this by | |
1223 | explicitly binding @code{[delete]}@footnote{E.g. to | |
1224 | @code{c-electric-delete} in your @file{.emacs} file. Note however, that | |
1225 | Emacs 20 does not have a standard variable such as | |
1226 | @code{delete-key-deletes-forward}.}. | |
1227 | ||
1228 | XEmacsen older than 20.3 behave similar to Emacs 19 and Emacs 20. | |
6bf7aab6 DL |
1229 | |
1230 | ||
1231 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
d7bd46ed GM |
1232 | @node Text Filling and Line Breaking, Commands, Minor Modes, Top |
1233 | @comment node-name, next, previous, up | |
1234 | @chapter Text Filling and Line Breaking | |
6bf7aab6 DL |
1235 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
1236 | ||
d7bd46ed GM |
1237 | Since there's a lot of normal text in comments and string literals, |
1238 | @ccmode{} provides features to edit these like in text mode. The goal | |
1239 | is to do it as seamlessly as possible, i.e. you can use auto fill mode, | |
1240 | sentence and paragraph movement, paragraph filling, adaptive filling etc | |
1241 | wherever there's a piece of normal text without having to think much | |
1242 | about it. @ccmode{} should keep the indentation, fix the comment line | |
1243 | decorations, and so on, for you. It does that by hooking in on the | |
1244 | different line breaking functions and tuning relevant variables as | |
1245 | necessary. | |
1246 | ||
1247 | @vindex c-comment-prefix-regexp | |
1248 | @vindex comment-prefix-regexp (c-) | |
1249 | @cindex comment line prefix | |
1250 | @vindex comment-start | |
1251 | @vindex comment-end | |
1252 | @vindex comment-start-skip | |
1253 | @vindex paragraph-start | |
1254 | @vindex paragraph-separate | |
1255 | @vindex paragraph-ignore-fill-prefix | |
1256 | @vindex adaptive-fill-mode | |
1257 | @vindex adaptive-fill-regexp | |
1258 | @vindex adaptive-fill-first-line-regexp | |
1259 | To make Emacs recognize comments and treat text in them as normal | |
1260 | paragraphs, @ccmode{} makes several standard | |
1261 | variables@footnote{@code{comment-start}, @code{comment-end}, | |
1262 | @code{comment-start-skip}, @code{paragraph-start}, | |
1263 | @code{paragraph-separate}, @code{paragraph-ignore-fill-prefix}, | |
1264 | @code{adaptive-fill-mode}, @code{adaptive-fill-regexp}, and | |
1265 | @code{adaptive-fill-first-line-regexp}.} buffer local and modifies them | |
1266 | according to the language syntax and the style of line decoration that | |
1267 | starts every line in a comment. The style variable | |
1268 | @code{c-comment-prefix-regexp} contains the regexp used to recognize | |
1269 | this @dfn{comment line prefix}. The default is @samp{//+\\|\\**}, which | |
1270 | matches C++ style line comments like | |
1271 | @example | |
1272 | ||
1273 | // blah blah | |
1274 | ||
1275 | @end example | |
1276 | ||
1277 | @noindent | |
1278 | with two or more slashes in front of them, and C style block comments | |
1279 | like | |
1280 | @example | |
1281 | @group | |
1282 | ||
1283 | /* | |
1284 | * blah blah | |
1285 | */ | |
1286 | ||
1287 | @end group | |
1288 | @end example | |
1289 | ||
1290 | @noindent | |
1291 | with zero or more stars at the beginning of every line. If you change | |
1292 | that variable, please make sure it still matches the comment starter | |
1293 | (i.e. @code{//}) of line comments @emph{and} the line prefix inside | |
1294 | block comments. Also note that since @ccmode{} uses the value of | |
1295 | @code{c-comment-prefix-regexp} to set up several other variables at mode | |
1296 | initialization, you need to reinitialize the program mode if you change | |
1297 | it inside a @ccmode{} buffer. | |
1298 | ||
1299 | @findex auto-fill-mode | |
1300 | @cindex auto fill mode | |
1301 | @cindex paragraph fill | |
1302 | Line breaks are by default handled (almost) the same regardless whether | |
1303 | they are made by auto fill mode (@pxref{Auto Fill,,, emacs, The Emacs | |
1304 | Editor}), paragraph filling (e.g. with @kbd{M-q}), or explicitly with | |
1305 | @kbd{M-j} or similar methods. In string literals, the new line gets the | |
1306 | same indentation as the previous nonempty line (may be changed with the | |
1307 | @code{string} syntactic symbol). In comments, @ccmode{} uses | |
1308 | @code{c-comment-prefix-regexp} to adapt the line prefix from the other | |
1309 | lines in the comment. | |
1310 | ||
1311 | @vindex adaptive-fill-mode | |
1312 | @cindex adaptive fill mode | |
1313 | @ccmode{} uses adaptive fill mode (@pxref{Adaptive Fill,,, emacs, The | |
1314 | Emacs Editor}) to make Emacs correctly keep the line prefix when filling | |
1315 | paragraphs. That also makes Emacs preserve the text indentation | |
1316 | @emph{inside} the comment line prefix. E.g. in the following comment, | |
1317 | both paragraphs will be filled with the left margins kept intact: | |
1318 | @example | |
1319 | @group | |
1320 | ||
1321 | /* Make a balanced b-tree of the nodes in the incoming | |
1322 | * stream. But, to quote the famous words of Donald E. | |
1323 | * Knuth, | |
1324 | * | |
1325 | * Beware of bugs in the above code; I have only | |
1326 | * proved it correct, not tried it. | |
1327 | */ | |
1328 | ||
1329 | @end group | |
1330 | @end example | |
1331 | ||
1332 | @findex c-setup-filladapt | |
1333 | @findex setup-filladapt (c-) | |
1334 | @findex filladapt-mode | |
1335 | @vindex filladapt-mode | |
1336 | @cindex Filladapt mode | |
1337 | It's also possible to use other adaptive filling packages, notably Kyle | |
1338 | E. Jones' Filladapt package@footnote{It's available from | |
1339 | @uref{http://www.wonderworks.com/}. As of version 2.12, it does however | |
1340 | lack a feature that makes it work suboptimally when | |
1341 | @code{c-comment-prefix-regexp} matches the empty string (which it does | |
1342 | by default). A patch for that is available from | |
f214c025 | 1343 | @uref{http://cc-mode.sourceforge.net/,, the CC Mode site}.}, |
d7bd46ed GM |
1344 | which handles things like bulleted lists nicely. There's a convenience |
1345 | function @code{c-setup-filladapt} that tunes the relevant variables in | |
1346 | Filladapt for use in @ccmode{}. Call it from a mode hook, e.g. with | |
1347 | something like this in your @file{.emacs}: | |
1348 | @example | |
1349 | @group | |
1350 | ||
1351 | (defun my-c-mode-common-hook () | |
1352 | (c-setup-filladapt) | |
1353 | (filladapt-mode 1)) | |
1354 | (add-hook 'c-mode-common-hook 'my-c-mode-common-hook) | |
1355 | ||
1356 | @end group | |
1357 | @end example | |
6bf7aab6 | 1358 | |
d7bd46ed GM |
1359 | @vindex c-block-comment-prefix |
1360 | @vindex block-comment-prefix (c-) | |
6bf7aab6 DL |
1361 | @vindex c-comment-continuation-stars |
1362 | @vindex comment-continuation-stars (c-) | |
d7bd46ed GM |
1363 | Normally the comment line prefix inserted for a new line inside a |
1364 | comment is deduced from other lines in it. However there's one | |
1365 | situation when there's no clue about how the prefix should look, namely | |
1366 | when a block comment is broken for the first time. The string in the | |
1367 | style variable @code{c-block-comment-prefix}@footnote{In versions before | |
1368 | 5.26, this variable was called @code{c-comment-continuation-stars}. As | |
1369 | a compatibility measure, @ccmode{} still uses the value on that variable | |
1370 | if it's set.} is used in that case. It defaults to @samp{* }, which | |
1371 | makes a comment | |
1372 | @example | |
6bf7aab6 | 1373 | |
d7bd46ed | 1374 | /* Got O(n^2) here, which is a Bad Thing. */ |
6bf7aab6 | 1375 | |
d7bd46ed | 1376 | @end example |
6bf7aab6 | 1377 | |
d7bd46ed GM |
1378 | @noindent |
1379 | break into | |
1380 | @example | |
1381 | @group | |
1382 | ||
1383 | /* Got O(n^2) here, | |
1384 | * which is a Bad Thing. */ | |
1385 | ||
1386 | @end group | |
1387 | @end example | |
1388 | ||
1389 | Note that it won't work to justify the indentation by putting leading | |
1390 | spaces in the @code{c-block-comment-prefix} string, since @ccmode{} | |
1391 | still uses the normal indentation engine to indent the line. Thus, the | |
1392 | right way to fix the indentation is by setting the @code{c} syntactic | |
1393 | symbol. It defaults to @code{c-lineup-C-comments}, which handles the | |
1394 | indentation of most common comment styles, see @ref{Indentation | |
1395 | Functions}. | |
1396 | ||
1397 | @vindex c-ignore-auto-fill | |
1398 | @vindex ignore-auto-fill (c-) | |
1399 | When auto fill mode is enabled, @ccmode{} can selectively ignore it | |
1400 | depending on the context the line break would occur in, e.g. to never | |
1401 | break a line automatically inside a string literal. This behavior can | |
1402 | be controlled with the @code{c-ignore-auto-fill} variable. It takes a | |
1403 | list of symbols for the different contexts where auto-filling never | |
1404 | should occur: | |
1405 | ||
1406 | @itemize @bullet | |
1407 | @item @code{string} --- Inside a string or character literal. | |
1408 | @item @code{c} --- Inside a C style block comment. | |
1409 | @item @code{c++} --- Inside a C++ style line comment. | |
1410 | @item @code{cpp} --- Inside a preprocessor directive. | |
1411 | @item @code{code} --- Anywhere else, i.e. in normal code. | |
1412 | @end itemize | |
1413 | ||
1414 | By default, @code{c-ignore-auto-fill} is set to @code{'(string cpp | |
1415 | code)}, which means that auto-filling only occurs in comments when | |
1416 | auto-fill mode is activated. In literals, it's often desirable to have | |
1417 | explicit control over newlines. In preprocessor directives, the | |
1418 | necessary @samp{\} escape character before the newline is not | |
1419 | automatically inserted, so an automatic line break would produce invalid | |
1420 | code. In normal code, line breaks are normally dictated by some logical | |
1421 | structure in the code rather than the last whitespace character, so | |
1422 | automatic line breaks there will produce poor results in the current | |
1423 | implementation. | |
1424 | ||
1425 | The commands that does the actual work follows. | |
1426 | ||
1427 | @table @asis | |
1428 | ||
1429 | @kindex M-q | |
1430 | @findex c-fill-paragraph | |
1431 | @findex fill-paragraph (c-) | |
1432 | @cindex Javadoc markup | |
cb7f2e96 | 1433 | @cindex Pike autodoc markup |
d7bd46ed GM |
1434 | @item @kbd{M-q} (@code{c-fill-paragraph}) |
1435 | This is the replacement for @code{fill-paragraph} in @ccmode{} | |
1436 | buffers. It's used to fill multiline string literals and both block and | |
1437 | line style comments. In Java buffers, the Javadoc markup words are | |
cb7f2e96 GM |
1438 | recognized as paragraph starters. The line oriented Pike autodoc markup |
1439 | words are recognized in the same way in Pike mode. | |
d7bd46ed GM |
1440 | |
1441 | The function keeps the comment starters and enders of block comments as | |
1442 | they were before the filling. This means that a comment ender on the | |
1443 | same line as the paragraph being filled will be filled with the | |
1444 | paragraph, and one on a line by itself will stay as it is. The comment | |
1445 | starter is handled similarly@footnote{This means that the variables | |
1446 | @code{c-hanging-comment-starter-p} and @code{c-hanging-comment-ender-p}, | |
1447 | which controlled this behavior in earlier versions of @ccmode{}, are now | |
1448 | obsolete.}. | |
1449 | ||
1450 | @kindex M-j | |
1451 | @findex c-indent-new-comment-line | |
1452 | @findex indent-new-comment-line (c-) | |
1453 | @item @kbd{M-j} (@code{c-indent-new-comment-line}) | |
1454 | This is the replacement for @code{indent-new-comment-line}. It breaks | |
1455 | the line at point and indents the new line like the current one. | |
1456 | ||
1457 | @vindex comment-multi-line | |
1458 | If inside a comment and @code{comment-multi-line} is non-@code{nil}, the | |
1459 | indentation and line prefix are preserved. If inside a comment and | |
1460 | @code{comment-multi-line} is @code{nil}, a new comment of the same type | |
1461 | is started on the next line and indented as appropriate for comments. | |
1462 | ||
1463 | @findex c-context-line-break | |
1464 | @findex context-line-break (c-) | |
1465 | @item @kbd{M-x c-context-line-break} | |
1466 | This is a function that works like @code{indent-new-comment-line} in | |
1467 | comments and @code{newline-and-indent} elsewhere, thus combining those | |
1468 | two in a way that uses each one in the context it's best suited for. | |
1469 | I.e. in comments the comment line prefix and indentation is kept for the | |
1470 | new line, and in normal code it's indented according to context by the | |
1471 | indentation engine. | |
1472 | ||
1473 | It's not bound to a key by default, but it's intended to be used on the | |
1474 | @kbd{RET} key. If you like the behavior of @code{newline-and-indent} on | |
1475 | @kbd{RET}, you might consider switching to this function. | |
1476 | ||
1477 | @end table | |
6bf7aab6 | 1478 | |
d7bd46ed GM |
1479 | |
1480 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
1481 | @node Commands, Customizing Indentation, Text Filling and Line Breaking, Top | |
1482 | @comment node-name, next, previous, up | |
1483 | @chapter Commands | |
6bf7aab6 DL |
1484 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
1485 | ||
1486 | @menu | |
1487 | * Indentation Commands:: | |
d7bd46ed | 1488 | * Movement Commands:: |
6bf7aab6 DL |
1489 | * Other Commands:: |
1490 | @end menu | |
1491 | ||
d7bd46ed GM |
1492 | See also @ref{Text Filling and Line Breaking}, for commands concerning |
1493 | that bit. | |
6bf7aab6 | 1494 | |
6bf7aab6 | 1495 | |
d7bd46ed GM |
1496 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
1497 | @node Indentation Commands, Movement Commands, , Commands | |
1498 | @comment node-name, next, previous,up | |
1499 | @section Indentation Commands | |
1500 | @cindex indentation commands | |
1501 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
6bf7aab6 | 1502 | |
d7bd46ed GM |
1503 | The following list of commands re-indent C constructs. Note that when |
1504 | you change your coding style, either interactively or through some other | |
1505 | means, your file does @emph{not} automatically get re-indented. You | |
1506 | will need to execute one of the following commands to see the effects of | |
1507 | your changes. | |
1508 | ||
1509 | @cindex GNU indent program | |
1510 | Also, variables like @code{c-hanging-*} and @code{c-cleanup-list} | |
1511 | only affect how on-the-fly code is formatted. Changing the | |
1512 | ``hanginess'' of a brace and then re-indenting, will not move the brace | |
1513 | to a different line. For this, you're better off getting an external | |
1514 | program like GNU @code{indent}, which will re-arrange brace location, | |
1515 | among other things. | |
1516 | ||
1517 | Re-indenting large sections of code can take a long time. When | |
1518 | @ccmode{} reindents a region of code, it is essentially equivalent to | |
1519 | hitting @kbd{TAB} on every line of the region. Especially vulnerable is | |
1520 | code generator output@footnote{In particular, I have had people | |
6bf7aab6 DL |
1521 | complain about the speed with which @code{lex(1)} output is re-indented. |
1522 | Lex, yacc, and other code generators usually output some pretty | |
d7bd46ed GM |
1523 | perversely formatted code. Re-indenting such code will be slow.}. |
1524 | ||
1525 | These commands are useful when indenting code: | |
6bf7aab6 | 1526 | |
d7bd46ed | 1527 | @table @asis |
6bf7aab6 | 1528 | |
d7bd46ed | 1529 | @kindex TAB |
6bf7aab6 DL |
1530 | @findex c-indent-command |
1531 | @findex indent-command (c-) | |
d7bd46ed GM |
1532 | @item @kbd{TAB} (@code{c-indent-command}) |
1533 | Indents the current line. The actual behavior is controlled by several | |
1534 | variables, described below. See @code{c-tab-always-indent}, | |
1535 | @code{c-insert-tab-function}, and @code{indent-tabs-mode}. With a | |
1536 | numeric argument, this command rigidly indents the region, preserving | |
1537 | the relative indentation among the lines. | |
6bf7aab6 | 1538 | |
718fb8a1 | 1539 | @kindex C-M-q |
6bf7aab6 DL |
1540 | @findex c-indent-exp |
1541 | @findex indent-exp (c-) | |
718fb8a1 | 1542 | @item @kbd{C-M-q} (@code{c-indent-exp}) |
d7bd46ed GM |
1543 | Indent an entire balanced brace or parenthesis expression. Note that |
1544 | point must be on the opening brace or parenthesis of the expression you | |
1545 | want to indent. | |
6bf7aab6 DL |
1546 | |
1547 | @kindex C-c C-q | |
1548 | @findex c-indent-defun | |
1549 | @findex indent-defun (c-) | |
d7bd46ed GM |
1550 | @item @kbd{C-c C-q} (@code{c-indent-defun}) |
1551 | Indents the entire top-level function or class definition encompassing | |
1552 | point. It leaves point unchanged. This function can't be used to | |
1553 | re-indent a nested brace construct, such as a nested class or function, | |
1554 | or a Java method. The top-level construct being re-indented must be | |
1555 | complete, i.e. it must have both a beginning brace and an ending brace. | |
6bf7aab6 | 1556 | |
718fb8a1 | 1557 | @kindex C-M-\ |
6bf7aab6 | 1558 | @findex indent-region |
718fb8a1 | 1559 | @item @kbd{C-M-\} (@code{indent-region}) |
d7bd46ed GM |
1560 | Indents an arbitrary region of code. This is a standard Emacs command, |
1561 | tailored for C code in a @ccmode{} buffer. Note that of course, point | |
1562 | and mark must delineate the region you want to indent. | |
6bf7aab6 | 1563 | |
718fb8a1 | 1564 | @kindex C-M-h |
6bf7aab6 DL |
1565 | @findex c-mark-function |
1566 | @findex mark-function (c-) | |
718fb8a1 | 1567 | @item @kbd{C-M-h} (@code{c-mark-function}) |
d7bd46ed GM |
1568 | While not strictly an indentation command, this is useful for marking |
1569 | the current top-level function or class definition as the current | |
1570 | region. As with @code{c-indent-defun}, this command operates on | |
1571 | top-level constructs, and can't be used to mark say, a Java method. | |
6bf7aab6 | 1572 | |
d7bd46ed GM |
1573 | @end table |
1574 | ||
1575 | These variables are also useful when indenting code: | |
1576 | ||
1577 | @table @code | |
1578 | ||
1579 | @vindex c-tab-always-indent | |
1580 | @vindex tab-always-indent (c-) | |
1581 | @kindex TAB | |
1582 | @cindex literal | |
1583 | @item c-tab-always-indent | |
1584 | This variable controls how @kbd{TAB} @code{c-indent-command} operates. | |
1585 | When this variable is @code{t}, @kbd{TAB} always just indents the | |
1586 | current line. When it is @code{nil}, the line is indented only if point | |
1587 | is at the left margin, or on or before the first non-whitespace | |
1588 | character on the line, otherwise some whitespace is inserted. If this | |
1589 | variable is the symbol @code{other}, then some whitespace is inserted | |
1590 | only within strings and comments (literals), an inside preprocessor | |
1591 | directives, but the line is always reindented. | |
1592 | ||
1593 | @vindex c-insert-tab-function | |
1594 | @vindex insert-tab-function (c-) | |
1595 | @findex tab-to-tab-stop | |
1596 | @item c-insert-tab-function | |
1597 | When ``some whitespace'' is inserted as described above, what actually | |
1598 | happens is that the function stored in @code{c-insert-tab-function} is | |
1599 | called. Normally, this just inserts a real tab character, or the | |
1600 | equivalent number of spaces, depending on @code{indent-tabs-mode}. | |
1601 | Some people, however, set @code{c-insert-tab-function} to | |
1602 | @code{tab-to-tab-stop} so as to get hard tab stops when indenting. | |
1603 | ||
1604 | @vindex indent-tabs-mode | |
1605 | @item indent-tabs-mode | |
1606 | This is a standard Emacs variable that controls how line indentation is | |
1607 | composed. When this variable is non-@code{nil}, then tabs can be used | |
1608 | in a line's indentation, otherwise only spaces can be used. | |
1609 | ||
1610 | @vindex c-progress-interval | |
1611 | @vindex progress-interval (c-) | |
1612 | @item c-progress-interval | |
1613 | When indenting large regions of code, this variable controls how often a | |
1614 | progress message is displayed. Set this variable to @code{nil} to | |
1615 | inhibit the progress messages, or set it to an integer which is the | |
1616 | interval in seconds that progress messages are displayed. | |
6bf7aab6 | 1617 | |
d7bd46ed GM |
1618 | @end table |
1619 | ||
1620 | ||
1621 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
1622 | @node Movement Commands, Other Commands, Indentation Commands, Commands | |
1623 | @comment node-name, next, previous, up | |
1624 | @section Movement Commands | |
1625 | @cindex movement commands | |
6bf7aab6 DL |
1626 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
1627 | ||
d7bd46ed | 1628 | @ccmode{} contains some useful command for moving around in C |
6bf7aab6 DL |
1629 | code. |
1630 | ||
d7bd46ed GM |
1631 | @table @asis |
1632 | ||
6bf7aab6 DL |
1633 | @findex c-beginning-of-defun |
1634 | @findex beginning-of-defun (c-) | |
1635 | @findex beginning-of-defun | |
d7bd46ed | 1636 | @item @kbd{M-x c-beginning-of-defun} |
6bf7aab6 DL |
1637 | Moves point back to the least-enclosing brace. This function is |
1638 | analogous to the Emacs built-in command @code{beginning-of-defun}, | |
1639 | except it eliminates the constraint that the top-level opening brace | |
1640 | must be in column zero. See @code{beginning-of-defun} for more | |
1641 | information. | |
1642 | ||
1643 | Depending on the coding style being used, you might prefer | |
1644 | @code{c-beginning-of-defun} to @code{beginning-of-defun}. If so, | |
1645 | consider binding @kbd{C-M-a} to the former instead. For backwards | |
1646 | compatibility reasons, the default binding remains in effect. | |
1647 | ||
1648 | @findex c-end-of-defun | |
1649 | @findex end-of-defun (c-) | |
1650 | @findex end-of-defun | |
d7bd46ed | 1651 | @item @kbd{M-x c-end-of-defun} |
6bf7aab6 DL |
1652 | Moves point to the end of the current top-level definition. This |
1653 | function is analogous to the Emacs built-in command @code{end-of-defun}, | |
1654 | except it eliminates the constraint that the top-level opening brace of | |
1655 | the defun must be in column zero. See @code{beginning-of-defun} for more | |
1656 | information. | |
1657 | ||
1658 | Depending on the coding style being used, you might prefer | |
1659 | @code{c-end-of-defun} to @code{end-of-defun}. If so, | |
1660 | consider binding @kbd{C-M-e} to the former instead. For backwards | |
1661 | compatibility reasons, the default binding remains in effect. | |
1662 | ||
1663 | @kindex C-c C-u | |
1664 | @findex c-up-conditional | |
1665 | @findex up-conditional (c-) | |
d7bd46ed | 1666 | @item @kbd{C-c C-u} (@code{c-up-conditional}) |
6bf7aab6 DL |
1667 | Move point back to the containing preprocessor conditional, leaving the |
1668 | mark behind. A prefix argument acts as a repeat count. With a negative | |
1669 | argument, move point forward to the end of the containing | |
d7bd46ed GM |
1670 | preprocessor conditional. |
1671 | ||
1672 | @samp{#elif} is treated like @samp{#else} followed by @samp{#if}, so the | |
1673 | function stops at them when going backward, but not when going forward. | |
1674 | ||
1675 | @findex c-up-conditional-with-else | |
1676 | @findex up-conditional-with-else (c-) | |
1677 | @item @kbd{M-x c-up-conditional-with-else} | |
1678 | A variety of @code{c-up-conditional} that also stops at @samp{#else} | |
1679 | lines. Normally those lines are ignored. | |
1680 | ||
1681 | @findex c-down-conditional | |
1682 | @findex down-conditional (c-) | |
1683 | @item @kbd{M-x c-down-conditional} | |
1684 | Move point forward into the next nested preprocessor conditional, | |
1685 | leaving the mark behind. A prefix argument acts as a repeat count. | |
1686 | With a negative argument, move point backward into the previous | |
1687 | nested preprocessor conditional. | |
1688 | ||
1689 | @samp{#elif} is treated like @samp{#else} followed by @samp{#if}, so the | |
1690 | function stops at them when going forward, but not when going backward. | |
1691 | ||
1692 | @findex c-down-conditional-with-else | |
1693 | @findex down-conditional-with-else (c-) | |
1694 | @item @kbd{M-x c-down-conditional-with-else} | |
1695 | A variety of @code{c-down-conditional} that also stops at @samp{#else} | |
1696 | lines. Normally those lines are ignored. | |
6bf7aab6 DL |
1697 | |
1698 | @kindex C-c C-p | |
1699 | @findex c-backward-conditional | |
1700 | @findex backward-conditional (c-) | |
d7bd46ed | 1701 | @item @kbd{C-c C-p} (@code{c-backward-conditional}) |
6bf7aab6 DL |
1702 | Move point back over a preprocessor conditional, leaving the mark |
1703 | behind. A prefix argument acts as a repeat count. With a negative | |
1704 | argument, move forward. | |
1705 | ||
1706 | @kindex C-c C-n | |
1707 | @findex c-forward-conditional | |
1708 | @findex forward-conditional (c-) | |
d7bd46ed | 1709 | @item @kbd{C-c C-n} (@code{c-forward-conditional}) |
6bf7aab6 DL |
1710 | Move point forward across a preprocessor conditional, leaving the mark |
1711 | behind. A prefix argument acts as a repeat count. With a negative | |
1712 | argument, move backward. | |
1713 | ||
d7bd46ed | 1714 | @kindex M-a |
6bf7aab6 DL |
1715 | @findex c-beginning-of-statement |
1716 | @findex beginning-of-statement (c-) | |
d7bd46ed | 1717 | @item @kbd{M-a} (@code{c-beginning-of-statement}) |
6bf7aab6 | 1718 | Move point to the beginning of the innermost C statement. If point is |
cb7f2e96 GM |
1719 | already at the beginning of a statement, move to the beginning of the |
1720 | closest preceding statement, even if that means moving into a block (you | |
718fb8a1 | 1721 | can use @kbd{C-M-b} to move over a balanced block). With prefix |
6bf7aab6 DL |
1722 | argument @var{n}, move back @var{n} @minus{} 1 statements. |
1723 | ||
cb7f2e96 GM |
1724 | If point is within or next to a comment or a string which spans more |
1725 | than one line, this command moves by sentences instead of statements. | |
6bf7aab6 DL |
1726 | |
1727 | When called from a program, this function takes three optional | |
cb7f2e96 GM |
1728 | arguments: the repetition count, a buffer position limit which is the |
1729 | farthest back to search for the syntactic context, and a flag saying | |
1730 | whether to do sentence motion in or near comments and multiline strings. | |
6bf7aab6 | 1731 | |
d7bd46ed | 1732 | @kindex M-e |
6bf7aab6 DL |
1733 | @findex c-end-of-statement |
1734 | @findex end-of-statement (c-) | |
d7bd46ed | 1735 | @item @kbd{M-e} (@code{c-end-of-statement}) |
6bf7aab6 DL |
1736 | Move point to the end of the innermost C statement. If point is at the |
1737 | end of a statement, move to the end of the next statement, even if it's | |
718fb8a1 | 1738 | inside a nested block (use @kbd{C-M-f} to move to the other side of the |
6bf7aab6 DL |
1739 | block). With prefix argument @var{n}, move forward @var{n} @minus{} 1 |
1740 | statements. | |
1741 | ||
cb7f2e96 GM |
1742 | If point is within or next to a comment or a string which spans more |
1743 | than one line, this command moves by sentences instead of statements. | |
6bf7aab6 DL |
1744 | |
1745 | When called from a program, this function takes three optional | |
cb7f2e96 GM |
1746 | arguments: the repetition count, a buffer position limit which is the |
1747 | farthest back to search for the syntactic context, and a flag saying | |
1748 | whether to do sentence motion in or near comments and multiline strings. | |
6bf7aab6 DL |
1749 | |
1750 | @findex c-forward-into-nomenclature | |
1751 | @findex forward-into-nomenclature (c-) | |
d7bd46ed | 1752 | @item @kbd{M-x c-forward-into-nomenclature} |
6bf7aab6 DL |
1753 | A popular programming style, especially for object-oriented languages |
1754 | such as C++ is to write symbols in a mixed case format, where the first | |
1755 | letter of each word is capitalized, and not separated by underscores. | |
1756 | E.g. @samp{SymbolsWithMixedCaseAndNoUnderlines}. | |
1757 | ||
1758 | This command moves point forward to next capitalized word. With prefix | |
1759 | argument @var{n}, move @var{n} times. | |
1760 | ||
1761 | @findex c-backward-into-nomenclature | |
1762 | @findex backward-into-nomenclature (c-) | |
d7bd46ed | 1763 | @item @kbd{M-x c-backward-into-nomenclature} |
6bf7aab6 DL |
1764 | Move point backward to beginning of the next capitalized |
1765 | word. With prefix argument @var{n}, move @var{n} times. If | |
1766 | @var{n} is negative, move forward. | |
1767 | ||
d7bd46ed GM |
1768 | @end table |
1769 | ||
1770 | ||
1771 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
1772 | @node Other Commands, , Movement Commands, Commands | |
1773 | @comment node-name, next, previous, up | |
1774 | @section Other Commands | |
1775 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
1776 | ||
1777 | @ccmode{} contains a few other useful commands: | |
1778 | ||
1779 | @table @asis | |
1780 | ||
6bf7aab6 DL |
1781 | @kindex C-c : |
1782 | @findex c-scope-operator | |
1783 | @findex scope-operator (c-) | |
d7bd46ed | 1784 | @item @kbd{C-c :} (@code{c-scope-operator}) |
6bf7aab6 DL |
1785 | In C++, it is also sometimes desirable to insert the double-colon scope |
1786 | operator without performing the electric behavior of colon insertion. | |
1787 | @kbd{C-c :} does just this. | |
1788 | ||
d7bd46ed GM |
1789 | @kindex C-c C-\ |
1790 | @findex c-backslash-region | |
1791 | @findex backslash-region (c-) | |
1792 | @item @kbd{C-c C-\} (@code{c-backslash-region}) | |
1793 | This function is handy when editing macros split over several lines by | |
1794 | ending each line with a backslash. It inserts and aligns, or deletes | |
1795 | these end-of-line backslashes in the current region. | |
1796 | ||
1797 | @vindex c-backslash-column | |
1798 | @vindex backslash-column (c-) | |
1799 | With no prefix argument, it inserts any missing backslashes and aligns | |
1800 | them to the column specified by the @code{c-backslash-column} style | |
1801 | variable. With a prefix argument, it deletes any backslashes. | |
1802 | ||
1803 | The function does not modify blank lines at the start of the region. If | |
1804 | the region ends at the start of a line, it always deletes the backslash | |
1805 | (if any) at the end of the previous line. | |
6bf7aab6 DL |
1806 | |
1807 | @end table | |
1808 | ||
6bf7aab6 | 1809 | |
d7bd46ed GM |
1810 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
1811 | @node Customizing Indentation, Syntactic Symbols, Commands, Top | |
1812 | @comment node-name, next, previous, up | |
1813 | @chapter Customizing Indentation | |
1814 | @cindex customizing indentation | |
6bf7aab6 DL |
1815 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
1816 | ||
1817 | @vindex c-offsets-alist | |
1818 | @vindex offsets-alist (c-) | |
d7bd46ed GM |
1819 | The style variable @code{c-offsets-alist} contains the mappings between |
1820 | syntactic symbols and the offsets to apply for those symbols. It's set | |
1821 | at mode initialization from a @emph{style} you may specify. Styles are | |
1822 | groupings of syntactic symbol offsets and other style variable values. | |
1823 | Most likely, you'll find that one of the pre-defined styles will suit | |
1824 | your needs. @xref{Styles}, for an explanation of how to set up named | |
1825 | styles. | |
1826 | ||
1827 | Only syntactic symbols not already bound on @code{c-offsets-alist} will | |
1828 | be set from styles. This means that any association you set on it, be | |
1829 | it before or after mode initialization, will not be changed. The | |
1830 | @code{c-offsets-alist} variable may therefore be used from e.g. the | |
1831 | Customization interface@footnote{Available in Emacs 20 and later, and | |
1832 | XEmacs 19.15 and later.} to easily change indentation offsets without | |
1833 | having to bother about styles. Initially @code{c-offsets-alist} is | |
1834 | empty, so that all syntactic symbols are set by the style system. | |
1835 | ||
1836 | @kindex C-c C-o | |
1837 | @findex c-set-offset | |
1838 | @findex set-offset (c-) | |
1839 | You can use the command @kbd{C-c C-o} (@code{c-set-offset}) as the way | |
1840 | to set offsets, both interactively and from your mode | |
47d7776c | 1841 | hook@footnote{Obviously, you use the key binding interactively, and the |
d7bd46ed GM |
1842 | function call programmatically!}. |
1843 | ||
1844 | @vindex c-basic-offset | |
1845 | @vindex basic-offset (c-) | |
1846 | The offset associated with any particular syntactic symbol can be any of | |
cb7f2e96 GM |
1847 | an integer, a function or lambda expression, a variable name, a vector, |
1848 | a list, or one of the following symbols: @code{+}, @code{-}, @code{++}, | |
1849 | @code{--}, @code{*}, or @code{/}. | |
1850 | ||
1851 | Those last special symbols describe an offset in multiples of the value | |
1852 | of the style variable @code{c-basic-offset}. By defining a style's | |
1853 | indentation in terms of this fundamental variable, you can change the | |
1854 | amount of whitespace given to an indentation level while maintaining the | |
1855 | same basic shape of your code. Here are the values that the special | |
1856 | symbols correspond to: | |
6bf7aab6 DL |
1857 | |
1858 | @table @code | |
1859 | ||
1860 | @item + | |
1861 | @code{c-basic-offset} times 1 | |
1862 | @item - | |
1863 | @code{c-basic-offset} times -1 | |
1864 | @item ++ | |
1865 | @code{c-basic-offset} times 2 | |
1866 | @item -- | |
1867 | @code{c-basic-offset} times -2 | |
1868 | @item * | |
1869 | @code{c-basic-offset} times 0.5 | |
1870 | @item / | |
1871 | @code{c-basic-offset} times -0.5 | |
1872 | ||
1873 | @end table | |
1874 | ||
d7bd46ed GM |
1875 | @cindex indentation functions |
1876 | ||
1877 | When a function is used as offset, it's called an @dfn{indentation | |
1878 | function}. Such functions are useful when more context than just the | |
1879 | syntactic symbol is needed to get the desired indentation. | |
1880 | @xref{Indentation Functions}, and @ref{Custom Indentation Functions}, | |
1881 | for details about them. | |
1882 | ||
cb7f2e96 GM |
1883 | If the offset is a vector, its first element sets the absolute |
1884 | indentation column, which will override any relative indentation. | |
1885 | ||
d7bd46ed GM |
1886 | @vindex c-strict-syntax-p |
1887 | @vindex strict-syntax-p (c-) | |
1888 | The offset can also be a list, in which case it is evaluated recursively | |
1889 | using the semantics described above. The first element of the list that | |
1890 | returns a non-@code{nil} value succeeds and the evaluation stops. If | |
1891 | none of the list elements return a non-@code{nil} value, then an offset | |
1892 | of 0 (zero) is used@footnote{There is however a variable | |
1893 | @code{c-strict-syntax-p} that, when set to non-@code{nil}, will cause an | |
1894 | error to be signalled in that case. It's now considered obsolete since | |
1895 | it doesn't work well with some of the alignment functions that now | |
1896 | returns @code{nil} instead of zero to be more usable in lists. You | |
1897 | should therefore leave @code{c-strict-syntax-p} set to @code{nil}.}. | |
1898 | ||
6bf7aab6 DL |
1899 | So, for example, because most of the default offsets are defined in |
1900 | terms of @code{+}, @code{-}, and @code{0}, if you like the general | |
1901 | indentation style, but you use 4 spaces instead of 2 spaces per level, | |
1902 | you can probably achieve your style just by changing | |
d7bd46ed GM |
1903 | @code{c-basic-offset} like so@footnote{You can try this interactively in |
1904 | a C buffer by typing the text that appears in italics.}: | |
6bf7aab6 DL |
1905 | @example |
1906 | ||
d7bd46ed GM |
1907 | @emph{M-x set-variable RET} |
1908 | Set variable: @emph{c-basic-offset RET} | |
1909 | Set c-basic-offset to value: @emph{4 RET} | |
6bf7aab6 DL |
1910 | |
1911 | @end example | |
1912 | ||
1913 | @noindent | |
1914 | This would change | |
1915 | @example | |
1916 | @group | |
1917 | ||
1918 | int add( int val, int incr, int doit ) | |
1919 | @{ | |
1920 | if( doit ) | |
1921 | @{ | |
1922 | return( val + incr ); | |
1923 | @} | |
1924 | return( val ); | |
1925 | @} | |
1926 | ||
1927 | @end group | |
1928 | @end example | |
1929 | @noindent | |
1930 | to | |
1931 | @example | |
1932 | @group | |
1933 | ||
1934 | int add( int val, int incr, int doit ) | |
1935 | @{ | |
1936 | if( doit ) | |
1937 | @{ | |
1938 | return( val + incr ); | |
1939 | @} | |
1940 | return( val ); | |
1941 | @} | |
1942 | ||
1943 | @end group | |
1944 | @end example | |
1945 | ||
6bf7aab6 | 1946 | To change indentation styles more radically, you will want to change the |
d7bd46ed GM |
1947 | offsets associated with other syntactic symbols. First, I'll show you |
1948 | how to do that interactively, then I'll describe how to make changes to | |
1949 | your @file{.emacs} file so that your changes are more permanent. | |
6bf7aab6 DL |
1950 | |
1951 | @menu | |
1952 | * Interactive Customization:: | |
1953 | * Permanent Customization:: | |
d7bd46ed | 1954 | * Hooks:: |
6bf7aab6 DL |
1955 | * Styles:: |
1956 | * Advanced Customizations:: | |
1957 | @end menu | |
1958 | ||
6bf7aab6 | 1959 | |
d7bd46ed GM |
1960 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
1961 | @node Interactive Customization, Permanent Customization, , Customizing Indentation | |
1962 | @comment node-name, next, previous, up | |
1963 | @section Interactive Customization | |
1964 | @cindex interactive customization | |
6bf7aab6 DL |
1965 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
1966 | ||
1967 | As an example of how to customize indentation, let's change the | |
1968 | style of this example@footnote{In this an subsequent examples, the | |
1969 | original code is formatted using the @samp{gnu} style unless otherwise | |
d7bd46ed | 1970 | indicated. @xref{Styles}.}: |
6bf7aab6 DL |
1971 | @example |
1972 | @group | |
1973 | ||
1974 | 1: int add( int val, int incr, int doit ) | |
1975 | 2: @{ | |
1976 | 3: if( doit ) | |
1977 | 4: @{ | |
1978 | 5: return( val + incr ); | |
1979 | 6: @} | |
1980 | 7: return( val ); | |
1981 | 8: @} | |
1982 | ||
1983 | @end group | |
1984 | @end example | |
1985 | @noindent | |
1986 | to: | |
1987 | @example | |
1988 | @group | |
1989 | ||
1990 | 1: int add( int val, int incr, int doit ) | |
1991 | 2: @{ | |
1992 | 3: if( doit ) | |
1993 | 4: @{ | |
1994 | 5: return( val + incr ); | |
1995 | 6: @} | |
1996 | 7: return( val ); | |
1997 | 8: @} | |
1998 | ||
1999 | @end group | |
2000 | @end example | |
2001 | ||
2002 | In other words, we want to change the indentation of braces that open a | |
2003 | block following a condition so that the braces line up under the | |
2004 | conditional, instead of being indented. Notice that the construct we | |
2005 | want to change starts on line 4. To change the indentation of a line, | |
2006 | we need to see which syntactic components affect the offset calculations | |
2007 | for that line. Hitting @kbd{C-c C-s} on line 4 yields: | |
2008 | @example | |
2009 | ||
2010 | ((substatement-open . 44)) | |
2011 | ||
2012 | @end example | |
2013 | ||
6bf7aab6 DL |
2014 | @noindent |
2015 | so we know that to change the offset of the open brace, we need to | |
2016 | change the indentation for the @code{substatement-open} syntactic | |
d7bd46ed GM |
2017 | symbol. To do this interactively, just hit @kbd{C-c C-o}. This prompts |
2018 | you for the syntactic symbol to change, providing a reasonable default. | |
2019 | In this case, the default is @code{substatement-open}, which is just the | |
2020 | syntactic symbol we want to change! | |
6bf7aab6 DL |
2021 | |
2022 | After you hit return, @ccmode{} will then prompt you for the new | |
2023 | offset value, with the old value as the default. The default in this | |
2024 | case is @samp{+}, but we want no extra indentation so enter | |
2025 | @samp{0} and @kbd{RET}. This will associate the offset 0 with the | |
d7bd46ed | 2026 | syntactic symbol @code{substatement-open}. |
6bf7aab6 | 2027 | |
6bf7aab6 DL |
2028 | To check your changes quickly, just hit @kbd{C-c C-q} |
2029 | (@code{c-indent-defun}) to reindent the entire function. The example | |
2030 | should now look like: | |
2031 | @example | |
2032 | @group | |
2033 | ||
2034 | 1: int add( int val, int incr, int doit ) | |
2035 | 2: @{ | |
2036 | 3: if( doit ) | |
2037 | 4: @{ | |
2038 | 5: return( val + incr ); | |
2039 | 6: @} | |
2040 | 7: return( val ); | |
2041 | 8: @} | |
2042 | ||
2043 | @end group | |
2044 | @end example | |
2045 | ||
2046 | Notice how just changing the open brace offset on line 4 is all we | |
2047 | needed to do. Since the other affected lines are indented relative to | |
2048 | line 4, they are automatically indented the way you'd expect. For more | |
2049 | complicated examples, this may not always work. The general approach to | |
2050 | take is to always start adjusting offsets for lines higher up in the | |
2051 | file, then re-indent and see if any following lines need further | |
2052 | adjustments. | |
2053 | ||
d7bd46ed GM |
2054 | |
2055 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
2056 | @node Permanent Customization, Hooks, Interactive Customization, Customizing Indentation | |
2057 | @comment node-name, next, previous, up | |
2058 | @section Permanent Customization | |
2059 | @cindex permanent customization | |
6bf7aab6 | 2060 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
6bf7aab6 | 2061 | |
d7bd46ed GM |
2062 | To make your changes permanent, you need to add some lisp code to your |
2063 | @file{.emacs} file. @ccmode{} supports many different ways to be | |
2064 | configured, from the straightforward way by setting variables globally | |
2065 | in @file{.emacs} or in the Customization interface, to the complex and | |
2066 | precisely controlled way by using styles and hook functions. | |
2067 | ||
2068 | The simplest way of customizing @ccmode{} permanently is to set the | |
2069 | variables in your @file{.emacs} with @code{setq} and similar commands. | |
2070 | So to make the setting of @code{substatement-open} permanent, add this | |
2071 | to the @file{.emacs} file: | |
2072 | @example | |
2073 | @group | |
2074 | ||
2075 | (require 'cc-mode) | |
2076 | (c-set-offset 'substatement-open 0) | |
2077 | ||
2078 | @end group | |
2079 | @end example | |
2080 | ||
2081 | The @code{require} line is only needed once in the beginning to make | |
2082 | sure @ccmode{} is loaded so that the @code{c-set-offset} function is | |
2083 | defined. | |
2084 | ||
2085 | You can also use the more user friendly Customization interface, but | |
2086 | this manual does not cover how that works. | |
2087 | ||
2088 | Variables set like this at the top level in @file{.emacs} take effect in | |
2089 | all @ccmode{} buffers, regardless of language. The indentation style | |
f214c025 GM |
2090 | related variables, e.g. @code{c-basic-offset}, that you don't set this |
2091 | way get their value from the style system (@pxref{Styles}), and they | |
2092 | therefore depend on the setting of @code{c-default-style}. Note that if | |
2093 | you use Customize, this means that the greyed-out default values | |
2094 | presented there might not be the ones you actually get, since the actual | |
2095 | values depend on the style, which may very well be different for | |
2096 | different languages. | |
d7bd46ed GM |
2097 | |
2098 | If you want to make more advanced configurations, e.g. language-specific | |
2099 | customization, global variable settings isn't enough. For that you can | |
2100 | use the language hooks, see @ref{Hooks}, and/or the style system, see | |
2101 | @ref{Styles}. | |
2102 | ||
2103 | @vindex c-style-variables-are-local-p | |
2104 | @vindex style-variables-are-local-p (c-) | |
2105 | By default, all style variables are global, so that every buffer will | |
2106 | share the same style settings. This is fine if you primarily edit one | |
2107 | style of code, but if you edit several languages and want to use | |
2108 | different styles for them, you need finer control by making the style | |
2109 | variables buffer local. The recommended way to do this is to set the | |
2110 | variable @code{c-style-variables-are-local-p} to @code{t}. The | |
2111 | variables will be made buffer local when @ccmode{} is activated in a | |
2112 | buffer for the first time in the Emacs session. Note that once the | |
2113 | style variables are made buffer local, they cannot be made global again, | |
2114 | without restarting Emacs. | |
2115 | ||
2116 | ||
2117 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
2118 | @node Hooks, Styles, Permanent Customization, Customizing Indentation | |
2119 | @comment node-name, next, previous, up | |
2120 | @section Hooks | |
2121 | @cindex hooks | |
6bf7aab6 DL |
2122 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
2123 | ||
2124 | @vindex c-mode-common-hook | |
d7bd46ed | 2125 | @vindex mode-common-hook (c-) |
6bf7aab6 DL |
2126 | @vindex c-mode-hook |
2127 | @vindex c++-mode-hook | |
2128 | @vindex objc-mode-hook | |
2129 | @vindex java-mode-hook | |
2130 | @vindex idl-mode-hook | |
d7bd46ed | 2131 | @vindex pike-mode-hook |
6bf7aab6 DL |
2132 | @vindex c-initialization-hook |
2133 | @vindex initialization-hook (c-) | |
d7bd46ed GM |
2134 | @ccmode{} provides several hooks that you can use to customize the mode |
2135 | according to your coding style. Each language mode has its own hook, | |
2136 | adhering to standard Emacs major mode conventions. There is also one | |
2137 | general hook and one package initialization hook: | |
6bf7aab6 DL |
2138 | |
2139 | @itemize @bullet | |
2140 | ||
2141 | @item | |
d7bd46ed | 2142 | @code{c-mode-hook} --- For C buffers only. |
6bf7aab6 | 2143 | @item |
d7bd46ed | 2144 | @code{c++-mode-hook} --- For C++ buffers only. |
6bf7aab6 | 2145 | @item |
d7bd46ed | 2146 | @code{objc-mode-hook} --- For Objective-C buffers only. |
6bf7aab6 | 2147 | @item |
d7bd46ed | 2148 | @code{java-mode-hook} --- For Java buffers only. |
6bf7aab6 | 2149 | @item |
d7bd46ed | 2150 | @code{idl-mode-hook} --- For CORBA IDL buffers only. |
6bf7aab6 | 2151 | @item |
d7bd46ed | 2152 | @code{pike-mode-hook} --- For Pike buffers only. |
6bf7aab6 | 2153 | @item |
d7bd46ed GM |
2154 | @code{c-mode-common-hook} --- Common across all languages. |
2155 | @item | |
2156 | @code{c-initialization-hook} --- Hook run only once per Emacs session, | |
6bf7aab6 DL |
2157 | when @ccmode{} is initialized. |
2158 | ||
2159 | @end itemize | |
2160 | ||
2161 | The language hooks get run as the last thing when you enter that | |
d7bd46ed GM |
2162 | language mode. The @code{c-mode-common-hook} is run by all supported |
2163 | modes @emph{before} the language specific hook, and thus can contain | |
2164 | customizations that are common across all languages. Most of the | |
cb7f2e96 GM |
2165 | examples in this section will assume you are using the common hook. |
2166 | ||
2167 | Note that all the language-specific mode setup that CC Mode does is done | |
2168 | prior to both @code{c-mode-common-hook} and the language specific hook. | |
2169 | That includes installing the indentation style, which can be mode | |
2170 | specific (and also is by default for Java mode). Thus, any style | |
2171 | settings done in @code{c-mode-common-hook} will override whatever | |
2172 | language-specific style is chosen by @code{c-default-style}. | |
6bf7aab6 DL |
2173 | |
2174 | Here's a simplified example of what you can add to your @file{.emacs} | |
d7bd46ed GM |
2175 | file to do things whenever any @ccmode{} language is edited. See the |
2176 | Emacs manuals for more information on customizing Emacs via hooks. | |
2177 | @xref{Sample .emacs File}, for a more complete sample @file{.emacs} | |
2178 | file. | |
6bf7aab6 DL |
2179 | @example |
2180 | @group | |
2181 | ||
2182 | (defun my-c-mode-common-hook () | |
2183 | ;; my customizations for all of c-mode and related modes | |
d7bd46ed | 2184 | (no-case-fold-search) |
6bf7aab6 DL |
2185 | ) |
2186 | (add-hook 'c-mode-common-hook 'my-c-mode-common-hook) | |
2187 | ||
2188 | @end group | |
2189 | @end example | |
2190 | ||
6bf7aab6 DL |
2191 | |
2192 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
d7bd46ed GM |
2193 | @node Styles, Advanced Customizations, Hooks, Customizing Indentation |
2194 | @comment node-name, next, previous, up | |
2195 | @section Styles | |
2196 | @cindex styles | |
6bf7aab6 DL |
2197 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
2198 | ||
2199 | Most people only need to edit code formatted in just a few well-defined | |
2200 | and consistent styles. For example, their organization might impose a | |
2201 | ``blessed'' style that all its programmers must conform to. Similarly, | |
d7bd46ed GM |
2202 | people who work on GNU software will have to use the GNU coding style. |
2203 | Some shops are more lenient, allowing a variety of coding styles, and as | |
2204 | programmers come and go, there could be a number of styles in use. For | |
2205 | this reason, @ccmode{} makes it convenient for you to set up logical | |
2206 | groupings of customizations called @dfn{styles}, associate a single name | |
2207 | for any particular style, and pretty easily start editing new or | |
2208 | existing code using these styles. | |
2209 | ||
2210 | @cindex style variables | |
2211 | The variables that the style system affect are called @dfn{style | |
2212 | variables}. They are handled specially in several ways: | |
2213 | ||
2214 | @itemize @bullet | |
2215 | @item | |
2216 | Style variables are by default global variables, i.e. they have the same | |
2217 | value in all Emacs buffers. However, they can instead be made always | |
2218 | buffer local by setting @code{c-style-variables-are-local-p} to | |
2219 | non-@code{nil} before @ccmode{} is initialized. | |
2220 | ||
2221 | @vindex c-old-style-variable-behavior | |
2222 | @vindex old-style-variable-behavior (c-) | |
2223 | @item | |
2224 | The default value of any style variable (with two exceptions --- see | |
2225 | below) is the special symbol @code{set-from-style}. Variables that are | |
2226 | still set to that symbol when a @ccmode{} buffer is initialized will be | |
2227 | set according to the current style, otherwise they will keep their | |
2228 | current value@footnote{This is a big change from versions of @ccmode{} | |
2229 | earlier than 5.26, where such settings would get overridden by the style | |
2230 | system unless special precautions were taken. That was changed since it | |
2231 | was counterintuitive and confusing, especially to novice users. If your | |
2232 | configuration depends on the old overriding behavior, you can set the | |
2233 | variable @code{c-old-style-variable-behavior} to non-@code{nil}.}. | |
2234 | ||
2235 | Note that when we talk about the ``default value'' for a style variable, | |
2236 | we don't mean the @code{set-from-style} symbol that all style variables | |
2237 | are set to initially, but instead the value it will get at mode | |
2238 | initialization when neither a style nor a global setting has set its | |
2239 | value. | |
2240 | ||
2241 | The style variable @code{c-offsets-alist} is handled a little | |
2242 | differently from the other style variables. It's an association list, | |
2243 | and is thus by default set to the empty list, @code{nil}. When the | |
2244 | style system is initialized, any syntactic symbols already on it are | |
2245 | kept --- only the missing ones are filled in from the chosen style. | |
2246 | ||
2247 | The style variable @code{c-special-indent-hook} is also handled in a | |
2248 | special way. Styles may only add more functions on this hook, so the | |
2249 | global settings on it are always preserved@footnote{This did not change | |
2250 | in version 5.26.}. | |
2251 | ||
2252 | @item | |
2253 | The global settings of style variables get captured in the special | |
2254 | @code{user} style, which is used as the base for all the other styles. | |
2255 | @xref{Built-in Styles}, for details. | |
2256 | ||
2257 | @end itemize | |
2258 | ||
2259 | The style variables are: | |
2260 | @code{c-basic-offset}, | |
2261 | @code{c-comment-only-line-offset}, | |
2262 | @code{c-block-comment-prefix}, | |
2263 | @code{c-comment-prefix-regexp}, | |
2264 | @code{c-cleanup-list}, | |
2265 | @code{c-hanging-braces-alist}, | |
2266 | @code{c-hanging-colons-alist}, | |
2267 | @code{c-hanging-semi&comma-criteria}, | |
2268 | @code{c-backslash-column}, | |
2269 | @code{c-special-indent-hook}, | |
2270 | @code{c-label-minimum-indentation}, and | |
2271 | @code{c-offsets-alist}. | |
6bf7aab6 DL |
2272 | |
2273 | @menu | |
2274 | * Built-in Styles:: | |
2275 | * Adding Styles:: | |
2276 | * File Styles:: | |
2277 | @end menu | |
2278 | ||
2279 | ||
2280 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
d7bd46ed GM |
2281 | @node Built-in Styles, Adding Styles, , Styles |
2282 | @comment node-name, next, previous, up | |
2283 | @subsection Built-in Styles | |
2284 | @cindex built-in styles | |
6bf7aab6 DL |
2285 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
2286 | ||
2287 | If you're lucky, one of @ccmode{}'s built-in styles might be just | |
2288 | what you're looking for. These include: | |
2289 | ||
2290 | @itemize @bullet | |
2291 | @cindex GNU style | |
2292 | @item | |
d7bd46ed GM |
2293 | @code{gnu} --- Coding style blessed by the Free Software Foundation |
2294 | for C code in GNU programs. | |
6bf7aab6 DL |
2295 | |
2296 | @cindex K&R style | |
2297 | @item | |
2298 | @code{k&r} --- The classic Kernighan and Ritchie style for C code. | |
2299 | ||
2300 | @cindex BSD style | |
2301 | @item | |
2302 | @code{bsd} --- Also known as ``Allman style'' after Eric Allman. | |
2303 | ||
2304 | @cindex Whitesmith style | |
2305 | @item | |
2306 | @code{whitesmith} --- Popularized by the examples that came with | |
2307 | Whitesmiths C, an early commercial C compiler. | |
2308 | ||
2309 | @cindex Stroustrup style | |
2310 | @item | |
2311 | @code{stroustrup} --- The classic Stroustrup style for C++ code. | |
2312 | ||
2313 | @cindex Ellemtel style | |
2314 | @item | |
2315 | @code{ellemtel} --- Popular C++ coding standards as defined by | |
94cae5a8 | 2316 | ``Programming in C++, Rules and Recommendations,'' Erik Nyquist and Mats |
d7bd46ed GM |
2317 | Henricson, Ellemtel@footnote{This document is available at |
2318 | @uref{http://www.doc.ic.ac.uk/lab/cplus/c++.rules/} among other | |
2319 | places.}. | |
6bf7aab6 DL |
2320 | |
2321 | @cindex Linux style | |
2322 | @item | |
94cae5a8 | 2323 | @code{linux} --- C coding standard for Linux (the kernel). |
6bf7aab6 DL |
2324 | |
2325 | @cindex Python style | |
2326 | @item | |
2327 | @code{python} --- C coding standard for Python extension | |
2328 | modules@footnote{Python is a high level scripting language with a C/C++ | |
2329 | foreign function interface. For more information, see | |
d7bd46ed | 2330 | @uref{http://www.python.org/}.}. |
6bf7aab6 DL |
2331 | |
2332 | @cindex Java style | |
d7bd46ed | 2333 | @findex java-mode |
6bf7aab6 | 2334 | @item |
cb7f2e96 GM |
2335 | @code{java} --- The style for editing Java code. Note that the default |
2336 | value for @code{c-default-style} installs this style when you enter | |
2337 | @code{java-mode}. | |
6bf7aab6 DL |
2338 | |
2339 | @cindex User style | |
d7bd46ed GM |
2340 | @item |
2341 | @code{user} --- This is a special style for several reasons. First, the | |
2342 | @ccmode{} customizations you do by using either the Customization | |
2343 | interface, or by writing @code{setq}'s at the top level of your | |
2344 | @file{.emacs} file, will be captured in the @code{user} style. Also, | |
2345 | all other styles implicitly inherit their settings from @code{user} | |
2346 | style. This means that for any styles you add via @code{c-add-style} | |
2347 | (@pxref{Adding Styles}) you need only define the differences between | |
2348 | your new style and @code{user} style. | |
2349 | ||
2350 | @end itemize | |
2351 | ||
6bf7aab6 DL |
2352 | @vindex c-default-style |
2353 | @vindex default-style (c-) | |
d7bd46ed GM |
2354 | The default style in all newly created buffers is @code{gnu}, but you |
2355 | can change this by setting variable @code{c-default-style}. Although | |
2356 | the @code{user} style is not the default style, any style variable | |
2357 | settings you do with the Customization interface or on the top level in | |
2358 | your @file{.emacs} file will by default override the style system, so | |
2359 | you don't need to set @code{c-default-style} to @code{user} to see the | |
2360 | effect of these settings. | |
2361 | ||
2362 | @code{c-default-style} takes either a style name string, or an | |
2363 | association list of major mode symbols to style names. Thus you can | |
2364 | control exactly which default style is used for which @ccmode{} language | |
2365 | mode. Here are the rules: | |
2366 | ||
2367 | @vindex c-style-alist | |
2368 | @vindex style-alist (c-) | |
2369 | @vindex c-mode-common-hook | |
2370 | @vindex mode-common-hook (c-) | |
2371 | @enumerate | |
6bf7aab6 | 2372 | @item |
d7bd46ed GM |
2373 | When @code{c-default-style} is a string, it must be an existing style |
2374 | name as found in @code{c-style-alist}. This style is then used for all | |
cb7f2e96 | 2375 | modes. |
6bf7aab6 | 2376 | |
d7bd46ed GM |
2377 | @item |
2378 | When @code{c-default-style} is an association list, the current major | |
2379 | mode is looked up to find a style name string. In this case, this style | |
2380 | is always used exactly as specified and an error will occur if the named | |
2381 | style does not exist. | |
2382 | ||
2383 | @item | |
2384 | If @code{c-default-style} is an association list, but the current major | |
2385 | mode isn't found, then the special symbol @samp{other} is looked up. If | |
2386 | this value is found, the associated style is used. | |
2387 | ||
2388 | @item | |
2389 | If @samp{other} is not found, then the @samp{gnu} style is used. | |
2390 | ||
2391 | @item | |
2392 | In all cases, the style described in @code{c-default-style} is installed | |
2393 | @emph{before} the language hooks are run, so you can always override | |
2394 | this setting by including an explicit call to @code{c-set-style} in your | |
2395 | language mode hook, or in @code{c-mode-common-hook}. | |
2396 | ||
2397 | @end enumerate | |
6bf7aab6 DL |
2398 | |
2399 | @findex c-set-style | |
2400 | @findex set-style (c-) | |
2401 | @kindex C-c . | |
2402 | If you'd like to experiment with these built-in styles you can simply | |
2403 | type the following in a @ccmode{} buffer: | |
2404 | @example | |
2405 | @group | |
2406 | ||
2407 | @kbd{C-c . @var{STYLE-NAME} RET} | |
2408 | ||
2409 | @end group | |
2410 | @end example | |
2411 | @noindent | |
2412 | @kbd{C-c .} runs the command @code{c-set-style}. Note that all style | |
2413 | names are case insensitive, even the ones you define. | |
2414 | ||
2415 | Setting a style in this way does @emph{not} automatically re-indent your | |
2416 | file. For commands that you can use to view the effect of your changes, | |
2417 | see @ref{Commands}. | |
2418 | ||
6bf7aab6 DL |
2419 | @vindex c-indentation-style |
2420 | @vindex indentation-style (c-) | |
d7bd46ed GM |
2421 | Note that for BOCM compatibility, @samp{gnu} is the default style, and |
2422 | any non-style based customizations you make (i.e. in | |
2423 | @code{c-mode-common-hook} in your @file{.emacs} file) will be based on | |
2424 | @samp{gnu} style unless you set @code{c-default-style} or do a | |
2425 | @code{c-set-style} as the first thing in your hook. The variable | |
2426 | @code{c-indentation-style} always contains the buffer's current style | |
2427 | name, as a string. | |
6bf7aab6 DL |
2428 | |
2429 | ||
2430 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
d7bd46ed GM |
2431 | @node Adding Styles, File Styles, Built-in Styles, Styles |
2432 | @comment node-name, next, previous, up | |
2433 | @subsection Adding Styles | |
2434 | @cindex adding styles | |
6bf7aab6 DL |
2435 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
2436 | ||
2437 | @vindex c-style-alist | |
2438 | @vindex style-alist (c-) | |
2439 | @findex c-add-style | |
2440 | @findex add-style (c-) | |
2441 | If none of the built-in styles is appropriate, you'll probably want to | |
2442 | add a new @dfn{style definition}. Styles are kept in the | |
2443 | @code{c-style-alist} variable, but you should never modify this variable | |
2444 | directly. Instead, @ccmode{} provides the function | |
2445 | @code{c-add-style} that you can use to easily add new styles or change | |
2446 | existing styles. This function takes two arguments, a @var{stylename} | |
2447 | string, and an association list @var{description} of style | |
2448 | customizations. If @var{stylename} is not already in | |
2449 | @code{c-style-alist}, the new style is added, otherwise the style is | |
2450 | changed to the new @var{description}. | |
2451 | This function also takes an optional third argument, which if | |
2452 | non-@code{nil}, automatically applies the new style to the current | |
2453 | buffer. | |
2454 | ||
2455 | @comment TBD: The next paragraph is bogus. I really need to better | |
2456 | @comment document adding styles, including setting up inherited styles. | |
2457 | ||
2458 | The sample @file{.emacs} file provides a concrete example of how a new | |
2459 | style can be added and automatically set. @xref{Sample .emacs File}. | |
2460 | ||
6bf7aab6 | 2461 | |
d7bd46ed GM |
2462 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
2463 | @node File Styles, , Adding Styles, Styles | |
2464 | @comment node-name, next, previous, up | |
2465 | @subsection File Styles | |
2466 | @cindex file styles | |
6bf7aab6 DL |
2467 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
2468 | ||
2469 | @cindex local variables | |
2470 | ||
2471 | The Emacs manual describes how you can customize certain variables on a | |
2472 | per-file basis by including a @dfn{Local Variable} block at the end of | |
2473 | the file. So far, you've only seen a functional interface to @ccmode{} | |
2474 | customization, which is highly inconvenient for use in a Local Variable | |
2475 | block. @ccmode{} provides two variables that make it easier for you to | |
2476 | customize your style on a per-file basis. | |
6bf7aab6 DL |
2477 | |
2478 | @vindex c-file-style | |
2479 | @vindex file-style (c-) | |
2480 | @vindex c-file-offsets | |
2481 | @vindex file-offsets (c-) | |
2482 | ||
2483 | The variable @code{c-file-style} can be set to a style name string. | |
2484 | When the file is visited, @ccmode{} will automatically set the | |
2485 | file's style to this style using @code{c-set-style}. | |
2486 | ||
6bf7aab6 DL |
2487 | Another variable, @code{c-file-offsets}, takes an association list |
2488 | similar to what is allowed in @code{c-offsets-alist}. When the file is | |
d7bd46ed | 2489 | visited, @ccmode{} will automatically institute these offsets using |
6bf7aab6 DL |
2490 | @code{c-set-offset}. |
2491 | ||
2492 | Note that file style settings (i.e. @code{c-file-style}) are applied | |
2493 | before file offset settings (i.e. @code{c-file-offsets}). Also, if | |
2494 | either of these are set in a file's local variable section, all the | |
2495 | style variable values are made local to that buffer. | |
2496 | ||
2497 | ||
2498 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
d7bd46ed GM |
2499 | @node Advanced Customizations, , Styles, Customizing Indentation |
2500 | @comment node-name, next, previous, up | |
2501 | @section Advanced Customizations | |
6bf7aab6 DL |
2502 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
2503 | ||
2504 | @vindex c-style-alist | |
2505 | @vindex style-alist (c-) | |
6bf7aab6 DL |
2506 | For most users, @ccmode{} will support their coding styles with |
2507 | very little need for more advanced customizations. Usually, one of the | |
2508 | standard styles defined in @code{c-style-alist} will do the trick. At | |
2509 | most, perhaps one of the syntactic symbol offsets will need to be | |
2510 | tweaked slightly, or maybe @code{c-basic-offset} will need to be | |
2511 | changed. However, some styles require a more flexible framework for | |
2512 | customization, and one of the real strengths of @ccmode{} is that | |
2513 | the syntactic analysis model provides just such a framework. This allows | |
2514 | you to implement custom indentation calculations for situations not | |
2515 | handled by the mode directly. | |
2516 | ||
6bf7aab6 DL |
2517 | @menu |
2518 | * Custom Indentation Functions:: | |
2519 | * Custom Brace and Colon Hanging:: | |
2520 | * Customizing Semi-colons and Commas:: | |
2521 | * Other Special Indentations:: | |
2522 | @end menu | |
2523 | ||
2524 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
d7bd46ed GM |
2525 | @node Custom Indentation Functions, Custom Brace and Colon Hanging, , Advanced Customizations |
2526 | @comment node-name, next, previous, up | |
2527 | @subsection Custom Indentation Functions | |
2528 | @cindex custom indentation functions | |
6bf7aab6 DL |
2529 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
2530 | ||
d7bd46ed GM |
2531 | The most flexible way to customize @ccmode{} is by writing custom |
2532 | indentation functions, and associating them with specific syntactic | |
2533 | symbols (@pxref{Syntactic Symbols}). @ccmode{} itself uses indentation | |
2534 | functions to provide more sophisticated indentation, for example when | |
2535 | lining up C++ stream operator blocks: | |
6bf7aab6 DL |
2536 | @example |
2537 | @group | |
2538 | ||
2539 | 1: void main(int argc, char**) | |
2540 | 2: @{ | |
2541 | 3: cout << "There were " | |
2542 | 4: << argc | |
2543 | 5: << "arguments passed to the program" | |
2544 | 6: << endl; | |
2545 | 7: @} | |
2546 | ||
2547 | @end group | |
2548 | @end example | |
2549 | ||
2550 | In this example, lines 4 through 6 are assigned the @code{stream-op} | |
2551 | syntactic symbol. Here, @code{stream-op} has an offset of @code{+}, and | |
2552 | with a @code{c-basic-offset} of 2, you can see that lines 4 through 6 | |
2553 | are simply indented two spaces to the right of line 3. But perhaps we'd | |
2554 | like @ccmode{} to be a little more intelligent so that it aligns | |
2555 | all the @samp{<<} symbols in lines 3 through 6. To do this, we have | |
2556 | to write a custom indentation function which finds the column of first | |
2557 | stream operator on the first line of the statement. Here is sample | |
2558 | lisp code implementing this: | |
2559 | @example | |
2560 | @group | |
2561 | ||
2562 | (defun c-lineup-streamop (langelem) | |
2563 | ;; lineup stream operators | |
2564 | (save-excursion | |
2565 | (let* ((relpos (cdr langelem)) | |
2566 | (curcol (progn (goto-char relpos) | |
2567 | (current-column)))) | |
2568 | (re-search-forward "<<\\|>>" (c-point 'eol) 'move) | |
2569 | (goto-char (match-beginning 0)) | |
2570 | (- (current-column) curcol)))) | |
2571 | ||
2572 | @end group | |
2573 | @end example | |
2574 | @noindent | |
d7bd46ed GM |
2575 | Indentation functions take a single argument, which is a syntactic |
2576 | component cons cell (@pxref{Syntactic Analysis}). The function returns | |
2577 | an integer offset value that will be added to the running total | |
2578 | indentation for the line. Note that what actually gets returned is the | |
2579 | difference between the column that the first stream operator is on, and | |
2580 | the column of the buffer relative position passed in the function's | |
2581 | argument. Remember that @ccmode{} automatically adds in the column of | |
2582 | the component's relative buffer position and we don't the column offset | |
2583 | added in twice. | |
2584 | ||
2585 | The function should return @code{nil} if it's used in a situation where | |
2586 | it doesn't want to do any decision. If the function is used in a list | |
2587 | expression (@pxref{Customizing Indentation}), that will cause @ccmode{} | |
2588 | to go on and check the next entry in the list. | |
6bf7aab6 DL |
2589 | |
2590 | @cindex stream-op syntactic symbol | |
2591 | @findex c-lineup-streamop | |
2592 | @findex lineup-streamop (c-) | |
2593 | Now, to associate the function @code{c-lineup-streamop} with the | |
2594 | @code{stream-op} syntactic symbol, we can add something like the | |
2595 | following to our @code{c++-mode-hook}@footnote{It probably makes more | |
2596 | sense to add this to @code{c++-mode-hook} than @code{c-mode-common-hook} | |
d7bd46ed | 2597 | since stream operators are only relevant for C++.}: |
6bf7aab6 DL |
2598 | @example |
2599 | ||
2600 | (c-set-offset 'stream-op 'c-lineup-streamop) | |
2601 | ||
2602 | @end example | |
2603 | ||
6bf7aab6 DL |
2604 | Now the function looks like this after re-indenting (using @kbd{C-c |
2605 | C-q}): | |
2606 | @example | |
2607 | @group | |
2608 | ||
2609 | 1: void main(int argc, char**) | |
2610 | 2: @{ | |
2611 | 3: cout << "There were " | |
2612 | 4: << argc | |
d7bd46ed | 2613 | 5: << " arguments passed to the program" |
6bf7aab6 DL |
2614 | 6: << endl; |
2615 | 7: @} | |
2616 | ||
2617 | @end group | |
2618 | @end example | |
2619 | ||
6bf7aab6 DL |
2620 | Custom indentation functions can be as simple or as complex as you like, |
2621 | and any syntactic symbol that appears in @code{c-offsets-alist} can have | |
d7bd46ed | 2622 | a custom indentation function associated with it. |
6bf7aab6 | 2623 | |
d7bd46ed GM |
2624 | @ccmode{} comes with an extensive set of predefined indentation |
2625 | functions, not all of which are used by the default styles. So there's | |
2626 | a good chance the function you want already exists. @xref{Indentation | |
2627 | Functions}, for a list of them. If you have written an indentation | |
2628 | function that you think is generally useful, you're very welcome to | |
2629 | contribute it; please contact @email{bug-cc-mode@@gnu.org}. | |
6bf7aab6 | 2630 | |
6bf7aab6 DL |
2631 | |
2632 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
d7bd46ed GM |
2633 | @node Custom Brace and Colon Hanging, Customizing Semi-colons and Commas, Custom Indentation Functions, Advanced Customizations |
2634 | @comment node-name, next, previous, up | |
2635 | @subsection Custom Brace and Colon Hanging | |
6bf7aab6 DL |
2636 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
2637 | ||
2638 | @vindex c-hanging-braces-alist | |
2639 | @vindex hanging-braces-alist (c-) | |
2640 | Syntactic symbols aren't the only place where you can customize | |
2641 | @ccmode{} with the lisp equivalent of callback functions. Brace | |
2642 | ``hanginess'' can also be determined by custom functions associated with | |
d7bd46ed | 2643 | syntactic symbols on the @code{c-hanging-braces-alist} style variable. |
6bf7aab6 | 2644 | Remember that @var{ACTION}'s are typically a list containing some |
d7bd46ed GM |
2645 | combination of the symbols @code{before} and @code{after} |
2646 | (@pxref{Hanging Braces}). However, an @var{ACTION} can also be a | |
2647 | function which gets called when a brace matching that syntactic symbol | |
2648 | is entered. | |
6bf7aab6 DL |
2649 | |
2650 | @cindex customizing brace hanging | |
2651 | These @var{ACTION} functions are called with two arguments: the | |
2652 | syntactic symbol for the brace, and the buffer position at which the | |
2653 | brace was inserted. The @var{ACTION} function is expected to return a | |
d7bd46ed GM |
2654 | list containing some combination of @code{before} and @code{after}, |
2655 | including neither of them (i.e. @code{nil}). This return value has the | |
2656 | normal brace hanging semantics. | |
6bf7aab6 DL |
2657 | |
2658 | As an example, @ccmode{} itself uses this feature to dynamically | |
2659 | determine the hanginess of braces which close ``do-while'' | |
2660 | constructs: | |
2661 | @example | |
2662 | @group | |
2663 | ||
2664 | void do_list( int count, char** atleast_one_string ) | |
2665 | @{ | |
2666 | int i=0; | |
2667 | do @{ | |
2668 | handle_string( atleast_one_string[i] ); | |
2669 | i++; | |
2670 | @} while( i < count ); | |
2671 | @} | |
2672 | ||
2673 | @end group | |
2674 | @end example | |
2675 | ||
2676 | @findex c-snug-do-while | |
2677 | @findex snug-do-while (c-) | |
2678 | @ccmode{} assigns the @code{block-close} syntactic symbol to the | |
2679 | brace that closes the @code{do} construct, and normally we'd like the | |
2680 | line that follows a @code{block-close} brace to begin on a separate | |
2681 | line. However, with ``do-while'' constructs, we want the | |
2682 | @code{while} clause to follow the closing brace. To do this, we | |
2683 | associate the @code{block-close} symbol with the @var{ACTION} function | |
2684 | @code{c-snug-do-while}: | |
2685 | @example | |
2686 | ||
2687 | (defun c-snug-do-while (syntax pos) | |
2688 | "Dynamically calculate brace hanginess for do-while statements. | |
2689 | Using this function, `while' clauses that end a `do-while' block will | |
2690 | remain on the same line as the brace that closes that block. | |
2691 | ||
2692 | See `c-hanging-braces-alist' for how to utilize this function as an | |
2693 | ACTION associated with `block-close' syntax." | |
2694 | (save-excursion | |
2695 | (let (langelem) | |
2696 | (if (and (eq syntax 'block-close) | |
2697 | (setq langelem (assq 'block-close c-syntactic-context)) | |
2698 | (progn (goto-char (cdr langelem)) | |
2699 | (if (= (following-char) ?@{) | |
2700 | (forward-sexp -1)) | |
2701 | (looking-at "\\<do\\>[^_]"))) | |
2702 | '(before) | |
2703 | '(before after))))) | |
2704 | ||
2705 | @end example | |
2706 | ||
2707 | This function simply looks to see if the brace closes a ``do-while'' | |
2708 | clause and if so, returns the list @samp{(before)} indicating | |
2709 | that a newline should be inserted before the brace, but not after it. | |
2710 | In all other cases, it returns the list @samp{(before after)} so | |
2711 | that the brace appears on a line by itself. | |
2712 | ||
2713 | @vindex c-syntactic-context | |
2714 | @vindex syntactic-context (c-) | |
2715 | During the call to the brace hanging @var{ACTION} function, the variable | |
2716 | @code{c-syntactic-context} is bound to the full syntactic analysis list. | |
2717 | ||
2718 | @cindex customizing colon hanging | |
2719 | @vindex c-hanging-colon-alist | |
2720 | @vindex hanging-colon-alist (c-) | |
2721 | Note that for symmetry, colon hanginess should be customizable by | |
2722 | allowing function symbols as @var{ACTION}s on the | |
d7bd46ed GM |
2723 | @code{c-hanging-colon-alist} style variable. Since no use has actually |
2724 | been found for this feature, it isn't currently implemented! | |
6bf7aab6 | 2725 | |
6bf7aab6 | 2726 | |
d7bd46ed GM |
2727 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
2728 | @node Customizing Semi-colons and Commas, Other Special Indentations, Custom Brace and Colon Hanging, Advanced Customizations | |
2729 | @comment node-name, next, previous, up | |
2730 | @subsection Customizing Semi-colons and Commas | |
2731 | @cindex customizing semi-colons and commas | |
6bf7aab6 DL |
2732 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
2733 | ||
6bf7aab6 DL |
2734 | @vindex c-hanging-semi&comma-criteria |
2735 | @vindex hanging-semi&comma-criteria (c-) | |
2736 | You can also customize the insertion of newlines after semi-colons and | |
d7bd46ed GM |
2737 | commas, when the auto-newline minor mode is enabled (@pxref{Minor |
2738 | Modes}). This is controlled by the style variable | |
6bf7aab6 DL |
2739 | @code{c-hanging-semi&comma-criteria}, which contains a list of functions |
2740 | that are called in the order they appear. Each function is called with | |
2741 | zero arguments, and is expected to return one of the following values: | |
2742 | ||
2743 | @itemize @bullet | |
2744 | @item | |
2745 | non-@code{nil} --- A newline is inserted, and no more functions from the | |
2746 | list are called. | |
2747 | ||
2748 | @item | |
2749 | @code{stop} --- No more functions from the list are called, but no | |
2750 | newline is inserted. | |
2751 | ||
2752 | @item | |
2753 | @code{nil} --- No determination is made, and the next function in the | |
2754 | list is called. | |
2755 | ||
2756 | @end itemize | |
2757 | ||
2758 | If every function in the list is called without a determination being | |
2759 | made, then no newline is added. The default value for this variable is a | |
2760 | list containing a single function which inserts newlines only after | |
2761 | semi-colons which do not appear inside parenthesis lists (i.e. those | |
2762 | that separate @code{for}-clause statements). | |
2763 | ||
2764 | @findex c-semi&comma-no-newlines-before-nonblanks | |
2765 | @findex semi&comma-no-newlines-before-nonblanks (c-) | |
2766 | Here's an example of a criteria function, provided by @ccmode{}, that | |
2767 | will prevent newlines from being inserted after semicolons when there is | |
2768 | a non-blank following line. Otherwise, it makes no determination. To | |
2769 | use, add this to the front of the @code{c-hanging-semi&comma-criteria} | |
2770 | list. | |
2771 | ||
2772 | @example | |
2773 | @group | |
2774 | ||
2775 | (defun c-semi&comma-no-newlines-before-nonblanks () | |
2776 | (save-excursion | |
2777 | (if (and (eq last-command-char ?\;) | |
2778 | (zerop (forward-line 1)) | |
2779 | (not (looking-at "^[ \t]*$"))) | |
2780 | 'stop | |
2781 | nil))) | |
2782 | ||
2783 | @end group | |
2784 | @end example | |
2785 | ||
2786 | @findex c-semi&comma-inside-parenlist | |
2787 | @findex c-semi&comma-no-newlines-for-oneline-inliners | |
2788 | @findex semi&comma-inside-parenlist (c-) | |
2789 | @findex semi&comma-no-newlines-for-oneline-inliners (c-) | |
d7bd46ed GM |
2790 | The function @code{c-semi&comma-inside-parenlist} is what prevents |
2791 | newlines from being inserted inside the parenthesis list of @code{for} | |
2792 | statements. In addition to | |
6bf7aab6 DL |
2793 | @code{c-semi&comma-no-newlines-before-nonblanks} described above, |
2794 | @ccmode{} also comes with the criteria function | |
2795 | @code{c-semi&comma-no-newlines-for-oneline-inliners}, which suppresses | |
2796 | newlines after semicolons inside one-line inline method definitions | |
2797 | (i.e. in C++ or Java). | |
2798 | ||
6bf7aab6 | 2799 | |
d7bd46ed GM |
2800 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
2801 | @node Other Special Indentations, , Customizing Semi-colons and Commas, Advanced Customizations | |
2802 | @comment node-name, next, previous, up | |
2803 | @subsection Other Special Indentations | |
6bf7aab6 DL |
2804 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
2805 | ||
2806 | @vindex c-label-minimum-indentation | |
2807 | @vindex label-minimum-indentation (c-) | |
d7bd46ed | 2808 | In @samp{gnu} style (@pxref{Built-in Styles}), a minimum indentation |
6bf7aab6 | 2809 | is imposed on lines inside top-level constructs. This minimum |
d7bd46ed | 2810 | indentation is controlled by the style variable |
6bf7aab6 DL |
2811 | @code{c-label-minimum-indentation}. The default value for this variable |
2812 | is 1. | |
2813 | ||
2814 | @vindex c-special-indent-hook | |
2815 | @vindex special-indent-hook (c-) | |
d7bd46ed GM |
2816 | One other customization variable is available in @ccmode{}: The style |
2817 | variable @code{c-special-indent-hook}. This is a standard hook variable | |
2818 | that is called after every line is indented by @ccmode{}. You can use | |
2819 | it to do any special indentation or line adjustments your style | |
2820 | dictates, such as adding extra indentation to constructors or destructor | |
6bf7aab6 DL |
2821 | declarations in a class definition, etc. Note however, that you should |
2822 | not change point or mark inside your @code{c-special-indent-hook} | |
2823 | functions (i.e. you'll probably want to wrap your function in a | |
2824 | @code{save-excursion}). | |
2825 | ||
2826 | Setting @code{c-special-indent-hook} in your style definition is handled | |
2827 | slightly differently than other variables. In your style definition, | |
2828 | you should set the value for | |
2829 | @code{c-special-indent-hook} to a function or list of functions, which | |
2830 | will be appended to @code{c-special-indent-hook} using @code{add-hook}. | |
2831 | That way, the current setting for the buffer local value of | |
2832 | @code{c-special-indent-hook} won't be overridden. | |
2833 | ||
2834 | @kindex M-; | |
2835 | @findex indent-for-comment | |
2836 | @vindex c-indent-comments-syntactically-p | |
2837 | @vindex indent-comments-syntactically-p (c-) | |
2838 | @vindex comment-column | |
6bf7aab6 DL |
2839 | Normally, the standard Emacs command @kbd{M-;} |
2840 | (@code{indent-for-comment}) will indent comment only lines to | |
2841 | @code{comment-column}. Some users however, prefer that @kbd{M-;} act | |
2842 | just like @kbd{TAB} for purposes of indenting comment-only lines; | |
2843 | i.e. they want the comments to always indent as they would for normal | |
2844 | code, regardless of whether @kbd{TAB} or @kbd{M-;} were used. This | |
2845 | behavior is controlled by the variable | |
2846 | @code{c-indent-comments-syntactically-p}. When @code{nil} (the | |
2847 | default), @kbd{M-;} indents comment-only lines to @code{comment-column}, | |
2848 | otherwise, they are indented just as they would be if @kbd{TAB} were | |
2849 | typed. | |
2850 | ||
d7bd46ed GM |
2851 | Note that this has no effect for comment lines that are inserted with |
2852 | @kbd{M-;} at the end of regular code lines. These comments will always | |
2853 | start at @code{comment-column}. | |
2854 | ||
6bf7aab6 | 2855 | |
d7bd46ed GM |
2856 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
2857 | @node Syntactic Symbols, Indentation Functions, Customizing Indentation, Top | |
2858 | @comment node-name, next, previous, up | |
2859 | @chapter Syntactic Symbols | |
2860 | @cindex syntactic symbols | |
6bf7aab6 DL |
2861 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
2862 | ||
2863 | @vindex c-offsets-alist | |
2864 | @vindex offsets-alist (c-) | |
6bf7aab6 | 2865 | Here is a complete list of the recognized syntactic symbols as described |
d7bd46ed GM |
2866 | in the @code{c-offsets-alist} style variable, along with a brief |
2867 | description. More detailed descriptions follow. | |
6bf7aab6 | 2868 | |
d7bd46ed GM |
2869 | @table @code |
2870 | @item string | |
2871 | Inside a multi-line string. | |
2872 | @item c | |
2873 | Inside a multi-line C style block comment. | |
2874 | @item defun-open | |
2875 | Brace that opens a top-level function definition. | |
2876 | @item defun-close | |
2877 | Brace that closes a top-level function definition. | |
2878 | @item defun-block-intro | |
2879 | The first line in a top-level defun. | |
2880 | @item class-open | |
2881 | Brace that opens a class definition. | |
2882 | @item class-close | |
2883 | Brace that closes a class definition. | |
2884 | @item inline-open | |
2885 | Brace that opens an in-class inline method. | |
2886 | @item inline-close | |
2887 | Brace that closes an in-class inline method. | |
2888 | @item func-decl-cont | |
2889 | The region between a function definition's argument list and the | |
2890 | function opening brace (excluding K&R argument declarations). In C, you | |
2891 | cannot put anything but whitespace and comments in this region, however | |
2892 | in C++ and Java, @code{throws} declarations and other things can appear | |
2893 | here. | |
2894 | @item knr-argdecl-intro | |
2895 | First line of a K&R C argument declaration. | |
2896 | @item knr-argdecl | |
2897 | Subsequent lines in a K&R C argument declaration. | |
2898 | @item topmost-intro | |
2899 | The first line in a ``topmost'' definition. | |
2900 | @item topmost-intro-cont | |
2901 | Topmost definition continuation lines. | |
2902 | @item member-init-intro | |
2903 | First line in a member initialization list. | |
2904 | @item member-init-cont | |
2905 | Subsequent member initialization list lines. | |
2906 | @item inher-intro | |
2907 | First line of a multiple inheritance list. | |
2908 | @item inher-cont | |
2909 | Subsequent multiple inheritance lines. | |
2910 | @item block-open | |
2911 | Statement block open brace. | |
2912 | @item block-close | |
2913 | Statement block close brace. | |
2914 | @item brace-list-open | |
2915 | Open brace of an enum or static array list. | |
2916 | @item brace-list-close | |
2917 | Close brace of an enum or static array list. | |
2918 | @item brace-list-intro | |
2919 | First line in an enum or static array list. | |
2920 | @item brace-list-entry | |
2921 | Subsequent lines in an enum or static array list. | |
2922 | @item brace-entry-open | |
2923 | Subsequent lines in an enum or static array list where the line begins | |
2924 | with an open brace. | |
2925 | @item statement | |
2926 | A statement. | |
2927 | @item statement-cont | |
2928 | A continuation of a statement. | |
2929 | @item statement-block-intro | |
2930 | The first line in a new statement block. | |
2931 | @item statement-case-intro | |
2932 | The first line in a case block. | |
2933 | @item statement-case-open | |
2934 | The first line in a case block that starts with a brace. | |
2935 | @item substatement | |
2936 | The first line after a conditional or loop construct. | |
2937 | @item substatement-open | |
2938 | The brace that opens a substatement block. | |
2939 | @item case-label | |
2940 | A @code{case} or @code{default} label. | |
2941 | @item access-label | |
2942 | C++ access control label. | |
2943 | @item label | |
2944 | Any non-special C label. | |
2945 | @item do-while-closure | |
2946 | The @code{while} line that ends a @code{do}-@code{while} construct. | |
2947 | @item else-clause | |
2948 | The @code{else} line of an @code{if}-@code{else} construct. | |
2949 | @item catch-clause | |
2950 | The @code{catch} or @code{finally} (in Java) line of a | |
2951 | @code{try}-@code{catch} construct. | |
2952 | @item comment-intro | |
2953 | A line containing only a comment introduction. | |
2954 | @item arglist-intro | |
2955 | The first line in an argument list. | |
2956 | @item arglist-cont | |
2957 | Subsequent argument list lines when no arguments follow on the same line | |
6b1f5814 | 2958 | as the arglist opening paren. |
d7bd46ed GM |
2959 | @item arglist-cont-nonempty |
2960 | Subsequent argument list lines when at least one argument follows on the | |
2961 | same line as the arglist opening paren. | |
2962 | @item arglist-close | |
2963 | The solo close paren of an argument list. | |
2964 | @item stream-op | |
2965 | Lines continuing a stream operator (C++ only). | |
2966 | @item inclass | |
2967 | The line is nested inside a class definition. | |
2968 | @item cpp-macro | |
2969 | The start of a C preprocessor macro definition. | |
2970 | @item cpp-macro-cont | |
2971 | Subsequent lines of a multi-line C preprocessor macro definition. | |
2972 | @item friend | |
2973 | A C++ friend declaration. | |
2974 | @item objc-method-intro | |
2975 | The first line of an Objective-C method. definition. | |
2976 | @item objc-method-args-cont | |
2977 | Lines continuing an Objective-C method. definition | |
2978 | @item objc-method-call-cont | |
2979 | Lines continuing an Objective-C method call. | |
2980 | @item extern-lang-open | |
2981 | Brace that opens an external language block. | |
2982 | @item extern-lang-close | |
2983 | Brace that closes an external language block. | |
2984 | @item inextern-lang | |
2985 | Analogous to @code{inclass} syntactic symbol, but used inside external | |
2986 | language blocks (e.g. @code{extern "C" @{}). | |
2987 | @item namespace-open | |
2988 | Brace that opens a C++ namespace block. | |
2989 | @item namespace-close | |
2990 | Brace that closes a C++ namespace block. | |
2991 | @item innamespace | |
2992 | Analogous to @code{inextern-lang} syntactic symbol, but used inside C++ | |
2993 | namespace blocks. | |
2994 | @item template-args-cont | |
2995 | C++ template argument list continuations. | |
2996 | @item inlambda | |
2997 | Analogous to @code{inclass} syntactic symbol, but used inside lambda | |
2998 | (i.e. anonymous) functions. Only used in Pike mode. | |
2999 | @item lambda-intro-cont | |
3000 | Lines continuing the header of a lambda function, i.e. between the | |
3001 | @code{lambda} keyword and the function body. Only used in Pike mode. | |
3002 | @item inexpr-statement | |
3003 | A statement block inside an expression. The gcc C extension of this is | |
3004 | recognized. It's also used for the special functions that takes a | |
3005 | statement block as an argument in Pike. | |
3006 | @item inexpr-class | |
3007 | A class definition inside an expression. This is used for anonymous | |
3008 | classes in Java. It's also used for anonymous array initializers in | |
3009 | Java. | |
3010 | @end table | |
6bf7aab6 DL |
3011 | |
3012 | @cindex -open syntactic symbols | |
3013 | @cindex -close syntactic symbols | |
3014 | Most syntactic symbol names follow a general naming convention. When a | |
3015 | line begins with an open or close brace, the syntactic symbol will | |
3016 | contain the suffix @code{-open} or @code{-close} respectively. | |
3017 | ||
3018 | @cindex -intro syntactic symbols | |
3019 | @cindex -cont syntactic symbols | |
3020 | @cindex -block-intro syntactic symbols | |
3021 | Usually, a distinction is made between the first line that introduces a | |
3022 | construct and lines that continue a construct, and the syntactic symbols | |
3023 | that represent these lines will contain the suffix @code{-intro} or | |
3024 | @code{-cont} respectively. As a sub-classification of this scheme, a | |
3025 | line which is the first of a particular brace block construct will | |
3026 | contain the suffix @code{-block-intro}. | |
3027 | ||
6bf7aab6 DL |
3028 | Let's look at some examples to understand how this works. Remember that |
3029 | you can check the syntax of any line by using @kbd{C-c C-s}. | |
3030 | @example | |
3031 | @group | |
3032 | ||
3033 | 1: void | |
3034 | 2: swap( int& a, int& b ) | |
3035 | 3: @{ | |
3036 | 4: int tmp = a; | |
3037 | 5: a = b; | |
3038 | 6: b = tmp; | |
3039 | 7: int ignored = | |
3040 | 8: a + b; | |
3041 | 9: @} | |
3042 | ||
3043 | @end group | |
3044 | @end example | |
3045 | ||
3046 | @cindex topmost-intro syntactic symbol | |
3047 | @cindex topmost-intro-cont syntactic symbol | |
3048 | @cindex defun-open syntactic symbol | |
3049 | @cindex defun-close syntactic symbol | |
3050 | @cindex defun-block-intro syntactic symbol | |
3051 | Line 1 shows a @code{topmost-intro} since it is the first line that | |
3052 | introduces a top-level construct. Line 2 is a continuation of the | |
3053 | top-level construct introduction so it has the syntax | |
3054 | @code{topmost-intro-cont}. Line 3 shows a @code{defun-open} since it is | |
d7bd46ed GM |
3055 | the brace that opens a top-level function definition. Line 9 is the |
3056 | corresponding | |
6bf7aab6 DL |
3057 | @code{defun-close} since it contains the brace that closes the top-level |
3058 | function definition. Line 4 is a @code{defun-block-intro}, i.e. it is | |
3059 | the first line of a brace-block, enclosed in a | |
3060 | top-level function definition. | |
3061 | ||
3062 | @cindex statement syntactic symbol | |
3063 | @cindex statement-cont syntactic symbol | |
3064 | Lines 5, 6, and 7 are all given @code{statement} syntax since there | |
3065 | isn't much special about them. Note however that line 8 is given | |
3066 | @code{statement-cont} syntax since it continues the statement begun | |
3067 | on the previous line. | |
3068 | ||
3069 | Here's another example, which illustrates some C++ class syntactic | |
3070 | symbols: | |
3071 | @example | |
3072 | @group | |
3073 | ||
3074 | 1: class Bass | |
3075 | 2: : public Guitar, | |
3076 | 3: public Amplifiable | |
3077 | 4: @{ | |
3078 | 5: public: | |
3079 | 6: Bass() | |
3080 | 7: : eString( new BassString( 0.105 )), | |
3081 | 8: aString( new BassString( 0.085 )), | |
3082 | 9: dString( new BassString( 0.065 )), | |
3083 | 10: gString( new BassString( 0.045 )) | |
3084 | 11: @{ | |
3085 | 12: eString.tune( 'E' ); | |
3086 | 13: aString.tune( 'A' ); | |
3087 | 14: dString.tune( 'D' ); | |
3088 | 15: gString.tune( 'G' ); | |
3089 | 16: @} | |
3090 | 17: friend class Luthier; | |
3091 | 18: @} | |
3092 | ||
3093 | @end group | |
3094 | @end example | |
3095 | ||
3096 | @cindex class-open syntactic symbol | |
3097 | @cindex class-close syntactic symbol | |
3098 | As in the previous example, line 1 has the @code{topmost-intro} syntax. | |
3099 | Here however, the brace that opens a C++ class definition on line 4 is | |
3100 | assigned the @code{class-open} syntax. Note that in C++, classes, | |
3101 | structs, and unions are essentially equivalent syntactically (and are | |
3102 | very similar semantically), so replacing the @code{class} keyword in the | |
3103 | example above with @code{struct} or @code{union} would still result in a | |
3104 | syntax of @code{class-open} for line 4 @footnote{This is the case even | |
3105 | for C and Objective-C. For consistency, structs in all supported | |
3106 | languages are syntactically equivalent to classes. Note however that | |
3107 | the keyword @code{class} is meaningless in C and Objective-C.}. | |
3108 | Similarly, line 18 is assigned @code{class-close} syntax. | |
3109 | ||
3110 | @cindex inher-intro syntactic symbol | |
3111 | @cindex inher-cont syntactic symbol | |
3112 | Line 2 introduces the inheritance list for the class so it is assigned | |
3113 | the @code{inher-intro} syntax, and line 3, which continues the | |
3114 | inheritance list is given @code{inher-cont} syntax. | |
3115 | ||
3116 | @cindex access-label syntactic symbol | |
3117 | @cindex inclass syntactic symbol | |
3118 | Hitting @kbd{C-c C-s} on line 5 shows the following analysis: | |
3119 | ||
3120 | @example | |
3121 | @group | |
3122 | ||
d7bd46ed | 3123 | @code{((inclass . 58) (access-label . 67))} |
6bf7aab6 DL |
3124 | |
3125 | @end group | |
3126 | @end example | |
3127 | ||
3128 | @noindent | |
3129 | The primary syntactic symbol for this line is @code{access-label} as | |
3130 | this a label keyword that specifies access protection in C++. However, | |
3131 | because this line is also a top-level construct inside a class | |
3132 | definition, the analysis actually shows two syntactic symbols. The | |
3133 | other syntactic symbol assigned to this line is @code{inclass}. | |
3134 | Similarly, line 6 is given both @code{inclass} and @code{topmost-intro} | |
3135 | syntax: | |
3136 | ||
3137 | @example | |
3138 | @group | |
3139 | ||
3140 | @code{((inclass . 58) (topmost-intro . 60))} | |
3141 | ||
3142 | @end group | |
3143 | @end example | |
3144 | ||
3145 | @cindex member-init-intro syntactic symbol | |
3146 | @cindex member-init-cont syntactic symbol | |
3147 | Line 7 introduces a C++ member initialization list and as such is given | |
3148 | @code{member-init-intro} syntax. Note that in this case it is | |
3149 | @emph{not} assigned @code{inclass} since this is not considered a | |
3150 | top-level construct. Lines 8 through 10 are all assigned | |
3151 | @code{member-init-cont} since they continue the member initialization | |
3152 | list started on line 7. | |
3153 | ||
3154 | @cindex in-class inline methods | |
3155 | @cindex inline-open syntactic symbol | |
3156 | @cindex inline-close syntactic symbol | |
3157 | Line 11's analysis is a bit more complicated: | |
3158 | ||
3159 | @example | |
3160 | @group | |
3161 | ||
d7bd46ed | 3162 | @code{((inclass . 58) (inline-open))} |
6bf7aab6 DL |
3163 | |
3164 | @end group | |
3165 | @end example | |
3166 | ||
3167 | This line is assigned a syntax of both @code{inline-open} and | |
3168 | @code{inclass} because it opens an @dfn{in-class} C++ inline method | |
3169 | definition. This is distinct from, but related to, the C++ notion of an | |
3170 | inline function in that its definition occurs inside an enclosing class | |
3171 | definition, which in C++ implies that the function should be inlined. | |
3172 | If though, the definition of the @code{Bass} constructor appeared | |
3173 | outside the class definition, the construct would be given the | |
3174 | @code{defun-open} syntax, even if the keyword @code{inline} appeared | |
3175 | before the method name, as in: | |
3176 | @example | |
3177 | @group | |
3178 | ||
3179 | class Bass | |
3180 | : public Guitar, | |
3181 | public Amplifiable | |
3182 | @{ | |
3183 | public: | |
3184 | Bass(); | |
3185 | @} | |
3186 | ||
3187 | inline | |
3188 | Bass::Bass() | |
3189 | : eString( new BassString( 0.105 )), | |
3190 | aString( new BassString( 0.085 )), | |
3191 | dString( new BassString( 0.065 )), | |
3192 | gString( new BassString( 0.045 )) | |
3193 | @{ | |
3194 | eString.tune( 'E' ); | |
3195 | aString.tune( 'A' ); | |
3196 | dString.tune( 'D' ); | |
3197 | gString.tune( 'G' ); | |
3198 | @} | |
3199 | ||
3200 | @end group | |
3201 | @end example | |
3202 | ||
3203 | @cindex friend syntactic symbol | |
3204 | Returning to the previous example, line 16 is given @code{inline-close} | |
3205 | syntax, while line 12 is given @code{defun-block-open} syntax, and lines | |
3206 | 13 through 15 are all given @code{statement} syntax. Line 17 is | |
3207 | interesting in that its syntactic analysis list contains three | |
3208 | elements: | |
3209 | ||
3210 | @example | |
3211 | ||
3212 | @code{((friend) (inclass . 58) (topmost-intro . 380))} | |
3213 | ||
3214 | @end example | |
3215 | ||
3216 | The @code{friend} syntactic symbol is a modifier that typically does not | |
3217 | have a relative buffer position. | |
3218 | ||
3219 | Template definitions introduce yet another syntactic symbol: | |
3220 | ||
3221 | @example | |
3222 | @group | |
3223 | ||
3224 | 1: ThingManager <int, | |
3225 | 2: Framework::Callback *, | |
3226 | 3: Mutex> framework_callbacks; | |
3227 | ||
3228 | @end group | |
3229 | @end example | |
3230 | ||
3231 | Here, line 1 is analyzed as a @code{topmost-intro}, but lines 2 and 3 | |
3232 | are both analyzed as @code{template-args-cont} lines. | |
3233 | ||
3234 | Here is another (totally contrived) example which illustrates how syntax | |
3235 | is assigned to various conditional constructs: | |
3236 | @example | |
3237 | @group | |
3238 | ||
3239 | 1: void spam( int index ) | |
3240 | 2: @{ | |
3241 | 3: for( int i=0; i<index; i++ ) | |
3242 | 4: @{ | |
3243 | 5: if( i == 10 ) | |
3244 | 6: @{ | |
3245 | 7: do_something_special(); | |
3246 | 8: @} | |
3247 | 9: else | |
3248 | 10: do_something( i ); | |
3249 | 11: @} | |
3250 | 12: do @{ | |
3251 | 13: another_thing( i-- ); | |
3252 | 14: @} | |
3253 | 15: while( i > 0 ); | |
3254 | 16: @} | |
3255 | ||
3256 | ||
3257 | @end group | |
3258 | @end example | |
3259 | ||
3260 | @noindent | |
3261 | Only the lines that illustrate new syntactic symbols will be discussed. | |
3262 | ||
3263 | @cindex substatement-open syntactic symbol | |
3264 | @cindex substatement-block-intro syntactic symbol | |
3265 | @cindex block-close syntactic symbol | |
3266 | Line 4 has a brace which opens a conditional's substatement block. It | |
3267 | is thus assigned @code{substatement-open} syntax, and since line 5 is | |
3268 | the first line in the substatement block, it is assigned | |
3269 | @code{substatement-block-intro} syntax. Lines 6 and 7 are assigned | |
3270 | similar syntax. Line 8 contains the brace that closes the inner | |
3271 | substatement block. It is given the syntax @code{block-close}, | |
3272 | as are lines 11 and 14. | |
3273 | ||
3274 | @cindex else-clause syntactic symbol | |
d7bd46ed | 3275 | @cindex catch-clause syntactic symbol |
6bf7aab6 DL |
3276 | Line 9 is a little different --- since it contains the keyword |
3277 | @code{else} matching the @code{if} statement introduced on line 5, it is | |
d7bd46ed GM |
3278 | given the @code{else-clause} syntax. The @code{try}-@code{catch} |
3279 | constructs in C++ and Java are treated this way too, with the only | |
3280 | difference that the @code{catch}, and in Java also @code{finally}, is | |
3281 | marked with @code{catch-clause}. | |
3282 | ||
3283 | @cindex substatement syntactic symbol | |
3284 | Line 10 is also slightly different. Because @code{else} is considered a | |
3285 | conditional introducing keyword @footnote{The list of conditional | |
3286 | keywords are (in C, C++, Objective-C, Java, and Pike): @code{for}, | |
3287 | @code{if}, @code{do}, @code{else}, @code{while}, and @code{switch}. C++ | |
3288 | and Java have two additional conditional keywords: @code{try} and | |
3289 | @code{catch}. Java also has the @code{finally} and @code{synchronized} | |
3290 | keywords.}, and because the following substatement is not a brace block, | |
3291 | line 10 is assigned the @code{substatement} syntax. | |
6bf7aab6 DL |
3292 | |
3293 | @cindex do-while-closure syntactic symbol | |
3294 | One other difference is seen on line 15. The @code{while} construct | |
3295 | that closes a @code{do} conditional is given the special syntax | |
3296 | @code{do-while-closure} if it appears on a line by itself. Note that if | |
3297 | the @code{while} appeared on the same line as the preceding close brace, | |
3298 | that line would have been assigned @code{block-close} syntax instead. | |
3299 | ||
3300 | Switch statements have their own set of syntactic symbols. Here's an | |
3301 | example: | |
3302 | @example | |
3303 | @group | |
3304 | ||
3305 | 1: void spam( enum Ingredient i ) | |
3306 | 2: @{ | |
3307 | 3: switch( i ) @{ | |
3308 | 4: case Ham: | |
3309 | 5: be_a_pig(); | |
3310 | 6: break; | |
3311 | 7: case Salt: | |
3312 | 8: drink_some_water(); | |
3313 | 9: break; | |
3314 | 10: default: | |
3315 | 11: @{ | |
3316 | 12: what_is_it(); | |
3317 | 13: break; | |
3318 | 14: @} | |
3319 | 15: @} | |
3320 | 14: @} | |
3321 | ||
3322 | @end group | |
3323 | @end example | |
3324 | ||
3325 | @cindex case-label syntactic symbol | |
3326 | @cindex statement-case-intro syntactic symbol | |
3327 | @cindex statement-case-open syntactic symbol | |
3328 | Here, lines 4, 7, and 10 are all assigned @code{case-label} syntax, | |
3329 | while lines 5 and 8 are assigned @code{statement-case-intro}. Line 11 | |
3330 | is treated slightly differently since it contains a brace that opens a | |
3331 | block --- it is given @code{statement-case-open} syntax. | |
3332 | ||
3333 | @cindex brace lists | |
3334 | There are a set of syntactic symbols that are used to recognize | |
3335 | constructs inside of brace lists. A brace list is defined as an | |
3336 | @code{enum} or aggregate initializer list, such as might statically | |
d7bd46ed GM |
3337 | initialize an array of structs. The three special aggregate constructs |
3338 | in Pike, @code{(@{ @})}, @code{([ ])} and @code{(< >)}, are treated as | |
3339 | brace lists too. An example: | |
6bf7aab6 DL |
3340 | @example |
3341 | @group | |
3342 | ||
3343 | 1: static char* ingredients[] = | |
3344 | 2: @{ | |
3345 | 3: "Ham", | |
3346 | 4: "Salt", | |
3347 | 5: NULL | |
3348 | 6: @} | |
3349 | ||
3350 | @end group | |
3351 | @end example | |
3352 | ||
3353 | @cindex brace-list-open syntactic symbol | |
3354 | @cindex brace-list-intro syntactic symbol | |
3355 | @cindex brace-list-close syntactic symbol | |
3356 | @cindex brace-list-entry syntactic symbol | |
3357 | Following convention, line 2 in this example is assigned | |
3358 | @code{brace-list-open} syntax, and line 3 is assigned | |
3359 | @code{brace-list-intro} syntax. Likewise, line 6 is assigned | |
3360 | @code{brace-list-close} syntax. Lines 4 and 5 however, are assigned | |
3361 | @code{brace-list-entry} syntax, as would all subsequent lines in this | |
3362 | initializer list. | |
3363 | ||
d7bd46ed GM |
3364 | @cindex brace-entry-open syntactic symbol |
3365 | Your static initializer might be initializing nested structures, for | |
3366 | example: | |
3367 | @example | |
3368 | @group | |
3369 | ||
3370 | 1: struct intpairs[] = | |
3371 | 2: @{ | |
3372 | 3: @{ 1, 2 @}, | |
3373 | 4: @{ | |
3374 | 5: 3, | |
3375 | 6: 4 | |
3376 | 7: @} | |
3377 | 8: @{ 1, | |
3378 | 9: 2 @}, | |
3379 | 10: @{ 3, 4 @} | |
3380 | 11: @} | |
3381 | ||
3382 | @end group | |
3383 | @end example | |
3384 | ||
3385 | Here, you've already seen the analysis of lines 1, 2, 3, and 11. On | |
3386 | line 4, things get interesting; this line is assigned | |
3387 | @code{brace-entry-open} syntactic symbol because it's a bracelist entry | |
3388 | line that starts with an open brace. Lines 5 and 6 (and line 9) are | |
3389 | pretty standard, and line 7 is a @code{brace-list-close} as you'd | |
3390 | expect. Once again, line 8 is assigned as @code{brace-entry-open} as is | |
3391 | line 10. | |
3392 | ||
6bf7aab6 DL |
3393 | External language definition blocks also have their own syntactic |
3394 | symbols. In this example: | |
3395 | @example | |
3396 | @group | |
3397 | ||
3398 | 1: extern "C" | |
3399 | 2: @{ | |
3400 | 3: int thing_one( int ); | |
3401 | 4: int thing_two( double ); | |
3402 | 5: @} | |
3403 | ||
3404 | @end group | |
3405 | @end example | |
3406 | ||
3407 | @cindex extern-lang-open syntactic symbol | |
3408 | @cindex extern-lang-close syntactic symbol | |
3409 | @cindex inextern-lang syntactic symbol | |
3410 | @cindex inclass syntactic symbol | |
3411 | @noindent | |
3412 | line 2 is given the @code{extern-lang-open} syntax, while line 5 is given | |
3413 | the @code{extern-lang-close} syntax. The analysis for line 3 yields: | |
3414 | @code{((inextern-lang) (topmost-intro . 14))}, where | |
3415 | @code{inextern-lang} is a modifier similar in purpose to @code{inclass}. | |
3416 | ||
3417 | Similarly, C++ namespace constructs have their own associated syntactic | |
3418 | symbols. In this example: | |
3419 | @example | |
3420 | @group | |
3421 | ||
3422 | 1: namespace foo | |
3423 | 2: @{ | |
3424 | 3: void xxx() @{@} | |
3425 | 4: @} | |
3426 | ||
3427 | @end group | |
3428 | @end example | |
3429 | ||
d7bd46ed GM |
3430 | @cindex namespace-open syntactic symbol |
3431 | @cindex namespace-close syntactic symbol | |
3432 | @cindex innamespace syntactic symbol | |
6bf7aab6 DL |
3433 | @noindent |
3434 | line 2 is given the @code{namespace-open} syntax, while line 4 is given | |
3435 | the @code{namespace-close} syntax. The analysis for line 3 yields: | |
3436 | @code{((innamespace) (topmost-intro . 17))}, where @code{innamespace} is | |
3437 | a modifier similar in purpose to @code{inextern-lang} and @code{inclass}. | |
3438 | ||
3439 | A number of syntactic symbols are associated with parenthesis lists, | |
3440 | a.k.a argument lists, as found in function declarations and function | |
3441 | calls. This example illustrates these: | |
3442 | @example | |
3443 | @group | |
3444 | ||
3445 | 1: void a_function( int line1, | |
3446 | 2: int line2 ); | |
3447 | 3: | |
3448 | 4: void a_longer_function( | |
3449 | 5: int line1, | |
3450 | 6: int line2 | |
3451 | 7: ); | |
3452 | 8: | |
3453 | 9: void call_them( int line1, int line2 ) | |
3454 | 10: @{ | |
3455 | 11: a_function( | |
3456 | 12: line1, | |
3457 | 13: line2 | |
3458 | 14: ); | |
3459 | 15: | |
3460 | 16: a_longer_function( line1, | |
3461 | 17: line2 ); | |
3462 | 18: @} | |
3463 | ||
3464 | @end group | |
3465 | @end example | |
3466 | ||
3467 | @cindex arglist-intro syntactic symbol | |
3468 | @cindex arglist-close syntactic symbol | |
3469 | Lines 5 and 12 are assigned @code{arglist-intro} syntax since they are | |
3470 | the first line following the open parenthesis, and lines 7 and 14 are | |
3471 | assigned @code{arglist-close} syntax since they contain the parenthesis | |
3472 | that closes the argument list. | |
3473 | ||
3474 | @cindex arglist-cont-nonempty syntactic symbol | |
3475 | @cindex arglist-cont syntactic symbol | |
3476 | Lines that continue argument lists can be assigned one of two syntactic | |
3477 | symbols. For example, Lines 2 and 17 | |
3478 | are assigned @code{arglist-cont-nonempty} syntax. What this means | |
3479 | is that they continue an argument list, but that the line containing the | |
3480 | parenthesis that opens the list is @emph{not empty} following the open | |
3481 | parenthesis. Contrast this against lines 6 and 13 which are assigned | |
3482 | @code{arglist-cont} syntax. This is because the parenthesis that opens | |
3483 | their argument lists is the last character on that line. | |
3484 | ||
3485 | Note that there is no @code{arglist-open} syntax. This is because any | |
3486 | parenthesis that opens an argument list, appearing on a separate line, | |
3487 | is assigned the @code{statement-cont} syntax instead. | |
3488 | ||
3489 | A few miscellaneous syntactic symbols that haven't been previously | |
3490 | covered are illustrated by this C++ example: | |
3491 | @example | |
3492 | @group | |
3493 | ||
3494 | 1: void Bass::play( int volume ) | |
3495 | 2: const | |
3496 | 3: @{ | |
3497 | 4: /* this line starts a multi-line | |
3498 | 5: * comment. This line should get `c' syntax */ | |
3499 | 6: | |
3500 | 7: char* a_multiline_string = "This line starts a multi-line \ | |
3501 | 8: string. This line should get `string' syntax."; | |
3502 | 9: | |
3503 | 10: note: | |
3504 | 11: @{ | |
3505 | 12: #ifdef LOCK | |
3506 | 13: Lock acquire(); | |
3507 | 14: #endif // LOCK | |
3508 | 15: slap_pop(); | |
3509 | 16: cout << "I played " | |
3510 | 17: << "a note\n"; | |
3511 | 18: @} | |
3512 | 19: @} | |
3513 | ||
3514 | @end group | |
3515 | @end example | |
3516 | ||
6bf7aab6 DL |
3517 | The lines to note in this example include: |
3518 | ||
3519 | @itemize @bullet | |
3520 | ||
3521 | @cindex func-decl-cont syntactic symbol | |
3522 | @item | |
f214c025 | 3523 | Line 2 is assigned the @code{func-decl-cont} syntax. |
6bf7aab6 DL |
3524 | |
3525 | @cindex comment-intro syntactic symbol | |
3526 | @item | |
f214c025 GM |
3527 | Line 4 is assigned both @code{defun-block-intro} @emph{and} |
3528 | @code{comment-intro} syntax. | |
6bf7aab6 DL |
3529 | |
3530 | @cindex c syntactic symbol | |
3531 | @item | |
f214c025 | 3532 | Line 5 is assigned @code{c} syntax. |
6bf7aab6 DL |
3533 | |
3534 | @item | |
3535 | @cindex syntactic whitespace | |
f214c025 | 3536 | Line 6 which, even though it contains nothing but whitespace, is |
6bf7aab6 DL |
3537 | assigned @code{defun-block-intro}. Note that the appearance of the |
3538 | comment on lines 4 and 5 do not cause line 6 to be assigned | |
3539 | @code{statement} syntax because comments are considered to be | |
3540 | @dfn{syntactic whitespace}, which are ignored when analyzing | |
f214c025 | 3541 | code. |
6bf7aab6 DL |
3542 | |
3543 | @cindex string syntactic symbol | |
3544 | @item | |
f214c025 | 3545 | Line 8 is assigned @code{string} syntax. |
6bf7aab6 DL |
3546 | |
3547 | @cindex label syntactic symbol | |
3548 | @item | |
f214c025 | 3549 | Line 10 is assigned @code{label} syntax. |
6bf7aab6 DL |
3550 | |
3551 | @cindex block-open syntactic symbol | |
3552 | @item | |
f214c025 | 3553 | Line 11 is assigned @code{block-open} syntax. |
6bf7aab6 DL |
3554 | |
3555 | @cindex cpp-macro syntactic symbol | |
3556 | @cindex cpp-macro-cont syntactic symbol | |
3557 | @item | |
f214c025 GM |
3558 | Lines 12 and 14 are assigned @code{cpp-macro} syntax in addition to the |
3559 | normal syntactic symbols (@code{statement-block-intro} and | |
3560 | @code{statement}, respectively). Normally @code{cpp-macro} is | |
3561 | configured to cancel out the normal syntactic context to make all | |
3562 | preprocessor directives stick to the first column, but that's easily | |
3563 | changed if you want preprocessor directives to be indented like the rest | |
3564 | of the code. | |
6bf7aab6 DL |
3565 | |
3566 | @cindex stream-op syntactic symbol | |
3567 | @item | |
f214c025 | 3568 | Line 17 is assigned @code{stream-op} syntax. |
6bf7aab6 DL |
3569 | |
3570 | @end itemize | |
3571 | ||
3572 | @cindex multi-line macros | |
3573 | @cindex syntactic whitespace | |
3574 | Multi-line C preprocessor macros are now (somewhat) supported. At least | |
d7bd46ed | 3575 | @ccmode{} now recognizes the fact that it is inside a multi-line macro, |
6bf7aab6 DL |
3576 | and it properly skips such macros as syntactic whitespace. In this |
3577 | example: | |
3578 | @example | |
3579 | @group | |
3580 | ||
3581 | 1: #define LIST_LOOP(cons, listp) \ | |
3582 | 2: for (cons = listp; !NILP (cons); cons = XCDR (cons)) \ | |
3583 | 3: if (!CONSP (cons)) \ | |
3584 | 4: signal_error ("Invalid list format", listp); \ | |
3585 | 5: else | |
3586 | ||
3587 | @end group | |
3588 | @end example | |
3589 | @noindent | |
3590 | line 1 is given the syntactic symbol @code{cpp-macro}. This first line | |
3591 | of a macro is always given this symbol. The second and subsequent lines | |
3592 | (e.g. lines 2 through 5) are given the @code{cpp-macro-cont} syntactic | |
3593 | symbol, with a relative buffer position pointing to the @code{#} which | |
3594 | starts the macro definition. | |
3595 | ||
3596 | In Objective-C buffers, there are three additional syntactic symbols | |
3597 | assigned to various message calling constructs. Here's an example | |
3598 | illustrating these: | |
3599 | @example | |
3600 | @group | |
3601 | ||
3602 | 1: - (void)setDelegate:anObject | |
3603 | 2: withStuff:stuff | |
3604 | 3: @{ | |
3605 | 4: [delegate masterWillRebind:self | |
3606 | 5: toDelegate:anObject | |
3607 | 6: withExtraStuff:stuff]; | |
3608 | 7: @} | |
3609 | ||
3610 | @end group | |
3611 | @end example | |
3612 | ||
3613 | @cindex objc-method-intro syntactic symbol | |
3614 | @cindex objc-method-args-cont syntactic symbol | |
3615 | @cindex objc-method-call-cont syntactic symbol | |
3616 | Here, line 1 is assigned @code{objc-method-intro} syntax, and line 2 is | |
3617 | assigned @code{objc-method-args-cont} syntax. Lines 5 and 6 are both | |
3618 | assigned @code{objc-method-call-cont} syntax. | |
3619 | ||
d7bd46ed GM |
3620 | Java has a concept of anonymous classes, which may look something like |
3621 | this: | |
3622 | @example | |
3623 | @group | |
3624 | ||
3625 | 1: public void watch(Observable o) @{ | |
3626 | 2: o.addObserver(new Observer() @{ | |
3627 | 3: public void update(Observable o, Object arg) @{ | |
3628 | 4: history.addElement(arg); | |
3629 | 5: @} | |
3630 | 6: @}); | |
3631 | 7: @} | |
3632 | ||
3633 | @end group | |
3634 | @end example | |
3635 | ||
3636 | @cindex inexpr-class syntactic symbol | |
3637 | The brace following the @code{new} operator opens the anonymous class. | |
3638 | Lines 3 and 6 are assigned the @code{inexpr-class} syntax, besides the | |
3639 | @code{inclass} symbol used in normal classes. Thus, the class will be | |
3640 | indented just like a normal class, with the added indentation given to | |
3641 | @code{inexpr-class}. | |
3642 | ||
3643 | There are a few occasions where a statement block may be used inside an | |
3644 | expression. One is in C code using the gcc extension for this, e.g: | |
3645 | @example | |
3646 | @group | |
3647 | ||
3648 | 1: int res = (@{ | |
3649 | 2: int y = foo (); int z; | |
3650 | 3: if (y > 0) z = y; else z = - y; | |
3651 | 4: z; | |
3652 | 5: @}); | |
3653 | ||
3654 | @end group | |
3655 | @end example | |
3656 | ||
3657 | @cindex inexpr-statement syntactic symbol | |
3658 | Lines 2 and 5 get the @code{inexpr-statement} syntax, besides the | |
3659 | symbols they'd get in a normal block. Therefore, the indentation put on | |
3660 | @code{inexpr-statement} is added to the normal statement block | |
3661 | indentation. | |
3662 | ||
3663 | In Pike code, there are a few other situations where blocks occur inside | |
3664 | statements, as illustrated here: | |
3665 | @example | |
3666 | @group | |
3667 | ||
3668 | 1: array itgob() | |
3669 | 2: @{ | |
3670 | 3: string s = map (backtrace()[-2][3..], | |
3671 | 4: lambda | |
3672 | 5: (mixed arg) | |
3673 | 6: @{ | |
3674 | 7: return sprintf ("%t", arg); | |
3675 | 8: @}) * ", " + "\n"; | |
3676 | 9: return catch @{ | |
3677 | 10: write (s + "\n"); | |
3678 | 11: @}; | |
3679 | 12: @} | |
3680 | ||
3681 | @end group | |
3682 | @end example | |
3683 | ||
3684 | @cindex inlambda syntactic symbol | |
3685 | @cindex lambda-intro-cont syntactic symbol | |
3686 | Lines 4 through 8 contain a lambda function, which @ccmode{} recognizes | |
3687 | by the @code{lambda} keyword. If the function argument list is put | |
3688 | on a line of its own, as in line 5, it gets the @code{lambda-intro-cont} | |
3689 | syntax. The function body is handled as an inline method body, with the | |
3690 | addition of the @code{inlambda} syntactic symbol. This means that line | |
3691 | 6 gets @code{inlambda} and @code{inline-open}, and line 8 gets | |
3692 | @code{inline-close}@footnote{You might wonder why it doesn't get | |
3693 | @code{inlambda} too. It's because the closing brace is relative to the | |
3694 | opening brace, which stands on its own line in this example. If the | |
3695 | opening brace was hanging on the previous line, then the closing brace | |
3696 | would get the @code{inlambda} syntax too to be indented correctly.}. | |
3697 | ||
3698 | @cindex inexpr-statement syntactic symbol | |
3699 | On line 9, @code{catch} is a special function taking a statement block | |
3700 | as its argument. The block is handled as an in-expression statement | |
3701 | with the @code{inexpr-statement} syntax, just like the gcc extended C | |
3702 | example above. The other similar special function, @code{gauge}, is | |
3703 | handled like this too. | |
3704 | ||
6bf7aab6 DL |
3705 | @cindex knr-argdecl-intro syntactic symbol |
3706 | @cindex knr-argdecl syntactic symbol | |
3707 | Two other syntactic symbols can appear in old style, non-prototyped C | |
3708 | code @footnote{a.k.a. K&R C, or Kernighan & Ritchie C}: | |
3709 | @example | |
3710 | @group | |
3711 | ||
3712 | 1: int add_three_integers(a, b, c) | |
3713 | 2: int a; | |
3714 | 3: int b; | |
3715 | 4: int c; | |
3716 | 5: @{ | |
3717 | 6: return a + b + c; | |
3718 | 7: @} | |
3719 | ||
3720 | @end group | |
3721 | @end example | |
3722 | ||
3723 | Here, line 2 is the first line in an argument declaration list and so is | |
3724 | given the @code{knr-argdecl-intro} syntactic symbol. Subsequent lines | |
3725 | (i.e. lines 3 and 4 in this example), are given @code{knr-argdecl} | |
3726 | syntax. | |
3727 | ||
d7bd46ed | 3728 | |
6bf7aab6 | 3729 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
d7bd46ed GM |
3730 | @node Indentation Functions, Performance Issues, Syntactic Symbols, Top |
3731 | @comment node-name, next, previous, up | |
3732 | @chapter Indentation Functions | |
3733 | @cindex indentation functions | |
3734 | @cindex line-up functions | |
3735 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
3736 | ||
3737 | Often there are cases when a simple offset setting on a syntactic symbol | |
3738 | isn't enough to get the desired indentation. Therefore, it's also | |
3739 | possible to use a @dfn{indentation function} (a.k.a. line-up function) | |
3740 | for a syntactic symbol. | |
3741 | ||
3742 | @ccmode{} comes with many predefined indentation functions for common | |
3743 | situations. If none of these does what you want, you can write your | |
3744 | own, see @ref{Custom Indentation Functions}. If you do, it's probably a | |
3745 | good idea to start working from one of these predefined functions, they | |
3746 | can be found in the file @file{cc-align.el}. | |
3747 | ||
3748 | For every function below there is a ``works with'' list that indicates | |
3749 | which syntactic symbols the function is intended to be used with. | |
3750 | ||
3751 | @macro workswith | |
cb7f2e96 | 3752 | @emph{Works with:@ } |
d7bd46ed GM |
3753 | @end macro |
3754 | @ifinfo | |
3755 | @unmacro workswith | |
3756 | @macro workswith | |
3757 | Works with: | |
3758 | @end macro | |
3759 | @end ifinfo | |
3760 | ||
3761 | @table @code | |
3762 | ||
3763 | @findex c-lineup-arglist | |
3764 | @findex lineup-arglist (c-) | |
3765 | @item c-lineup-arglist | |
3766 | Line up the current argument line under the first argument. | |
3767 | ||
3768 | @workswith @code{arglist-cont-nonempty}. | |
3769 | ||
3770 | @findex c-lineup-arglist-intro-after-paren | |
3771 | @findex lineup-arglist-intro-after-paren (c-) | |
3772 | @item c-lineup-arglist-intro-after-paren | |
3773 | Line up a line just after the open paren of the surrounding paren or | |
3774 | brace block. | |
3775 | ||
3776 | @workswith @code{defun-block-intro}, @code{brace-list-intro}, | |
3777 | @code{statement-block-intro}, @code{statement-case-intro}, | |
3778 | @code{arglist-intro}. | |
3779 | ||
3780 | @findex c-lineup-arglist-close-under-paren | |
3781 | @findex lineup-arglist-close-under-paren (c-) | |
3782 | @item c-lineup-arglist-close-under-paren | |
3783 | Set e.g. your @code{arglist-close} syntactic symbol to this line-up | |
3784 | function so that parentheses that close argument lists will line up | |
3785 | under the parenthesis that opened the argument list. | |
3786 | ||
3787 | @workswith @code{defun-close}, @code{class-close}, @code{inline-close}, | |
3788 | @code{block-close}, @code{brace-list-close}, @code{arglist-close}, | |
3789 | @code{extern-lang-close}, @code{namespace-close} (for most of these, a | |
3790 | zero offset will normally produce the same result, though). | |
3791 | ||
3792 | @findex c-lineup-close-paren | |
3793 | @findex lineup-close-paren (c-) | |
3794 | @item c-lineup-close-paren | |
3795 | Line up the closing paren under its corresponding open paren if the | |
3796 | open paren is followed by code. If the open paren ends its line, no | |
3797 | indentation is added. E.g: | |
3798 | @example | |
3799 | @group | |
3800 | ||
3801 | main (int, | |
3802 | char ** | |
3803 | ) // c-lineup-close-paren | |
3804 | ||
3805 | @end group | |
3806 | @end example | |
3807 | @noindent | |
3808 | and | |
3809 | @example | |
3810 | @group | |
3811 | ||
3812 | main ( | |
3813 | int, char ** | |
3814 | ) // c-lineup-close-paren | |
3815 | ||
3816 | @end group | |
3817 | @end example | |
3818 | ||
3819 | @workswith @code{defun-close}, @code{class-close}, @code{inline-close}, | |
3820 | @code{block-close}, @code{brace-list-close}, @code{arglist-close}, | |
3821 | @code{extern-lang-close}, @code{namespace-close}. | |
3822 | ||
3823 | @findex c-lineup-streamop | |
3824 | @findex lineup-streamop (c-) | |
3825 | @item c-lineup-streamop | |
3826 | Line up C++ stream operators (i.e. @samp{<<} and @samp{>>}). | |
3827 | ||
3828 | @workswith @code{stream-op}. | |
3829 | ||
3830 | @findex c-lineup-multi-inher | |
3831 | @findex lineup-multi-inher (c-) | |
3832 | @item c-lineup-multi-inher | |
f214c025 GM |
3833 | Line up the classes in C++ multiple inheritance clauses and member |
3834 | initializers under each other. E.g: | |
3835 | @example | |
3836 | @group | |
d7bd46ed | 3837 | |
f214c025 GM |
3838 | Foo::Foo (int a, int b): |
3839 | Cyphr (a), | |
3840 | Bar (b) // c-lineup-multi-inher | |
3841 | ||
3842 | @end group | |
3843 | @end example | |
3844 | @noindent | |
3845 | and | |
3846 | @example | |
3847 | @group | |
3848 | ||
3849 | class Foo | |
3850 | : public Cyphr, | |
3851 | public Bar // c-lineup-multi-inher | |
3852 | ||
3853 | @end group | |
3854 | @end example | |
3855 | @noindent | |
3856 | and | |
3857 | @example | |
3858 | @group | |
3859 | ||
3860 | Foo::Foo (int a, int b) | |
3861 | : Cyphr (a) | |
3862 | , Bar (b) // c-lineup-multi-inher | |
3863 | ||
3864 | @end group | |
3865 | @end example | |
3866 | ||
3867 | @workswith @code{inher-cont}, @code{member-init-cont}. | |
d7bd46ed GM |
3868 | |
3869 | @findex c-lineup-java-inher | |
3870 | @findex lineup-java-inher (c-) | |
3871 | @item c-lineup-java-inher | |
3872 | Line up Java implements and extends declarations. If class names | |
3873 | follows on the same line as the @samp{implements}/@samp{extends} | |
3874 | keyword, they are lined up under each other. Otherwise, they are | |
3875 | indented by adding @code{c-basic-offset} to the column of the keyword. | |
3876 | E.g: | |
3877 | @example | |
3878 | @group | |
3879 | ||
3880 | class Foo | |
3881 | extends | |
3882 | Bar // c-lineup-java-inher | |
3883 | ||
3884 | <--> c-basic-offset | |
3885 | ||
3886 | @end group | |
3887 | @end example | |
3888 | @noindent | |
3889 | and | |
3890 | @example | |
3891 | @group | |
3892 | ||
3893 | class Foo | |
3894 | extends Cyphr, | |
3895 | Bar // c-lineup-java-inher | |
3896 | ||
3897 | @end group | |
3898 | @end example | |
3899 | ||
3900 | @workswith @code{inher-cont}. | |
3901 | ||
3902 | @findex c-lineup-java-throws | |
3903 | @findex lineup-java-throws (c-) | |
3904 | @item c-lineup-java-throws | |
3905 | Line up Java throws declarations. If exception names follows on the | |
3906 | same line as the throws keyword, they are lined up under each other. | |
3907 | Otherwise, they are indented by adding @code{c-basic-offset} to the | |
3908 | column of the @samp{throws} keyword. The @samp{throws} keyword itself | |
3909 | is also indented by @code{c-basic-offset} from the function declaration | |
3910 | start if it doesn't hang. E.g: | |
3911 | @example | |
3912 | @group | |
3913 | ||
3914 | int foo() | |
3915 | throws // c-lineup-java-throws | |
3916 | Bar // c-lineup-java-throws | |
3917 | ||
3918 | <--><--> c-basic-offset | |
3919 | ||
3920 | @end group | |
3921 | @end example | |
3922 | @noindent | |
3923 | and | |
3924 | @example | |
3925 | @group | |
3926 | ||
3927 | int foo() throws Cyphr, | |
3928 | Bar, // c-lineup-java-throws | |
3929 | Vlod // c-lineup-java-throws | |
3930 | ||
3931 | @end group | |
3932 | @end example | |
3933 | ||
3934 | @workswith @code{func-decl-cont}. | |
3935 | ||
3936 | @findex c-indent-one-line-block | |
3937 | @findex indent-one-line-block (c-) | |
3938 | @item c-indent-one-line-block | |
3939 | Indent a one line block @code{c-basic-offset} extra. E.g: | |
3940 | @example | |
3941 | @group | |
3942 | ||
3943 | if (n > 0) | |
3944 | @{m+=n; n=0;@} // c-indent-one-line-block | |
3945 | ||
3946 | <--> c-basic-offset | |
3947 | ||
3948 | @end group | |
3949 | @end example | |
3950 | @noindent | |
3951 | and | |
3952 | @example | |
3953 | @group | |
3954 | ||
3955 | if (n > 0) | |
3956 | @{ // c-indent-one-line-block | |
3957 | m+=n; n=0; | |
3958 | @} | |
3959 | ||
3960 | @end group | |
3961 | @end example | |
3962 | ||
3963 | The block may be surrounded by any kind of parenthesis characters. | |
3964 | @code{nil} is returned if the line doesn't start with a one line block, | |
3965 | which makes the function usable in list expressions. | |
3966 | ||
3967 | @workswith Almost all syntactic symbols, but most useful on the | |
3968 | @code{-open} symbols. | |
3969 | ||
3970 | @findex c-indent-multi-line-block | |
3971 | @findex indent-multi-line-block (c-) | |
3972 | @item c-indent-multi-line-block | |
3973 | Indent a multi line block @code{c-basic-offset} extra. E.g: | |
3974 | @example | |
3975 | @group | |
3976 | ||
3977 | int *foo[] = @{ | |
3978 | NULL, | |
3979 | @{17@}, // c-indent-multi-line-block | |
3980 | ||
3981 | @end group | |
3982 | @end example | |
3983 | @noindent | |
3984 | and | |
3985 | @example | |
3986 | @group | |
3987 | ||
3988 | int *foo[] = @{ | |
3989 | NULL, | |
3990 | @{ // c-indent-multi-line-block | |
3991 | 17 | |
3992 | @}, | |
3993 | ||
3994 | <--> c-basic-offset | |
3995 | ||
3996 | @end group | |
3997 | @end example | |
3998 | ||
3999 | The block may be surrounded by any kind of parenthesis characters. | |
4000 | @code{nil} is returned if the line doesn't start with a multi line | |
4001 | block, which makes the function usable in list expressions. | |
4002 | ||
4003 | @workswith Almost all syntactic symbols, but most useful on the | |
4004 | @code{-open} symbols. | |
4005 | ||
4006 | @findex c-lineup-C-comments | |
4007 | @findex lineup-C-comments (c-) | |
4008 | @item c-lineup-C-comments | |
4009 | Line up C block comment continuation lines. Various heuristics are used | |
4010 | to handle most of the common comment styles. Some examples: | |
4011 | @example | |
4012 | ||
4013 | @group | |
4014 | /* /** /* | |
4015 | * text * text text | |
4016 | */ */ */ | |
4017 | @end group | |
4018 | ||
4019 | @group | |
4020 | /* text /* /** | |
4021 | text ** text ** text | |
4022 | */ */ */ | |
4023 | @end group | |
4024 | ||
4025 | @group | |
4026 | /************************************************** | |
4027 | * text | |
4028 | *************************************************/ | |
4029 | @end group | |
4030 | ||
4031 | @vindex comment-start-skip | |
4032 | @group | |
4033 | /************************************************** | |
4034 | Free form text comments: | |
4035 | In comments with a long delimiter line at the | |
4036 | start, the indentation is kept unchanged for lines | |
4037 | that start with an empty comment line prefix. The | |
4038 | delimiter line is whatever matches the | |
4039 | @code{comment-start-skip} regexp. | |
4040 | **************************************************/ | |
4041 | @end group | |
4042 | ||
4043 | @end example | |
4044 | ||
4045 | The style variable @code{c-comment-prefix-regexp} is used to recognize | |
4046 | the comment line prefix, e.g. the @samp{*} that usually starts every | |
4047 | line inside a comment. | |
4048 | ||
4049 | @workswith The @code{c} syntactic symbol. | |
4050 | ||
4051 | @findex c-lineup-comment | |
4052 | @findex lineup-comment (c-) | |
4053 | @item c-lineup-comment | |
4054 | Line up a comment-only line according to the style variable | |
4055 | @code{c-comment-only-line-offset}. If the comment is lined up with a | |
4056 | comment starter on the previous line, that alignment is preserved. | |
4057 | ||
4058 | @vindex c-comment-only-line-offset | |
4059 | @vindex comment-only-line-offset (c-) | |
4060 | @code{c-comment-only-line-offset} specifies the extra offset for the | |
4061 | line. It can contain an integer or a cons cell of the form | |
4062 | @example | |
4063 | ||
4064 | (@r{<non-anchored-offset>} . @r{<anchored-offset>}) | |
4065 | ||
4066 | @end example | |
4067 | ||
4068 | @noindent | |
4069 | where @var{non-anchored-offset} is the amount of offset given to | |
4070 | non-column-zero anchored lines, and @var{anchored-offset} is the amount | |
4071 | of offset to give column-zero anchored lines. Just an integer as value | |
4072 | is equivalent to @code{(@r{<value>} . -1000)}. | |
4073 | ||
4074 | @workswith @code{comment-intro}. | |
4075 | ||
4076 | @findex c-lineup-runin-statements | |
4077 | @findex lineup-runin-statements (c-) | |
4078 | @item c-lineup-runin-statements | |
4079 | Line up statements for coding standards which place the first statement | |
4080 | in a block on the same line as the block opening brace@footnote{Run-in | |
4081 | style doesn't really work too well. You might need to write your own | |
4082 | custom indentation functions to better support this style.}. E.g: | |
4083 | @example | |
4084 | @group | |
4085 | ||
4086 | int main() | |
4087 | @{ puts (\"Hello world!\"); | |
4088 | return 0; // c-lineup-runin-statements | |
4089 | @} | |
4090 | ||
4091 | @end group | |
4092 | @end example | |
4093 | ||
4094 | If there is no statement after the opening brace to align with, | |
4095 | @code{nil} is returned. This makes the function usable in list | |
4096 | expressions. | |
4097 | ||
4098 | @workswith The @code{statement} syntactic symbol. | |
4099 | ||
4100 | @findex c-lineup-math | |
4101 | @findex lineup-math (c-) | |
4102 | @item c-lineup-math | |
4103 | Line up the current line after the equal sign on the first line in the | |
4104 | statement. If there isn't any, indent with @code{c-basic-offset}. If | |
4105 | the current line contains an equal sign too, try to align it with the | |
4106 | first one. | |
4107 | ||
4108 | @workswith @code{statement-cont}. | |
4109 | ||
4110 | @findex c-lineup-template-args | |
4111 | @findex lineup-template-args (c-) | |
4112 | @item c-lineup-template-args | |
4113 | Line up the arguments of a template argument list under each other, but | |
4114 | only in the case where the first argument is on the same line as the | |
4115 | opening @samp{<}. | |
4116 | ||
4117 | To allow this function to be used in a list expression, @code{nil} is | |
4118 | returned if there's no template argument on the first line. | |
4119 | ||
4120 | @workswith @code{template-args-cont}. | |
4121 | ||
4122 | @findex c-lineup-ObjC-method-call | |
4123 | @findex lineup-ObjC-method-call (c-) | |
4124 | @item c-lineup-ObjC-method-call | |
4125 | For Objective-C code, line up selector args as @code{elisp-mode} does | |
4126 | with function args: go to the position right after the message receiver, | |
4127 | and if you are at the end of the line, indent the current line | |
4128 | c-basic-offset columns from the opening bracket; otherwise you are | |
4129 | looking at the first character of the first method call argument, so | |
4130 | lineup the current line with it. | |
4131 | ||
4132 | @workswith @code{objc-method-call-cont}. | |
4133 | ||
4134 | @findex c-lineup-ObjC-method-args | |
4135 | @findex lineup-ObjC-method-args (c-) | |
4136 | @item c-lineup-ObjC-method-args | |
4137 | For Objective-C code, line up the colons that separate args. The colon | |
4138 | on the current line is aligned with the one on the first line. | |
4139 | ||
4140 | @workswith @code{objc-method-args-cont}. | |
4141 | ||
4142 | @findex c-lineup-ObjC-method-args-2 | |
4143 | @findex lineup-ObjC-method-args-2 (c-) | |
4144 | @item c-lineup-ObjC-method-args-2 | |
4145 | Similar to @code{c-lineup-ObjC-method-args} but lines up the colon on | |
4146 | the current line with the colon on the previous line. | |
4147 | ||
4148 | @workswith @code{objc-method-args-cont}. | |
4149 | ||
4150 | @findex c-lineup-inexpr-block | |
4151 | @findex lineup-inexpr-block (c-) | |
4152 | @item c-lineup-inexpr-block | |
4153 | This can be used with the in-expression block symbols to indent the | |
4154 | whole block to the column where the construct is started. E.g. for Java | |
4155 | anonymous classes, this lines up the class under the @samp{new} keyword, | |
4156 | and in Pike it lines up the lambda function body under the @samp{lambda} | |
4157 | keyword. Returns @code{nil} if the block isn't part of such a | |
4158 | construct. | |
4159 | ||
4160 | @workswith @code{inlambda}, @code{inexpr-statement}, | |
4161 | @code{inexpr-class}. | |
4162 | ||
4163 | @findex c-lineup-whitesmith-in-block | |
4164 | @findex lineup-whitesmith-in-block (c-) | |
4165 | @item c-lineup-whitesmith-in-block | |
4166 | Line up lines inside a block in Whitesmith style. It's done in a way | |
4167 | that works both when the opening brace hangs and when it doesn't. E.g: | |
4168 | @example | |
4169 | @group | |
4170 | ||
4171 | something | |
4172 | @{ | |
4173 | foo; // c-lineup-whitesmith-in-block | |
4174 | @} | |
4175 | ||
4176 | @end group | |
4177 | @end example | |
4178 | @noindent | |
4179 | and | |
4180 | @example | |
4181 | @group | |
4182 | ||
4183 | something @{ | |
4184 | foo; // c-lineup-whitesmith-in-block | |
4185 | @} | |
4186 | ||
4187 | <--> c-basic-offset | |
4188 | ||
4189 | @end group | |
4190 | @end example | |
4191 | ||
4192 | In the first case the indentation is kept unchanged, in the second | |
4193 | @code{c-basic-offset} is added. | |
4194 | ||
4195 | @workswith @code{defun-close}, @code{defun-block-intro}, | |
4196 | @code{block-close}, @code{brace-list-close}, @code{brace-list-intro}, | |
4197 | @code{statement-block-intro}, @code{inclass}, @code{inextern-lang}, | |
4198 | @code{innamespace}. | |
4199 | ||
4200 | @findex c-lineup-dont-change | |
4201 | @findex lineup-dont-change (c-) | |
4202 | @item c-lineup-dont-change | |
cb7f2e96 GM |
4203 | This lineup function makes the line stay at whatever indentation it |
4204 | already has; think of it as an identity function for lineups. It is | |
4205 | used for @code{cpp-macro-cont} lines. | |
d7bd46ed GM |
4206 | |
4207 | @workswith Any syntactic symbol. | |
4208 | ||
4209 | @end table | |
4210 | ||
6bf7aab6 | 4211 | |
d7bd46ed | 4212 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
cb7f2e96 | 4213 | @node Performance Issues, Limitations and Known Bugs, Indentation Functions, Top |
d7bd46ed GM |
4214 | @comment node-name, next, previous, up |
4215 | @chapter Performance Issues | |
4216 | @cindex performance issues | |
6bf7aab6 DL |
4217 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
4218 | ||
4219 | C and its derivative languages are highly complex creatures. Often, | |
4220 | ambiguous code situations arise that require @ccmode{} to scan | |
4221 | large portions of the buffer to determine syntactic context. Such | |
4222 | pathological code@footnote{such as the output of @code{lex(1)}!} | |
4223 | can cause @ccmode{} to perform fairly badly. | |
4224 | This section identifies some of the coding styles to watch out for, and | |
4225 | suggests some workarounds that you can use to improve performance. | |
4226 | ||
4227 | Because @ccmode{} has to scan the buffer backwards from the current | |
4228 | insertion point, and because C's syntax is fairly difficult to parse in | |
4229 | the backwards direction, @ccmode{} often tries to find the nearest | |
4230 | position higher up in the buffer from which to begin a forward scan. | |
4231 | The farther this position is from the current insertion point, the | |
4232 | slower the mode gets. Some coding styles can even force @ccmode{} | |
4233 | to scan from the beginning of the buffer for every line of code! | |
4234 | ||
4235 | @findex beginning-of-defun | |
4236 | @findex defun-prompt-regexp | |
4237 | One of the simplest things you can do to reduce scan time, is make sure | |
d7bd46ed | 4238 | any brace that opens a top-level construct@footnote{E.g. a function in |
6bf7aab6 DL |
4239 | C, or outermost class definition in C++ or Java.} always appears in the |
4240 | leftmost column. This is actually an Emacs constraint, as embodied in | |
d7bd46ed GM |
4241 | the @code{beginning-of-defun} function which @ccmode{} uses heavily. If |
4242 | you insist on hanging top-level open braces on the right side of the | |
4243 | line, then you might want to set the variable @code{defun-prompt-regexp} | |
4244 | to something reasonable, however that ``something reasonable'' is | |
4245 | difficult to define, so @ccmode{} doesn't do it for you. | |
6bf7aab6 DL |
4246 | |
4247 | @vindex c-Java-defun-prompt-regexp | |
4248 | @vindex Java-defun-prompt-regexp (c-) | |
4249 | A special note about @code{defun-prompt-regexp} in Java mode: while much | |
4250 | of the early sample Java code seems to encourage a style where the brace | |
4251 | that opens a class is hung on the right side of the line, this is not a | |
4252 | good style to pursue in Emacs. @ccmode{} comes with a variable | |
4253 | @code{c-Java-defun-prompt-regexp} which tries to define a regular | |
4254 | expression usable for this style, but there are problems with it. In | |
4255 | some cases it can cause @code{beginning-of-defun} to hang@footnote{This | |
4256 | has been observed in Emacs 19.34 and XEmacs 19.15.}. For this reason, | |
4257 | it is not used by default, but if you feel adventurous, you can set | |
4258 | @code{defun-prompt-regexp} to it in your mode hook. In any event, | |
4259 | setting and rely on @code{defun-prompt-regexp} will definitely slow | |
d7bd46ed GM |
4260 | things down anyway because you'll be doing regular expression searches |
4261 | for every line you indent, so you're probably screwed either way! | |
4262 | ||
4263 | @vindex c-enable-xemacs-performance-kludge-p | |
4264 | @vindex enable-xemacs-performance-kludge-p (c-) | |
4265 | Another alternative for XEmacs users, is to set the variable | |
4266 | @code{c-enable-xemacs-performance-kludge-p} to non-@code{nil}. This | |
4267 | tells @ccmode{} to use XEmacs-specific built-in functions which, in some | |
4268 | circumstances, can locate the top-most opening brace much quicker than | |
4269 | @code{beginning-of-defun}. Preliminary testing has shown that for | |
4270 | styles where these braces are hung (e.g. most JDK-derived Java styles), | |
4271 | this hack can improve performance of the core syntax parsing routines | |
4272 | from 3 to 60 times. However, for styles which @emph{do} conform to | |
4273 | Emacs' recommended style of putting top-level braces in column zero, | |
4274 | this hack can degrade performance by about as much. Thus this variable | |
4275 | is set to @code{nil} by default, since the Emacs-friendly styles | |
4276 | should be more common (and | |
4277 | encouraged!). Note that this variable has no effect in Emacs since the | |
4278 | necessary built-in functions don't exist (in Emacs 20.2 or 20.3 as of | |
4279 | this writing 27-Apr-1998). | |
6bf7aab6 DL |
4280 | |
4281 | You will probably notice pathological behavior from @ccmode{} when | |
4282 | working in files containing large amounts of C preprocessor macros. | |
4283 | This is because Emacs cannot skip backwards over these lines as quickly | |
d7bd46ed | 4284 | as it can comments. |
6bf7aab6 DL |
4285 | |
4286 | @vindex c-recognize-knr-p | |
4287 | @vindex recognize-knr-p (c-) | |
4288 | Previous versions of @ccmode{} had potential performance problems | |
4289 | when recognizing K&R style function argument declarations. This was | |
4290 | because there are ambiguities in the C syntax when K&R style argument | |
4291 | lists are used@footnote{It is hard to distinguish them from top-level | |
4292 | declarations.}. @ccmode{} has adopted BOCM's convention for | |
4293 | limiting the search: it assumes that argdecls are indented at least one | |
4294 | space, and that the function headers are not indented at all. With | |
4295 | current versions of @ccmode{}, user customization of | |
4296 | @code{c-recognize-knr-p} is deprecated. Just don't put argdecls in | |
4297 | column zero! | |
4298 | ||
4299 | @cindex @file{cc-lobotomy.el} file | |
4300 | @vindex cc-lobotomy-pith-list | |
4301 | You might want to investigate the speed-ups contained in the | |
4302 | file @file{cc-lobotomy.el}, which comes as part of the @ccmode{} | |
4303 | distribution, but is completely unsupported. | |
4304 | As mentioned previous, @ccmode{} always trades speed for accuracy, | |
4305 | however it is recognized that sometimes you need speed and can sacrifice | |
4306 | some accuracy in indentation. The file @file{cc-lobotomy.el} contains | |
4307 | hacks that will ``dumb down'' @ccmode{} in some specific ways, making | |
4308 | that trade-off of accurancy for speed. I won't go into details of its | |
4309 | use here; you should read the comments at the top of the file, and look | |
4310 | at the variable @code{cc-lobotomy-pith-list} for details. | |
4311 | ||
4312 | ||
cb7f2e96 GM |
4313 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
4314 | @node Limitations and Known Bugs, Frequently Asked Questions, Performance Issues, Top | |
4315 | @comment node-name, next, previous, up | |
4316 | @chapter Limitations and Known Bugs | |
4317 | @cindex limitations | |
4318 | @cindex bugs | |
4319 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
4320 | ||
4321 | @itemize @bullet | |
4322 | @item | |
4323 | Re-indenting large regions or expressions can be slow. | |
4324 | ||
4325 | @findex c-indent-exp | |
4326 | @findex indent-exp (c-) | |
4327 | @item | |
4328 | @code{c-indent-exp} has not been fully optimized. It essentially | |
4329 | equivalent to hitting @kbd{TAB} (@code{c-indent-command}) on every | |
4330 | line. Some information is cached from line to line, but such caching | |
4331 | invariable causes inaccuracies in analysis in some bizarre situations. | |
4332 | ||
4333 | @vindex signal-error-on-buffer-boundary | |
4334 | @item | |
4335 | XEmacs versions from 19.15 until (as of this writing 12-Mar-1998) 20.4 | |
4336 | contain a variable called @code{signal-error-on-buffer-boundary}. This | |
4337 | was intended as a solution to user interface problems associated with | |
4338 | buffer movement and the @code{zmacs-region} deactivation on errors. | |
4339 | However, setting this variable to a non-default value had the | |
4340 | deleterious side effect of breaking many built-in primitive functions. | |
4341 | Most users will not be affected since they never change the value of | |
4342 | this variable. @strong{Do not set this variable to @code{nil}}; you | |
4343 | will cause serious problems in @ccmode{} and probably other XEmacs | |
4344 | packages! As of at least XEmacs 20.4, the effects this variable tried | |
4345 | to correct have been fixed in other, better ways. | |
4346 | ||
4347 | @end itemize | |
4348 | ||
4349 | ||
6bf7aab6 | 4350 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
cb7f2e96 | 4351 | @node Frequently Asked Questions, Getting the Latest CC Mode Release, Limitations and Known Bugs, Top |
d7bd46ed | 4352 | @comment node-name, next, previous, up |
cb7f2e96 | 4353 | @appendix Frequently Asked Questions |
d7bd46ed GM |
4354 | @cindex frequently asked questions |
4355 | @cindex FAQ | |
6bf7aab6 DL |
4356 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
4357 | ||
4358 | @kindex C-x h | |
d7bd46ed GM |
4359 | @kindex C-M-\ |
4360 | @kindex C-M-x | |
4361 | @kindex C-M-q | |
4362 | @kindex C-M-u | |
6bf7aab6 DL |
4363 | @kindex RET |
4364 | @kindex C-j | |
6bf7aab6 DL |
4365 | @quotation |
4366 | ||
4367 | @strong{Q.} @emph{How do I re-indent the whole file?} | |
4368 | ||
4369 | @strong{A.} Visit the file and hit @kbd{C-x h} to mark the whole | |
d7bd46ed | 4370 | buffer. Then hit @kbd{C-M-\}. |
6bf7aab6 | 4371 | |
d7bd46ed | 4372 | @sp 1 |
6bf7aab6 | 4373 | @strong{Q.} @emph{How do I re-indent the entire function? |
d7bd46ed | 4374 | @kbd{C-M-x} doesn't work.} |
6bf7aab6 | 4375 | |
d7bd46ed | 4376 | @strong{A.} @kbd{C-M-x} is reserved for future Emacs use. |
6bf7aab6 | 4377 | To re-indent the entire function hit @kbd{C-c C-q}. |
6bf7aab6 | 4378 | |
d7bd46ed | 4379 | @sp 1 |
6bf7aab6 DL |
4380 | @strong{Q.} @emph{How do I re-indent the current block?} |
4381 | ||
4382 | @strong{A.} First move to the brace which opens the block with | |
d7bd46ed GM |
4383 | @kbd{C-M-u}, then re-indent that expression with |
4384 | @kbd{C-M-q}. | |
6bf7aab6 | 4385 | |
d7bd46ed GM |
4386 | @sp 1 |
4387 | @strong{Q.} @emph{Why doesn't the @kbd{RET} key indent the new line?} | |
6bf7aab6 DL |
4388 | |
4389 | @strong{A.} Emacs' convention is that @kbd{RET} just adds a newline, | |
4390 | and that @kbd{C-j} adds a newline and indents it. You can make | |
4391 | @kbd{RET} do this too by adding this to your | |
d7bd46ed | 4392 | @code{c-mode-common-hook}: |
6bf7aab6 DL |
4393 | @example |
4394 | ||
d7bd46ed | 4395 | (define-key c-mode-base-map "\C-m" 'c-context-line-break) |
6bf7aab6 DL |
4396 | |
4397 | @end example | |
4398 | ||
4399 | This is a very common question. If you want this to be the default | |
d7bd46ed | 4400 | behavior, don't lobby me, lobby RMS! @t{:-)} |
6bf7aab6 | 4401 | |
d7bd46ed | 4402 | @sp 1 |
6bf7aab6 DL |
4403 | @strong{Q.} @emph{I put @code{(c-set-offset 'substatement-open 0)} |
4404 | in my @file{.emacs} file but I get an error saying that | |
4405 | @code{c-set-offset}'s function definition is void.} | |
4406 | ||
4407 | @strong{A.} This means that @ccmode{} wasn't loaded into your | |
4408 | Emacs session by the time the @code{c-set-offset} call was reached, | |
cb7f2e96 | 4409 | most likely because @ccmode{} is being autoloaded. Instead |
6bf7aab6 DL |
4410 | of putting the @code{c-set-offset} line in your top-level |
4411 | @file{.emacs} file, put it in your @code{c-mode-common-hook}, or | |
d7bd46ed | 4412 | simply modify @code{c-offsets-alist} directly: |
6bf7aab6 DL |
4413 | @example |
4414 | ||
f214c025 GM |
4415 | (setq c-offsets-alist '((substatement-open . 0))) |
4416 | ||
6bf7aab6 DL |
4417 | @end example |
4418 | ||
6bf7aab6 DL |
4419 | @sp 1 |
4420 | @strong{Q.} @emph{How do I make strings, comments, keywords, and other | |
4421 | constructs appear in different colors, or in bold face, etc.?} | |
4422 | ||
4423 | @strong{A.} ``Syntax Colorization'' is a standard Emacs feature, | |
d7bd46ed GM |
4424 | controlled by @code{font-lock-mode}. @ccmode{} does not contain |
4425 | font-lock definitions for any of its supported languages. | |
6bf7aab6 DL |
4426 | |
4427 | @sp 1 | |
4428 | @strong{Q.} @emph{@kbd{M-a} and @kbd{M-e} used to move over entire | |
4429 | balanced brace lists, but now they move into blocks. How do I get the | |
4430 | old behavior back?} | |
4431 | ||
4432 | @strong{A.} Use @kbd{C-M-f} and @kbd{C-M-b} to move over balanced brace | |
4433 | blocks. Use @kbd{M-a} and @kbd{M-e} to move by statements, which will | |
d7bd46ed GM |
4434 | also move into blocks. |
4435 | ||
4436 | @sp 1 | |
4437 | @strong{Q.} @emph{Whenever I try to indent a line or type an | |
4438 | ``electric'' key such as @kbd{;}, @kbd{@{}, or @kbd{@}}, I get an error | |
4439 | that look like this: @code{Invalid function: (macro . #[...}. What | |
4440 | gives?} | |
4441 | ||
4442 | @strong{A.} This is a common error when @ccmode{} hasn't been compiled | |
4443 | correctly, especially under Emacs 19.34@footnote{Technically, it's | |
4444 | because some macros wasn't defined during the compilation, so the byte | |
4445 | compiler put in function calls instead of the macro expansions. Later, | |
4446 | when the interpreter tries to call the macros as functions, it shows | |
4447 | this (somewhat cryptic) error message.}. If you are using the standalone | |
4448 | @ccmode{} distribution, try recompiling it according to the instructions | |
4449 | in the @file{README} file. | |
6bf7aab6 DL |
4450 | |
4451 | @end quotation | |
4452 | ||
4453 | ||
4454 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
cb7f2e96 | 4455 | @node Getting the Latest CC Mode Release, Mailing Lists and Submitting Bug Reports, Frequently Asked Questions, Top |
d7bd46ed | 4456 | @comment node-name, next, previous, up |
cb7f2e96 | 4457 | @appendix Getting the Latest CC Mode Release |
6bf7aab6 DL |
4458 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
4459 | ||
d7bd46ed GM |
4460 | @ccmode{} is standard with all versions of Emacs since 19.34 and of |
4461 | XEmacs since 19.16. | |
4462 | ||
4463 | Due to release schedule skew, it is likely that all of these Emacsen | |
4464 | have old versions of @ccmode{} and so should be upgraded. Access to the | |
4465 | @ccmode{} source code, as well as more detailed information on Emacsen | |
4466 | compatibility, etc. are all available via the Web at: | |
6bf7aab6 DL |
4467 | |
4468 | @example | |
4469 | @group | |
4470 | ||
f214c025 | 4471 | @uref{http://cc-mode.sourceforge.net/} |
6bf7aab6 DL |
4472 | |
4473 | @end group | |
4474 | @end example | |
4475 | ||
d7bd46ed GM |
4476 | @emph{Old URLs, including the FTP URLs, should no longer be used.} |
4477 | ||
6bf7aab6 DL |
4478 | There are many files under these directories; you can pick up the entire |
4479 | distribution (named @code{cc-mode.tar.gz}; a gzip'd tar file), or any of | |
4480 | the individual files, including PostScript documentation. | |
4481 | ||
6bf7aab6 | 4482 | |
cb7f2e96 GM |
4483 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
4484 | @node Mailing Lists and Submitting Bug Reports, Sample .emacs File, Getting the Latest CC Mode Release, Top | |
4485 | @comment node-name, next, previous, up | |
4486 | @appendix Mailing Lists and Submitting Bug Reports | |
4487 | @cindex mailing lists | |
4488 | @cindex reporting bugs | |
4489 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! | |
4490 | ||
4491 | @kindex C-c C-b | |
4492 | @findex c-submit-bug-report | |
4493 | @findex submit-bug-report (c-) | |
4494 | To report bugs, use the @kbd{C-c C-b} (@code{c-submit-bug-report}) | |
4495 | command. This provides vital information we need to reproduce your | |
4496 | problem. Make sure you include a concise, but complete code example. | |
4497 | Please try to boil your example down to just the essential code needed | |
4498 | to reproduce the problem, and include an exact recipe of steps needed to | |
4499 | expose the bug. Be especially sure to include any code that appears | |
4500 | @emph{before} your bug example, if you think it might affect our ability | |
4501 | to reproduce it. | |
4502 | ||
4503 | Please try to produce the problem in an Emacs instance without any | |
4504 | customizations loaded (i.e. start it with the @code{-q -no-site-file} | |
4505 | arguments). If it works correctly there, the problem might be caused by | |
4506 | faulty customizations in either your own or your site configuration. In | |
4507 | that case, we'd appreciate if you isolate the Emacs Lisp code that trigs | |
4508 | the bug and include it in your report. | |
4509 | ||
4510 | @cindex bug report mailing list | |
4511 | Bug reports are now sent to the following email addresses: | |
4512 | @email{bug-cc-mode@@gnu.org} and @email{bug-gnu-emacs@@gnu.org}; the | |
4513 | latter is mirrored on the Usenet newsgroup @code{gnu.emacs.bug}. You | |
4514 | can send other questions and suggestions (kudos? @t{;-)} to | |
4515 | @email{bug-cc-mode@@gnu.org}. | |
4516 | ||
4517 | @cindex announcement mailing list | |
4518 | If you want to get announcements of new @ccmode{} releases, send the | |
4519 | word @emph{subscribe} in the body of a message to | |
4520 | @email{cc-mode-announce-request@@lists.sourceforge.net}. Announcements | |
4521 | will also be posted to the Usenet newsgroups @code{gnu.emacs.sources}, | |
4522 | @code{comp.emacs} and @code{comp.emacs.xemacs}. | |
4523 | ||
4524 | ||
6bf7aab6 | 4525 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
cb7f2e96 | 4526 | @node Sample .emacs File, Concept Index, Mailing Lists and Submitting Bug Reports, Top |
d7bd46ed | 4527 | @comment node-name, next, previous, up |
cb7f2e96 | 4528 | @appendix Sample .emacs file |
6bf7aab6 DL |
4529 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
4530 | ||
4531 | @example | |
4532 | ;; Here's a sample .emacs file that might help you along the way. Just | |
4533 | ;; copy this region and paste it into your .emacs file. You may want to | |
4534 | ;; change some of the actual values. | |
4535 | ||
4536 | (defconst my-c-style | |
4537 | '((c-tab-always-indent . t) | |
4538 | (c-comment-only-line-offset . 4) | |
4539 | (c-hanging-braces-alist . ((substatement-open after) | |
4540 | (brace-list-open))) | |
4541 | (c-hanging-colons-alist . ((member-init-intro before) | |
4542 | (inher-intro) | |
4543 | (case-label after) | |
4544 | (label after) | |
4545 | (access-label after))) | |
4546 | (c-cleanup-list . (scope-operator | |
4547 | empty-defun-braces | |
4548 | defun-close-semi)) | |
4549 | (c-offsets-alist . ((arglist-close . c-lineup-arglist) | |
4550 | (substatement-open . 0) | |
4551 | (case-label . 4) | |
4552 | (block-open . 0) | |
4553 | (knr-argdecl-intro . -))) | |
4554 | (c-echo-syntactic-information-p . t) | |
4555 | ) | |
4556 | "My C Programming Style") | |
4557 | ||
d7bd46ed | 4558 | ;; offset customizations not in my-c-style |
f214c025 | 4559 | (setq c-offsets-alist '((member-init-intro . ++))) |
d7bd46ed GM |
4560 | |
4561 | ;; Customizations for all modes in CC Mode. | |
6bf7aab6 DL |
4562 | (defun my-c-mode-common-hook () |
4563 | ;; add my personal style and set it for the current buffer | |
4564 | (c-add-style "PERSONAL" my-c-style t) | |
6bf7aab6 DL |
4565 | ;; other customizations |
4566 | (setq tab-width 8 | |
4567 | ;; this will make sure spaces are used instead of tabs | |
4568 | indent-tabs-mode nil) | |
4569 | ;; we like auto-newline and hungry-delete | |
4570 | (c-toggle-auto-hungry-state 1) | |
47d7776c | 4571 | ;; key bindings for all supported languages. We can put these in |
6bf7aab6 | 4572 | ;; c-mode-base-map because c-mode-map, c++-mode-map, objc-mode-map, |
d7bd46ed GM |
4573 | ;; java-mode-map, idl-mode-map, and pike-mode-map inherit from it. |
4574 | (define-key c-mode-base-map "\C-m" 'c-context-line-break) | |
6bf7aab6 DL |
4575 | ) |
4576 | ||
4577 | (add-hook 'c-mode-common-hook 'my-c-mode-common-hook) | |
4578 | @end example | |
4579 | ||
d7bd46ed | 4580 | |
6bf7aab6 | 4581 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
cb7f2e96 | 4582 | @node Concept Index, Command Index, Sample .emacs File, Top |
d7bd46ed | 4583 | @comment node-name, next, previous, up |
6bf7aab6 | 4584 | @unnumbered Concept Index |
d7bd46ed | 4585 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
6bf7aab6 DL |
4586 | |
4587 | @printindex cp | |
4588 | ||
4589 | ||
d7bd46ed GM |
4590 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
4591 | @node Command Index, Key Index, Concept Index, Top | |
4592 | @comment node-name, next, previous, up | |
6bf7aab6 | 4593 | @unnumbered Command Index |
d7bd46ed | 4594 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
6bf7aab6 | 4595 | |
d7bd46ed | 4596 | Since most @ccmode{} commands are prepended with the string |
6bf7aab6 DL |
4597 | @samp{c-}, each appears under its @code{c-@var{<thing>}} name and its |
4598 | @code{@var{<thing>} (c-)} name. | |
4599 | @iftex | |
4600 | @sp 2 | |
4601 | @end iftex | |
4602 | @printindex fn | |
4603 | ||
4604 | ||
d7bd46ed GM |
4605 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
4606 | @node Key Index, Variable Index, Command Index, Top | |
4607 | @comment node-name, next, previous, up | |
6bf7aab6 | 4608 | @unnumbered Key Index |
d7bd46ed | 4609 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
6bf7aab6 DL |
4610 | |
4611 | @printindex ky | |
4612 | ||
4613 | ||
d7bd46ed GM |
4614 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
4615 | @node Variable Index, , Key Index, Top | |
4616 | @comment node-name, next, previous, up | |
6bf7aab6 | 4617 | @unnumbered Variable Index |
d7bd46ed | 4618 | @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |
6bf7aab6 | 4619 | |
d7bd46ed | 4620 | Since most @ccmode{} variables are prepended with the string |
6bf7aab6 DL |
4621 | @samp{c-}, each appears under its @code{c-@var{<thing>}} name and its |
4622 | @code{@var{<thing>} (c-)} name. | |
4623 | @iftex | |
4624 | @sp 2 | |
4625 | @end iftex | |
4626 | @printindex vr | |
cb7f2e96 GM |
4627 | |
4628 | @iftex | |
6bf7aab6 DL |
4629 | @page |
4630 | @summarycontents | |
4631 | @contents | |
cb7f2e96 GM |
4632 | @end iftex |
4633 | ||
6bf7aab6 | 4634 | @bye |