3 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4 @comment %**start of header (This is for running Texinfo on a region)
5 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
7 @setfilename ../info/ccmode
8 @settitle CC MODE Version 5 Documentation
13 * CC mode: (ccmode). The GNU Emacs mode for editing C, C++, Objective-C
17 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
18 @comment @setchapternewpage odd !! we don't want blank pages !!
19 @comment %**end of header (This is for running Texinfo on a region)
20 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
23 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
25 @comment Texinfo manual for CC Mode
26 @comment Generated from the original README file by Krishna Padmasola
27 @comment <krishna@earth-gw.njit.edu>
29 @comment Maintained by Barry A. Warsaw <cc-mode-help@python.org>
31 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
34 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
35 @comment The following line inserts the copyright notice
36 @comment into the Info file.
37 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
40 Copyright @copyright{} 1995,96,97,98 Free Software Foundation, Inc.
43 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
44 @comment !!!The titlepage section does not appear in the Info file.!!!
45 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
51 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
52 @comment The title is printed in a large font.
53 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
55 @center @titlefont{CC Mode 5.21}
57 @center @subtitlefont{A GNU Emacs mode for editing C and C-like languages}
59 @center Barry A. Warsaw
62 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
63 @comment The following two commands start the copyright page
64 @comment for the printed manual. This will not appear in the Info file.
65 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
68 @vskip 0pt plus 1filll
69 Copyright @copyright{} 1995,96,97,98 Free Software Foundation, Inc.
73 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
74 @comment The Top node contains the master menu for the Info file.
75 @comment This appears only in the Info file, not the printed manual.
76 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
78 @node Top, Introduction, (dir), (dir)
79 @comment node-name, next, previous, up
82 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
83 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
88 * New Indentation Engine::
91 * Customizing Indentation::
93 * Performance Issues::
94 * Frequently Asked Questions::
95 * Getting the latest CC Mode release::
96 * Sample .emacs File::
97 * Limitations and Known Bugs::
98 * Mailing Lists and Submitting Bug Reports::
100 * Command Index:: Command Index
101 * Key Index:: Key Index
102 * Variable Index:: Variable Index
105 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
106 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
108 @node Introduction, Getting Connected, Top, Top
109 @comment node-name, next, previous, up
110 @chapter Introduction
119 Welcome to @ccmode{}. This is a GNU Emacs mode for editing files
120 containing C, C++, Objective-C, Java, and CORBA IDL code. This
121 incarnation of the mode is descendant from @file{c-mode.el} (also called
122 "Boring Old C Mode" or BOCM @code{:-)}, and @file{c++-mode.el} version
123 2, which I have been maintaining since 1992. @ccmode{} represents a
124 significant milestone in the mode's life. It has been fully merged back
125 with Emacs 19's @file{c-mode.el}. Also a new, more intuitive and
126 flexible mechanism for controlling indentation has been developed.
128 @ccmode{} supports the editing of K&R and ANSI C, @dfn{ARM}
129 @footnote{``The Annotated C++ Reference Manual'', by Ellis and
130 Stroustrup.} C++, Objective-C, Java and CORBA's Interface
131 Definition Language files. In this way, you can
132 easily set up consistent coding styles for use in editing all C, C++,
133 Objective-C, Java and IDL programs. @ccmode{} does @emph{not} handle
134 font-locking (a.k.a. syntax coloring, keyword highlighting) or anything
135 of that nature, for any of these modes. Font-locking is handled by other
138 This manual will describe the following:
142 How to get started using @ccmode{}.
145 How the new indentation engine works.
148 How to customize the new indentation engine.
157 Note that the name of this package is ``@ccmode{}'', but there is no top
158 level @code{cc-mode} entry point. All of the variables, commands, and
159 functions in @ccmode{} are prefixed with @code{c-@var{<thing>}}, and
160 @code{c-mode}, @code{c++-mode}, @code{objc-mode}, @code{java-mode}, and
161 @code{idl-mode} entry points are provided. This file is intended to be
162 a replacement for @file{c-mode.el} and @file{c++-mode.el}.
164 @cindex @file{cc-compat.el} file
165 This distribution also contains a file
166 called @file{cc-compat.el} which should ease your transition from BOCM
167 to @ccmode{}. If you have a BOCM configuration you are really happy
168 with, and want to postpone learning how to configure @ccmode{}, take a
169 look at that file. It maps BOCM configuration variables to @ccmode{}'s
170 new indentation model. It is not actively supported so for the long
171 run, you should learn how to customize @ccmode{} to support your coding
174 A special word of thanks goes to Krishna Padmasola for his work in
175 converting the original @file{README} file to Texinfo format. I'd also
176 like to thank all the @ccmode{} victims who help enormously during the
177 early beta stages of @ccmode{}'s development.
180 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
182 @node Getting Connected, New Indentation Engine, Introduction, Top
183 @comment node-name, next, previous, up
184 @chapter Getting Connected
185 @cindex Getting Connected
187 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
189 If you got this version of @ccmode{} with Emacs or XEmacs, it should
190 work just fine right out of the box. Note however that you may not have
191 the latest @ccmode{} release and may want to upgrade your copy.
193 If you are upgrading an existing @ccmode{} installation, please see the
194 @file{README} file for installation details. @ccmode{} may not work
195 with older versions of Emacs or XEmacs. See the @ccmode{} release notes
196 Web pages for the latest information on Emacs version and package
197 compatibility (see @ref{Getting the latest CC Mode release}).
199 @cindex @file{cc-mode-18.el} file
200 @emph{Note that @ccmode{} no longer works with Emacs 18!} The
201 @file{cc-mode-18.el} file is no longer distributed with @ccmode{}. If
202 you haven't upgraded from Emacs 18 by now, you are out of luck.
206 You can find out what version of @ccmode{} you are using by visiting a C
207 file and entering @kbd{M-x c-version RET}. You should see this message in
211 Using CC Mode version 5.XX
216 where @samp{XX} is the minor release number.
219 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
220 @node New Indentation Engine, Minor Modes, Getting Connected, Top
221 @comment node-name, next, previous, up
223 @chapter New Indentation Engine
224 @cindex New Indentation Engine
225 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
227 @ccmode{} has a new indentation engine, providing a simplified, yet
228 flexible and general mechanism for customizing indentation. It separates
229 indentation calculation into two steps: first, @ccmode{} analyzes the
230 line of code being indented to determine the kind of language construct
231 it's looking at, then it applies user defined offsets to the current
232 line based on this analysis.
234 This section will briefly cover how indentation is calculated in
235 @ccmode{}. It is important to understand the indentation model
236 being used so that you will know how to customize @ccmode{} for
237 your personal coding style.
240 * Syntactic Analysis::
241 * Indentation Calculation::
245 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
246 @node Syntactic Analysis, Indentation Calculation, , New Indentation Engine
247 @comment node-name, next, previous,up
248 @section Syntactic Analysis
249 @cindex Syntactic Analysis
250 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
252 @vindex c-offsets-alist
253 @vindex offsets-alist (c-)
254 @cindex relative buffer position
255 @cindex syntactic symbol
256 @cindex syntactic component
257 @cindex syntactic component list
258 @cindex relative buffer position
259 The first thing @ccmode{} does when indenting a line of code, is to
260 analyze the line, determining the @dfn{syntactic component list} of the
261 construct on that line. A syntactic component consists of a pair
262 of information (in lisp parlance, a @emph{cons cell}), where the first
263 part is a @dfn{syntactic symbol}, and the second part is a @dfn{relative
264 buffer position}. Syntactic symbols describe elements of C code
265 @footnote{or C++, Objective-C, Java or IDL code. In general, for the rest
266 of this manual I'll use the term ``C code'' to refer to all the C-like
267 dialects, unless otherwise noted.}, e.g. @code{statement},
268 @code{substatement}, @code{class-open}, @code{class-close}, etc.
269 @xref{Syntactic Symbols}, for a complete list of currently recognized
270 syntactic symbols and their semantics. The variable
271 @code{c-offsets-alist} also contains the list of currently supported
274 Conceptually, a line of C code is always indented relative to the
275 indentation of some line higher up in the buffer. This is represented
276 by the relative buffer position in the syntactic component.
278 Here is an example. Suppose we had the following code as the only thing
279 in a @code{c++-mode} buffer @footnote{The line numbers in this and
280 future examples don't actually appear in the buffer, of course!}:
284 1: void swap( int& a, int& b )
295 @findex c-show-syntactic-information
296 @findex show-syntactic-information (c-)
297 We can use the command @kbd{C-c C-s}
298 (@code{c-show-syntactic-information}) to simply report what the
299 syntactic analysis is for the current line. Running this command on
300 line 4 of this example, we'd see in the echo area@footnote{With a universal
301 argument (i.e. @kbd{C-u C-c C-s}) the analysis is inserted into the
303 on the current line.}:
310 This tells us that the line is a statement and it is indented relative
311 to buffer position 35, which happens to be the @samp{i} in @code{int} on
312 line 3. If you were to move point to line 3 and hit @kbd{C-c C-s}, you
316 ((defun-block-intro . 29))
320 This indicates that the @samp{int} line is the first statement in a top
321 level function block, and is indented relative to buffer position 29,
322 which is the brace just after the function header.
324 Here's another example:
328 1: int add( int val, int incr, int doit )
332 5: return( val + incr );
341 Hitting @kbd{C-c C-s} on line 4 gives us:
344 ((substatement-open . 46))
349 @cindex substatment block
351 which tells us that this is a brace that @emph{opens} a substatement
352 block. @footnote{A @dfn{substatement} is the line after a
353 conditional statement, such as @code{if}, @code{else}, @code{while},
354 @code{do}, @code{switch}, etc. A @dfn{substatement
355 block} is a brace block following one of these conditional statements.}
357 @cindex comment-only line
358 Syntactic component lists can contain more than one component, and
359 individual syntactic components need not have relative buffer positions.
360 The most common example of this is a line that contains a @dfn{comment
365 1: void draw_list( List<Drawables>& drawables )
367 3: // call the virtual draw() method on each element in list
368 4: for( int i=0; i < drawables.count(), ++i )
370 6: drawables[i].draw();
378 Hitting @kbd{C-c C-s} on line 3 of this example gives:
381 ((comment-intro) (defun-block-intro . 46))
386 and you can see that the syntactic component list contains two syntactic
387 components. Also notice that the first component,
388 @samp{(comment-intro)} has no relative buffer position.
391 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
392 @node Indentation Calculation, , Syntactic Analysis, New Indentation Engine
393 @comment node-name, next, previous,up
394 @section Indentation Calculation
395 @cindex Indentation Calculation
396 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
398 @vindex c-offsets-alist
399 @vindex offsets-alist (c-)
400 Indentation for a line is calculated using the syntactic
401 component list derived in step 1 above (see @ref{Syntactic Analysis}).
402 Each component contributes to the final total indentation of the line in
405 First, the syntactic symbols are looked up in the @code{c-offsets-alist}
406 variable, which is an association list of syntactic symbols and the
407 offsets to apply for those symbols. These offsets are added to a
410 Second, if the component has a relative buffer position, @ccmode{}
411 adds the column number of that position to the running total. By adding
412 up the offsets and columns for every syntactic component on the list,
413 the final total indentation for the current line is computed.
415 Let's use our two code examples above to see how this works. Here is
416 our first example again:
420 1: void swap( int& a, int& b )
431 Let's say point is on line 3 and we hit the @kbd{TAB} key to re-indent
432 the line. Remember that the syntactic component list for that
436 ((defun-block-intro . 29))
441 @ccmode{} looks up @code{defun-block-intro} in the
442 @code{c-offsets-alist} variable. Let's say it finds the value @samp{4};
443 it adds this to the running total (initialized to zero), yielding a
444 running total indentation of 4 spaces.
446 Next @ccmode{} goes to buffer position 29 and asks for the current
447 column. This brace is in column zero, so @ccmode{}
448 adds @samp{0} to the running total. Since there is only one syntactic
449 component on the list for this line, indentation calculation is
450 complete, and the total indentation for the line
453 Here's another example:
457 1: int add( int val, int incr, int doit )
461 5: return( val + incr );
469 If we were to hit @kbd{TAB} on line 4 in the above example, the same
470 basic process is performed, despite the differences in the syntactic
471 component list. Remember that the list for this line is:
474 ((substatement-open . 46))
478 Here, @ccmode{} first looks up the @code{substatement-open} symbol
479 in @code{c-offsets-alist}. Let's say it finds the value @samp{4}. This
480 yields a running total of 4. @ccmode{} then goes to
481 buffer position 46, which is the @samp{i} in @code{if} on line 3. This
482 character is in the fourth column on that line so adding this to the
483 running total yields an indentation for the line of 8 spaces.
487 Actually, the mode usually just does The Right Thing without you having
488 to think about it in this much detail. But when customizing
489 indentation, it's helpful to understand the general indentation model
492 @vindex c-echo-syntactic-information-p
493 @vindex echo-syntactic-information-p (c-)
495 As you configure @ccmode{}, you might want to set the variable
496 @code{c-echo-syntactic-information-p} to non-@code{nil} so that the
497 syntactic component list and calculated offset will always be echoed in
498 the minibuffer when you hit @kbd{TAB}.
501 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
502 @node Minor Modes, Commands, New Indentation Engine, Top
503 @comment node-name, next, previous,up
507 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
509 @ccmode{} contains two minor-mode-like features that you should
510 find useful while you enter new C code. The first is called
511 @dfn{auto-newline} mode, and the second is called @dfn{hungry-delete}
512 mode. These minor modes can be toggled on and off independently, and
513 @ccmode{} can be configured so that it starts up with any
514 combination of these minor modes. By default, both of these minor modes
517 The state of the minor modes is always reflected in the minor mode list
518 on the modeline of the @ccmode{} buffer. When auto-newline mode is
519 enabled, you will see @samp{C/a} on the mode line @footnote{Remember
520 that the @samp{C} could be replaced with @samp{C++}, @samp{ObjC},
521 @samp{Java} or @samp{IDL}.}. When hungry delete mode is enabled you
522 would see @samp{C/h} and when both modes are enabled, you'd see
528 @findex c-toggle-hungry-state
529 @findex c-toggle-auto-state
530 @findex c-toggle-auto-hungry-state
531 @findex toggle-hungry-state (c-)
532 @findex toggle-auto-state (c-)
533 @findex toggle-auto-hungry-state (c-)
534 @ccmode{} provides keybindings which allow you to toggle the minor
535 modes on the fly while editing code. To toggle just the auto-newline
536 state, hit @kbd{C-c C-a} (@code{c-toggle-auto-state}). When you do
537 this, you should see the @samp{a} indicator either appear or disappear
538 on the modeline. Similarly, to toggle just the hungry-delete state, use
539 @kbd{C-c C-d} (@code{c-toggle-hungry-state}), and to toggle both states,
540 use @kbd{C-c C-t} (@code{c-toggle-auto-hungry-state}).
542 To set up the auto-newline and hungry-delete states to your preferred
543 values, you would need to add some lisp to your @file{.emacs} file that
544 called one of the @code{c-toggle-*-state} functions directly. When
545 called programmatically, each function takes a numeric value, where
546 a positive number enables the minor mode, a negative number disables the
547 mode, and zero toggles the current state of the mode.
549 So for example, if you wanted to enable both auto-newline and
550 hungry-delete for all your C file editing, you could add the following
551 to your @file{.emacs} file:
554 (add-hook 'c-mode-common-hook
555 '(lambda () (c-toggle-auto-hungry-state 1)))
560 @cindex electric characters
563 * Auto-newline insertion::
564 * Hungry-deletion of whitespace::
565 * Auto-fill mode interaction::
568 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
569 @node Auto-newline insertion, Hungry-deletion of whitespace, , Minor Modes
570 @comment node-name, next, previous,up
572 @section Auto-newline insertion
573 @cindex Auto-newline insertion
574 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
576 @cindex electric commands
577 Auto-newline minor mode works by enabling certain @dfn{electric
578 commands}. Electric commands are typically bound to special characters
579 such as the left and right braces, colons, semi-colons, etc., which when
580 typed, perform some magic formatting in addition to inserting the typed
581 character. As a general rule, electric commands are only electric when
582 the following conditions apply:
586 Auto-newline minor mode is enabled, as evidenced by a @samp{C/a} or
587 @samp{C/ah} indicator on the modeline.
590 @cindex syntactic whitespace
592 The character was not typed inside of a literal @footnote{A
593 @dfn{literal} is defined as any comment, string, or C preprocessor macro
594 definition. These constructs are also known as @dfn{syntactic
595 whitespace} since they are usually ignored when scanning C code.}.
599 No numeric argument was supplied to the command (i.e. it was typed as
600 normal, with no @kbd{C-u} prefix).
607 * Hanging Semi-colons and commas::
608 * Other electric commands::
612 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
613 @node Hanging Braces, Hanging Colons, , Auto-newline insertion
614 @comment node-name, next, previous,up
616 @subsection Hanging Braces
617 @cindex Hanging Braces
618 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
620 @findex c-electric-brace
621 @findex electric-brace (c-)
622 @vindex c-hanging-braces-alist
623 @vindex hanging-braces-alist (c-)
624 @vindex c-offsets-alist
625 @vindex offsets-alist (c-)
626 When you type either an open or close brace (i.e. @kbd{@{} or @kbd{@}}),
627 the electric command @code{c-electric-brace} gets run. This command has
628 two electric formatting behaviors. First, it will perform some
629 re-indentation of the line the brace was typed on, and second, it will
630 add various newlines before and/or after the typed brace.
631 Re-indentation occurs automatically whenever the electric behavior is
632 enabled. If the brace ends up on a line other than the one it was typed
633 on, then that line is also re-indented.
635 @cindex class-open syntactic symbol
636 @cindex class-close syntactic symbol
637 @cindex defun-open syntactic symbol
638 @cindex defun-close syntactic symbol
639 @cindex inline-open syntactic symbol
640 @cindex inline-close syntactic symbol
641 @cindex brace-list-open syntactic symbol
642 @cindex brace-list-close syntactic symbol
643 @cindex brace-list-intro syntactic symbol
644 @cindex brace-list-entry syntactic symbol
645 @cindex block-open syntactic symbol
646 @cindex block-close syntactic symbol
647 @cindex substatement-open syntactic symbol
648 @cindex statement-case-open syntactic symbol
649 @cindex extern-lang-open syntactic symbol
650 @cindex extern-lang-close syntactic symbol
651 @cindex namespace-open symbol
652 @cindex namespace-close symbol
654 The insertion of newlines is controlled by the
655 @code{c-hanging-braces-alist} variable. This variable contains a
656 mapping between syntactic symbols related to braces, and a list of
657 places to insert a newline. The syntactic symbols that are useful for
658 this list are: @code{class-open}, @code{class-close}, @code{defun-open},
659 @code{defun-close}, @code{inline-open}, @code{inline-close},
660 @code{brace-list-open}, @code{brace-list-close},
661 @code{brace-list-intro}, @code{brace-list-entry}, @code{block-open},
662 @code{block-close}, @code{substatement-open},
663 @code{statement-case-open},
664 @code{extern-lang-open}, @code{extern-lang-close},
665 @code{namespace-open}, and @code{namespace-close}.
666 @xref{Syntactic Symbols}, for a more
667 detailed description of these syntactic symbols.
669 @cindex Custom Indentation Functions
670 The value associated with each syntactic symbol in this association list
671 is called an @var{ACTION} which can be either a function or a list.
672 @xref{Custom Brace and Colon Hanging}, for a more detailed discussion of
673 using a function as a brace hanging @var{ACTION}.
675 When the @var{ACTION} is a list, it can contain any combination of the
676 symbols @code{before} and @code{after}, directing @ccmode{} where to
677 put newlines in relationship to the brace being inserted. Thus, if the
678 list contains only the symbol @code{after}, then the brace is said to
679 @dfn{hang} on the right side of the line, as in:
683 // here, open braces always `hang'
684 void spam( int i ) @{
694 When the list contains both @code{after} and @code{before}, the braces
695 will appear on a line by themselves, as shown by the close braces in the
696 above example. The list can also be empty, in which case no newlines
697 are added either before or after the brace.
699 For example, the default value of @code{c-hanging-braces-alist} is:
703 (defvar c-hanging-braces-alist '((brace-list-open)
704 (substatement-open after)
705 (block-close . c-snug-do-while)
706 (extern-lang-open after)))
712 which says that @code{brace-list-open} braces should both hang on the
713 right side, and allow subsequent text to follow on the same line as the
714 brace. Also, @code{substatement-open} and @code{extern-lang-open}
715 braces should hang on the right side, but subsequent text should follow
716 on the next line. Here, in the @code{block-close} entry, you also see
717 an example of using a function as an @var{ACTION}.
719 A word of caution: it is not a good idea to hang top-level construct
720 introducing braces, such as @code{class-open} or @code{defun-open}.
721 Emacs makes an assumption that such braces will always appear in column
722 zero, hanging such braces can introduce performance problems.
723 @xref{Performance Issues}, for more information.
726 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
727 @node Hanging Colons, Hanging Semi-colons and commas, Hanging Braces, Auto-newline insertion
728 @comment node-name, next, previous,up
730 @subsection Hanging Colons
731 @cindex Hanging Colons
732 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
734 @vindex hanging-colons-alist (c-)
735 @vindex c-hanging-colons-alist
736 Using a mechanism similar to brace hanging (see @ref{Hanging Braces}),
737 colons can also be made to hang using the variable
738 @code{c-hanging-colons-alist}. The syntactic symbols appropriate for
739 this assocation list are: @code{case-label}, @code{label},
740 @code{access-label}, @code{member-init-intro}, and @code{inher-intro}.
741 Note however that for @code{c-hanging-colons-alist}, @var{ACTION}s as
742 functions are not supported. See also @ref{Custom Brace and Colon
743 Hanging} for details.
746 In C++, double-colons are used as a scope operator but because these
747 colons always appear right next to each other, newlines before and after
748 them are controlled by a different mechanism, called @dfn{clean-ups} in
749 @ccmode{}. @xref{Clean-ups}, for details.
752 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
753 @node Hanging Semi-colons and commas, Other electric commands, Hanging Colons, Auto-newline insertion
754 @comment node-name, next, previous,up
756 @subsection Hanging Semi-colons and commas
757 @cindex Hanging Semi-colons and commas
758 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
760 Semicolons and commas are also electric in @ccmode{}, but since
761 these characters do not correspond directly to syntactic symbols, a
762 different mechanism is used to determine whether newlines should be
763 automatically inserted after these characters. @xref{Customizing
764 Semi-colons and Commas}, for details.
767 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
768 @node Other electric commands, Clean-ups, Hanging Semi-colons and commas, Auto-newline insertion
769 @comment node-name, next, previous,up
771 @subsection Other electric commands
772 @cindex Other electric commands
773 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
776 @findex c-electric-pound
777 @vindex c-electric-pound-behavior
778 @findex electric-pound (c-)
779 @vindex electric-pound-behavior (c-)
780 @vindex c-offsets-alist
781 @vindex offsets-alist (c-)
782 A few other keys also provide electric behavior. For example
783 @kbd{#} (@code{c-electric-pound}) is electric when typed as
784 the first non-whitespace character on a line. In this case, the
785 variable @code{c-electric-pound-behavior} is consulted for the electric
786 behavior. This variable takes a list value, although the only element
787 currently defined is @code{alignleft}, which tells this command to force
788 the @samp{#} character into column zero. This is useful for entering
789 C preprocessor macro definitions.
791 @findex c-electric-star
792 @findex c-electric-slash
793 @findex electric-star (c-)
794 @findex electric-slash (c-)
795 @cindex comment-only line
796 Stars and slashes (i.e. @kbd{*} and @kbd{/}, @code{c-electric-star} and
797 @code{c-electric-slash} respectively) are also electric under
798 certain circumstances. If a star is inserted as the second character of
799 a C style block comment on a @dfn{comment-only} line, then the comment
800 delimiter is indented as defined by @code{c-offsets-alist}. A
801 comment-only line is defined as a line which contains only a comment, as
808 // this is a comment-only line...
809 if( i == 7 ) // but this is not
818 Likewise, if a slash is inserted as the second slash in a C++ style line
819 comment (also only on a comment-only line), then the line is indented as
820 defined by @code{c-offsets-alist}.
822 @findex c-electric-lt-gt
823 @findex electric-lt-gt (c-)
826 Less-than and greater-than signs (@code{c-electric-lt-gt}) are also
827 electric, but only in C++ mode. Hitting the second of two @kbd{<} or
828 @kbd{>} keys re-indents the line if it is a C++ style stream operator.
831 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
832 @node Clean-ups, , Other electric commands, Auto-newline insertion
833 @comment node-name, next, previous,up
835 @subsection Clean-ups
837 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
839 @dfn{Clean-ups} are a mechanism complementary to colon and brace
840 hanging. On the surface, it would seem that clean-ups overlap the
841 functionality provided by the @code{c-hanging-*-alist} variables, and
842 similarly, clean-ups are only enabled when auto-newline minor mode is
843 enabled. Clean-ups are used however to adjust code ``after-the-fact'',
844 i.e. to eliminate some whitespace that is inserted by electric
845 commands, or whitespace that contains intervening constructs.
848 You can configure @ccmode{}'s clean-ups by setting the variable
849 @code{c-cleanup-list}, which is a list of clean-up symbols. By default,
850 @ccmode{} cleans up only the @code{scope-operator} construct, which
851 is necessary for proper C++ support. Note that clean-ups are only
852 performed when the construct does not occur within a literal (see
853 @ref{Auto-newline insertion}), and when there is nothing but whitespace
854 appearing between the individual components of the construct.
856 @vindex c-cleanup-list
857 @vindex cleanup-list (c-)
858 There are currently only five specific constructs that @ccmode{}
859 can clean up, as indicated by these symbols:
863 @code{brace-else-brace} --- cleans up @samp{@} else @{} constructs by
864 placing the entire construct on a single line. Clean-up occurs when the
865 open brace after the @samp{else} is typed. So for example, this:
881 appears like this after the open brace is typed:
895 @code{brace-elseif-brace} --- similar to the @code{brace-else-brace}
896 clean-up, but this cleans up @samp{@} else if (...) @{} constructs. For
912 appears like this after the open brace is typed:
920 @} else if( i==3 ) @{
926 @code{empty-defun-braces} --- cleans up braces following a top-level
927 function or class definition that contains no body. Clean up occurs
928 when the closing brace is typed. Thus the following:
939 is transformed into this when the close brace is typed:
950 @code{defun-close-semi} --- cleans up the terminating semi-colon on
951 top-level function or class definitions when they follow a close
952 brace. Clean up occurs when the semi-colon is typed.
953 So for example, the following:
965 is transformed into this when the semi-colon is typed:
978 @code{list-close-comma} --- cleans up commas following braces in array
979 and aggregate initializers. Clean up occurs when the comma is typed.
982 @code{scope-operator} --- cleans up double colons which may designate a
983 C++ scope operator split across multiple lines@footnote{Certain C++
984 constructs introduce ambiguous situations, so @code{scope-operator}
985 clean-ups may not always be correct. This usually only occurs when
986 scoped identifiers appear in switch label tags.}. Clean up occurs when
987 the second colon is typed. You will always want @code{scope-operator}
988 in the @code{c-cleanup-list} when you are editing C++ code.
993 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
994 @node Hungry-deletion of whitespace, Auto-fill mode interaction, Auto-newline insertion, Minor Modes
995 @comment node-name, next, previous,up
997 @section Hungry-deletion of whitespace
998 @cindex Hungry-deletion of whitespace
999 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1001 Hungry deletion of whitespace, or as it more commonly called,
1002 @dfn{hungry-delete mode}, is a simple feature that some people find
1003 extremely useful. In fact, you might find yourself wanting
1004 hungry-delete in @strong{all} your editing modes!
1008 In a nutshell, when hungry-delete mode is enabled, hitting the
1009 @key{Backspace} key@footnote{I say ``hit the @key{Backspace} key'' but
1010 what I really mean is ``when Emacs receives the @code{BackSpace} key
1011 event''. The difference usually isn't significant to most users, but
1012 advanced users will realize that under window systems such as X, any
1013 physical key (keycap) on the keyboard can be configured to generate any
1014 keysym, and thus any Emacs key event. Also, the use of Emacs on TTYs
1015 will affect which keycap generates which key event. From a pedantic
1016 point of view, here we are only concerned with the key event that
1017 Emacs receives.} will consume all preceding whitespace, including
1018 newlines and tabs. This can really cut down on the number of
1019 @key{Backspace}'s you have to type if, for example you made a mistake on
1022 @findex c-electric-backspace
1023 @findex electric-backspace (c-)
1024 @vindex c-backspace-function
1025 @vindex backspace-function (c-)
1027 @findex c-electric-delete
1028 @findex electric-delete (c-)
1029 @vindex c-delete-function
1030 @vindex delete-function (c-)
1033 @findex backward-delete-char-untabify
1035 By default, when you hit the @key{Backspace} key
1036 @ccmode{} runs the command @code{c-electric-backspace}, which deletes
1037 text in the backwards direction. When deleting a single character, or
1038 when @key{Backspace} is hit in a literal
1039 (see @ref{Auto-newline insertion}),
1040 or when hungry-delete mode is disabled, the function
1041 contained in the @code{c-backspace-function} variable is called with one
1042 argument (the number of characters to delete). This variable is set to
1043 @code{backward-delete-char-untabify} by default.
1045 @vindex delete-key-deletes-forward
1048 Similarly, hitting the @key{Delete} key runs the command
1049 @code{c-electric-delete}. When deleting a single character, or when
1050 @key{Delete} is hit in a literal, or when hungry-delete mode is
1051 disabled, the function contained in the @code{c-delete-function}
1052 variable is called with one argument (the number of characters to
1053 delete). This variable is set to @code{delete-char} by default.
1055 However, if @code{delete-key-deletes-forward} is @code{nil}, or your
1056 Emacs does not support separation of @key{Backspace} and @key{DEL}, then
1057 @code{c-electric-delete} simply calls @code{c-electric-backspace}.
1060 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1061 @node Auto-fill mode interaction, , Hungry-deletion of whitespace, Minor Modes
1062 @comment node-name, next, previous,up
1064 @section Auto-fill mode interaction
1065 @cindex Auto-fill mode interaction
1066 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1068 One other note about minor modes is worth mentioning here. CC Mode now
1069 works much better with auto-fill mode (a standard Emacs minor mode) by
1070 correctly auto-filling both line (e.g. C++ style) and block (e.g. C
1071 style) oriented comments. When @code{auto-fill-mode} is enabled, line
1072 oriented comments will also be auto-filled by inserting a newline at the
1073 line break, and inserting @samp{//} at the start of the next line.
1075 @vindex c-comment-continuation-stars
1076 @vindex comment-continuation-stars (c-)
1077 @vindex comment-line-break-function
1078 When auto-filling block oriented comments, the behavior is dependent on
1079 the value of the variable @code{c-comment-continuation-stars}. When
1080 this variable is @code{nil}, the old behavior for auto-filling C
1081 comments is in effect. In this case, the line is broken by closing the
1082 comment and starting a new comment on the next line.
1084 If you set @code{c-comment-continuation-stars} to a string, then a long
1085 C block comment line is broken by inserting a newline at the line break
1086 position, and inserting this string at the beginning of the next comment
1087 line. The default value for @code{c-comment-continuation-stars} is
1088 @samp{* } (a star followed by a single space)@footnote{To get block
1089 comment continuation lines indented under the block comment starter
1090 (e.g. the @samp{/*}), it is not enough to set
1091 @code{c-comment-continuation-stars} to the empty string. You need to do
1092 this, but you also need to set the offset for the @code{c} syntactic
1093 symbol to be zero.}.
1096 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1097 @node Commands, Customizing Indentation, Minor Modes, Top
1098 @comment node-name, next, previous,up
1102 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1105 * Indentation Commands::
1109 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1110 @node Indentation Commands, Other Commands, , Commands
1111 @comment node-name, next, previous,up
1113 @section Indentation Commands
1114 @cindex Indentation Commands
1115 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1117 Various commands are provided which allow you to conveniently re-indent
1118 C constructs. There are several things to
1119 note about these indentation commands. First, when you
1120 change your programming style, either interactively or through some
1121 other means, your file does @emph{not} automatically get re-indented.
1122 When you change style parameters, you will typically need to reformat
1123 the line, expression, or buffer to see the effects of your changes.
1125 @cindex c-hanging- functions
1126 @findex c-hanging-braces-alist
1127 @findex hanging-braces-alist (c-)
1128 Second, changing some variables have no effect on existing code, even
1129 when you do re-indent. For example, the @code{c-hanging-*} variables
1130 and @code{c-cleanup-list} only affect new code as it is typed in
1131 on-the-fly, so changing @code{c-hanging-braces-alist} and re-indenting
1132 the buffer will not adjust placement of braces already in the file.
1134 @vindex c-progress-interval
1135 @vindex progress-interval (c-)
1136 Third, re-indenting large portions of code is currently rather
1137 inefficient. Improvements have been made since previous releases of
1138 @ccmode{}, and much more radical improvements are planned, but for now
1139 you need to be aware of this @footnote{In particular, I have had people
1140 complain about the speed with which @code{lex(1)} output is re-indented.
1141 Lex, yacc, and other code generators usually output some pretty
1142 perversely formatted code. @emph{Don't} try to indent this stuff!}.
1143 Some provision has been made to at least inform you as to the progress
1144 of the re-indentation. The variable @code{c-progress-interval} controls
1145 how often a progress message is displayed. Set this variable to
1146 @code{nil} to inhibit progress messages, including messages normally
1147 printed when indentation is started and completed.
1149 Also, except as noted below, re-indentation is always driven by the
1150 same mechanisms that control on-the-fly indentation of code. @xref{New
1151 Indentation Engine}, for details.
1153 @findex c-indent-command
1154 @findex indent-command (c-)
1155 @vindex c-tab-always-indent
1156 @vindex tab-always-indent (c-)
1159 @vindex indent-tabs-mode
1160 @vindex c-insert-tab-function
1161 @vindex insert-tab-function (c-)
1162 @findex tab-to-tab-stop
1163 To indent a single line of code, use @kbd{TAB}
1164 (@code{c-indent-command}). The behavior of this command is controlled
1165 by the variable @code{c-tab-always-indent}. When this variable is
1166 @code{t}, @kbd{TAB} always just indents the current line. When
1167 @code{nil}, the line is indented only if point is at the left margin, or
1168 on or before the first non-whitespace character on the line, otherwise
1169 @emph{something else happens}@footnote{Actually what happens is that the
1170 function stored in @code{c-insert-tab-function} is called.
1171 Normally this just inserts a real tab character, or the equivalent
1172 number of spaces, depending on the setting of the variable
1173 @code{indent-tabs-mode}. If you preferred, you could set
1174 @code{c-insert-tab-function} to @code{tab-to-tab-stop} for example.}.
1175 If the value of @code{c-tab-always-indent} is something other than
1176 @code{t} or @code{nil} (e.g. @code{'other}), then a real tab
1177 character@footnote{The caveat about @code{indent-tabs-mode} in the
1178 previous footnote also applies here.} is inserted only when point is
1179 inside a literal (see @ref{Auto-newline insertion}), otherwise the line
1183 @findex c-indent-exp
1184 @findex indent-exp (c-)
1185 To indent an entire balanced brace or parenthesis expression, use
1186 @kbd{M-C-q} (@code{c-indent-exp}). Note that point should be on
1187 the opening brace or parenthesis of the expression you want to indent.
1190 @findex c-indent-defun
1191 @findex indent-defun (c-)
1192 Another very convenient keystroke is @kbd{C-c C-q}
1193 (@code{c-indent-defun}) when re-indents the entire top-level function or
1194 class definition that encompasses point. It leaves point at the
1195 same position within the buffer.
1198 @findex indent-region
1199 To indent any arbitrary region of code, use @kbd{M-C-\}
1200 (@code{indent-region}). This is a standard Emacs command, specially
1201 tailored for C code in a @ccmode{} buffer. Note that of course,
1202 point and mark must delineate the region you
1206 @findex c-mark-function
1207 @findex mark-function (c-)
1208 While not strictly an indentation function, @kbd{M-C-h}
1209 (@code{c-mark-function}) is useful for marking the current top-level
1210 function or class definition as the current region.
1212 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1213 @node Other Commands, , Indentation Commands, Commands
1214 @comment node-name, next, previous,up
1216 @section Other Commands
1217 @cindex Other Commands
1218 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1220 @ccmode{} contains other useful command for moving around in C
1224 @findex c-beginning-of-defun
1225 @findex beginning-of-defun (c-)
1226 @findex beginning-of-defun
1227 @item M-x c-beginning-of-defun
1228 Moves point back to the least-enclosing brace. This function is
1229 analogous to the Emacs built-in command @code{beginning-of-defun},
1230 except it eliminates the constraint that the top-level opening brace
1231 must be in column zero. See @code{beginning-of-defun} for more
1234 Depending on the coding style being used, you might prefer
1235 @code{c-beginning-of-defun} to @code{beginning-of-defun}. If so,
1236 consider binding @kbd{C-M-a} to the former instead. For backwards
1237 compatibility reasons, the default binding remains in effect.
1239 @findex c-end-of-defun
1240 @findex end-of-defun (c-)
1241 @findex end-of-defun
1242 @item M-x c-end-of-defun
1243 Moves point to the end of the current top-level definition. This
1244 function is analogous to the Emacs built-in command @code{end-of-defun},
1245 except it eliminates the constraint that the top-level opening brace of
1246 the defun must be in column zero. See @code{beginning-of-defun} for more
1249 Depending on the coding style being used, you might prefer
1250 @code{c-end-of-defun} to @code{end-of-defun}. If so,
1251 consider binding @kbd{C-M-e} to the former instead. For backwards
1252 compatibility reasons, the default binding remains in effect.
1255 @findex c-up-conditional
1256 @findex up-conditional (c-)
1257 @item C-c C-u (c-up-conditional)
1258 Move point back to the containing preprocessor conditional, leaving the
1259 mark behind. A prefix argument acts as a repeat count. With a negative
1260 argument, move point forward to the end of the containing
1261 preprocessor conditional. When going backwards, @code{#elif} is treated
1262 like @code{#else} followed by @code{#if}. When going forwards,
1263 @code{#elif} is ignored.@refill
1266 @findex c-backward-conditional
1267 @findex backward-conditional (c-)
1268 @item C-c C-p (c-backward-conditional)
1269 Move point back over a preprocessor conditional, leaving the mark
1270 behind. A prefix argument acts as a repeat count. With a negative
1271 argument, move forward.
1274 @findex c-forward-conditional
1275 @findex forward-conditional (c-)
1276 @item C-c C-n (c-forward-conditional)
1277 Move point forward across a preprocessor conditional, leaving the mark
1278 behind. A prefix argument acts as a repeat count. With a negative
1279 argument, move backward.
1282 @findex c-beginning-of-statement
1283 @findex beginning-of-statement (c-)
1284 @item M-a (c-beginning-of-statement)
1285 Move point to the beginning of the innermost C statement. If point is
1286 already at the beginning of a statement, it moves to the beginning of
1287 the closest preceding statement, even if that means moving into a block
1288 (you can use @kbd{M-C-b} to move over a balanced block). With prefix
1289 argument @var{n}, move back @var{n} @minus{} 1 statements.
1291 If point is within a comment, or next to a comment, this command moves
1292 by sentences instead of statements.
1294 When called from a program, this function takes three optional
1295 arguments: the numeric prefix argument, a buffer position limit (used as
1296 a starting point for syntactic parsing and as a limit for backward
1297 movement), and a flag to indicate whether movement should be by
1298 statements (if @code{nil}) or sentence (if non-@code{nil}).
1301 @findex c-end-of-statement
1302 @findex end-of-statement (c-)
1303 @item M-e (c-end-of-statement)
1304 Move point to the end of the innermost C statement. If point is at the
1305 end of a statement, move to the end of the next statement, even if it's
1306 inside a nested block (use @kbd{M-C-f} to move to the other side of the
1307 block). With prefix argument @var{n}, move forward @var{n} @minus{} 1
1310 If point is within a comment, or next to a comment, this command moves
1311 by sentences instead of statements.
1313 When called from a program, this function takes three optional
1314 arguments: the numeric prefix argument, a buffer position limit (used as
1315 a starting point for syntactic parsing and as a limit for backward
1316 movement), and a flag to indicate whether movement should be by
1317 statements (if @code{nil}) or sentence (if non-@code{nil}).
1319 @findex c-forward-into-nomenclature
1320 @findex forward-into-nomenclature (c-)
1321 @item M-x c-forward-into-nomenclature
1322 A popular programming style, especially for object-oriented languages
1323 such as C++ is to write symbols in a mixed case format, where the first
1324 letter of each word is capitalized, and not separated by underscores.
1325 E.g. @samp{SymbolsWithMixedCaseAndNoUnderlines}.
1327 This command moves point forward to next capitalized word. With prefix
1328 argument @var{n}, move @var{n} times.
1330 @findex c-backward-into-nomenclature
1331 @findex backward-into-nomenclature (c-)
1332 @item M-x c-backward-into-nomenclature
1333 Move point backward to beginning of the next capitalized
1334 word. With prefix argument @var{n}, move @var{n} times. If
1335 @var{n} is negative, move forward.
1338 @findex c-scope-operator
1339 @findex scope-operator (c-)
1340 @item C-c : (c-scope-operator)
1341 In C++, it is also sometimes desirable to insert the double-colon scope
1342 operator without performing the electric behavior of colon insertion.
1343 @kbd{C-c :} does just this.
1346 @findex fill-paragraph
1347 @vindex c-hanging-comment-starter-p
1348 @vindex c-hanging-comment-ender-p
1349 @vindex hanging-comment-starter-p (c-)
1350 @vindex hanging-comment-ender-p (c-)
1351 @item M-q (fill-paragraph)
1352 The command is used to fill a block style (C) or line style (C++)
1353 comment, in much the same way that text in the various text modes can be
1354 filled@footnote{You should not use specialized filling packages such as
1355 @code{filladapt} with CC Mode. They don't work as well for filling as
1356 @code{c-fill-paragraph}}. You should never attempt to fill non-comment
1357 code sections; you'll end up with garbage! Two variables control how C
1358 style block comments are filled, specifically how the comment start and
1359 end delimiters are handled.
1361 The variable @code{c-hanging-comment-starter-p} controls whether comment
1362 start delimiters which appear on a line by themselves, end up on a line
1363 by themselves after the fill. When the value is @code{nil}, the comment
1364 starter will remain on its own line@footnote{It will not be placed on a
1365 separate line if it is not already on a separate line.}. Otherwise,
1366 text on the next line will be put on the same line as the comment
1367 starter. This is called @dfn{hanging} because the following text hangs
1368 on the line with the comment starter@footnote{This variable is @code{t}
1369 by default, except in @code{java-mode}. Hanging comment starters mess
1370 up Javadoc style comments.}
1372 The variable @code{c-hanging-comment-ender-p} controls the analogous
1373 behavior for the block comment end delimiter. When the value is
1374 @code{nil}, the comment ender will remain on its own line after the
1375 file@footnote{The same caveat as above holds true.}. Otherwise, the
1376 comment end delimiter will be placed at the end of the previous line.
1380 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1381 @node Customizing Indentation, Syntactic Symbols, Commands, Top
1382 @comment node-name, next, previous,up
1384 @chapter Customizing Indentation
1385 @cindex Customizing Indentation
1386 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1388 @vindex c-offsets-alist
1389 @vindex offsets-alist (c-)
1390 @cindex c-set-offset
1391 @cindex set-offset (c-)
1392 The variable @code{c-offsets-alist} contains the mappings between
1393 syntactic symbols and the offsets to apply for those symbols. You
1394 should never modify this variable directly though. Use the function
1395 @code{c-set-offset} instead (see below for details).
1397 The @code{c-offsets-alist} variable is where you customize all your
1398 indentations. You simply need to decide what additional offset you want
1399 to add for every syntactic symbol. You can use the command @kbd{C-c
1400 C-o} (@code{c-set-offset}) as the way to set offsets, both interactively
1401 and from your mode hook. Also, you can set up @emph{styles} of
1402 indentatio. Most likely, you'll
1403 find one of the pre-defined styles will suit your needs, but if not,
1404 this section will describe how to set up basic editing configurations.
1405 @xref{Styles}, for an explanation of how to set up named styles.
1407 @cindex c-basic-offset
1408 @cindex basic-offset (c-)
1409 As mentioned previously, the variable @code{c-offsets-alist} is an
1410 association list of syntactic symbols and the offsets to be applied for
1411 those symbols. In fact, these offset values can be any of an integer, a
1412 function or lambda expression, a variable name, or one of the following
1413 symbols: @code{+}, @code{-}, @code{++}, @code{--}, @code{*}, or
1414 @code{/}. These symbols describe offset in multiples of the value of
1415 the variable @code{c-basic-offset}. By defining a style's indentation
1416 in terms of this fundamental variable, you can change the amount of
1417 whitespace given to an indentation level while leaving the same
1418 relationship between levels. Here are the values that the special
1419 symbols correspond to:
1424 @code{c-basic-offset} times 1
1426 @code{c-basic-offset} times -1
1428 @code{c-basic-offset} times 2
1430 @code{c-basic-offset} times -2
1432 @code{c-basic-offset} times 0.5
1434 @code{c-basic-offset} times -0.5
1438 @vindex c-style-variables-are-local-p
1439 @vindex style-variables-are-local-p (c-)
1441 So, for example, because most of the default offsets are defined in
1442 terms of @code{+}, @code{-}, and @code{0}, if you like the general
1443 indentation style, but you use 4 spaces instead of 2 spaces per level,
1444 you can probably achieve your style just by changing
1445 @code{c-basic-offset} like so (in your @file{.emacs} file):
1448 (setq c-basic-offset 4)
1457 int add( int val, int incr, int doit )
1461 return( val + incr );
1473 int add( int val, int incr, int doit )
1477 return( val + incr );
1486 To change indentation styles more radically, you will want to change the
1487 value associated with the syntactic symbols in the
1488 @code{c-offsets-alist} variable. First, I'll show you how to do that
1489 interactively, then I'll describe how to make changes to your
1490 @file{.emacs} file so that your changes are more permanent.
1493 * Interactive Customization::
1494 * Permanent Customization::
1496 * Advanced Customizations::
1499 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1500 @node Interactive Customization, Permanent Customization, , Customizing Indentation
1501 @comment node-name, next, previous,up
1503 @section Interactive Customization
1504 @cindex Interactive Customization
1505 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1507 As an example of how to customize indentation, let's change the
1508 style of this example@footnote{In this an subsequent examples, the
1509 original code is formatted using the @samp{gnu} style unless otherwise
1510 indicated. @xref{Styles}.}:
1514 1: int add( int val, int incr, int doit )
1518 5: return( val + incr );
1530 1: int add( int val, int incr, int doit )
1534 5: return( val + incr );
1542 In other words, we want to change the indentation of braces that open a
1543 block following a condition so that the braces line up under the
1544 conditional, instead of being indented. Notice that the construct we
1545 want to change starts on line 4. To change the indentation of a line,
1546 we need to see which syntactic components affect the offset calculations
1547 for that line. Hitting @kbd{C-c C-s} on line 4 yields:
1550 ((substatement-open . 44))
1554 @findex c-set-offset
1555 @findex set-offset (c-)
1558 so we know that to change the offset of the open brace, we need to
1559 change the indentation for the @code{substatement-open} syntactic
1560 symbol. To do this interactively, just hit @kbd{C-c C-o}
1561 (@code{c-set-offset}). This prompts you for the syntactic symbol to
1562 change, providing a reasonable default. In this case, the default is
1563 @code{substatement-open}, which is just the syntactic symbol we want to
1566 After you hit return, @ccmode{} will then prompt you for the new
1567 offset value, with the old value as the default. The default in this
1568 case is @samp{+}, but we want no extra indentation so enter
1569 @samp{0} and @kbd{RET}. This will associate the offset 0 with the
1570 syntactic symbol @code{substatement-open} in the @code{c-offsets-alist}
1573 @findex c-indent-defun
1574 @findex indent-defun (c-)
1576 To check your changes quickly, just hit @kbd{C-c C-q}
1577 (@code{c-indent-defun}) to reindent the entire function. The example
1578 should now look like:
1582 1: int add( int val, int incr, int doit )
1586 5: return( val + incr );
1594 Notice how just changing the open brace offset on line 4 is all we
1595 needed to do. Since the other affected lines are indented relative to
1596 line 4, they are automatically indented the way you'd expect. For more
1597 complicated examples, this may not always work. The general approach to
1598 take is to always start adjusting offsets for lines higher up in the
1599 file, then re-indent and see if any following lines need further
1602 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1603 @node Permanent Customization, Styles, Interactive Customization, Customizing Indentation
1604 @comment node-name, next, previous,up
1606 @section Permanent Customization
1607 @cindex Permanent Customization
1608 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1610 @vindex c-mode-common-hook
1612 @vindex c++-mode-hook
1613 @vindex objc-mode-hook
1614 @vindex java-mode-hook
1615 @vindex idl-mode-hook
1616 @vindex c-initialization-hook
1617 @vindex initialization-hook (c-)
1619 To make your changes permanent, you need to add some lisp code to your
1620 @file{.emacs} file, but first you need to decide whether your styles
1621 should be global in every buffer, or local to each specific buffer.
1623 If you edit primarily one style of code, you may want to make the
1624 @ccmode{} style variables have global values so that every buffer will
1625 share the style settings. This will allow you to set the @ccmode{}
1626 variables at the top level of your @file{.emacs} file, and is the
1627 way @ccmode{} works by default.
1629 @vindex c-mode-common-hook
1630 @vindex mode-common-hook (c-)
1631 @vindex c-style-variables-are-local-p
1632 @vindex style-variables-are-local-p (c-)
1633 If you edit many different styles of code at
1634 the same time, you might want to make the @ccmode{} style variables
1635 have buffer local values. If you do this, then you will need to set any
1636 @ccmode{} style variables in a hook function (e.g. off of
1637 @code{c-mode-common-hook} instead of at the top level of your
1638 @file{.emacs} file). The recommended way to do this is to set the
1639 variable @code{c-style-variables-are-local-p} to @code{t}
1640 @strong{before} @ccmode{} is loaded into your Emacs session.
1642 @ccmode{} provides several hooks that you can
1643 use to customize the mode according to your coding style. Each language
1644 mode has its own hook, adhering to standard Emacs major mode
1645 conventions. There is also one general hook and one package
1646 initialization hook:
1651 @code{c-mode-hook} --- for C buffers only
1653 @code{c++-mode-hook} --- for C++ buffers only
1655 @code{objc-mode-hook} --- for Objective-C buffers only
1657 @code{java-mode-hook} --- for Java buffers only
1659 @code{idl-mode-hook} --- for IDL buffers only
1661 @code{c-mode-common-hook} --- common across all languages
1663 @code{c-initialization-hook} --- hook run only once per Emacs session,
1664 when @ccmode{} is initialized.
1668 The language hooks get run as the last thing when you enter that
1669 language mode. The @code{c-mode-common-hook} is run by all
1670 supported modes @emph{before} the language specific hook, and thus can
1671 contain customizations that are common across all languages. Most of
1672 the examples in this section will assume you are using the common
1673 hook@footnote{The interaction between @code{java-mode} and the hook
1674 variables is slightly different than for the other modes.
1675 @code{java-mode} sets the style (see @ref{Styles}) of the buffer to
1676 @samp{java} @emph{before} running the @code{c-mode-common-hook} or
1677 @code{java-mode-hook}. You need to be aware of this so that style
1678 settings in @code{c-mode-common-hook} don't clobber your Java style.}.
1680 Here's a simplified example of what you can add to your @file{.emacs}
1681 file to make the changes described in the previous section
1682 (@ref{Interactive Customization}) more permanent. See the Emacs manuals
1683 for more information on customizing Emacs via hooks. @xref{Sample
1684 .emacs File}, for a more complete sample @file{.emacs} file.
1688 (defun my-c-mode-common-hook ()
1689 ;; my customizations for all of c-mode and related modes
1690 (c-set-offset 'substatement-open 0)
1691 ;; other customizations can go here
1693 (add-hook 'c-mode-common-hook 'my-c-mode-common-hook)
1698 For complex customizations, you will probably want to set up a
1699 @emph{style} that groups all your customizations under a single
1702 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1703 @node Styles, Advanced Customizations, Permanent Customization, Customizing Indentation
1704 @comment node-name, next, previous,up
1708 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1710 Most people only need to edit code formatted in just a few well-defined
1711 and consistent styles. For example, their organization might impose a
1712 ``blessed'' style that all its programmers must conform to. Similarly,
1713 people who work on GNU software will have to use the GNU coding style on
1714 C code. Some shops are more lenient, allowing a variety of coding
1715 styles, and as programmers come and go, there could be a number of
1716 styles in use. For this reason, @ccmode{} makes it convenient for
1717 you to set up logical groupings of customizations called @dfn{styles},
1718 associate a single name for any particular style, and pretty easily
1719 start editing new or existing code using these styles.
1728 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1729 @node Built-in Styles, Adding Styles, , Styles
1730 @comment node-name, next, previous,up
1732 @subsection Built-in Styles
1733 @cindex Built-in Styles
1734 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1736 If you're lucky, one of @ccmode{}'s built-in styles might be just
1737 what you're looking for. These include:
1742 @code{gnu} --- coding style blessed by the Free Software Foundation
1743 for C code in GNU programs. This is the default style for all newly
1744 created buffers, but you can change this by setting the variable
1745 @code{c-default-style}.
1749 @code{k&r} --- The classic Kernighan and Ritchie style for C code.
1753 @code{bsd} --- Also known as ``Allman style'' after Eric Allman.
1755 @cindex Whitesmith style
1757 @code{whitesmith} --- Popularized by the examples that came with
1758 Whitesmiths C, an early commercial C compiler.
1760 @cindex Stroustrup style
1762 @code{stroustrup} --- The classic Stroustrup style for C++ code.
1764 @cindex Ellemtel style
1766 @code{ellemtel} --- Popular C++ coding standards as defined by
1767 ``Programming in C++, Rules and Recommendations'', Erik Nyquist and Mats
1768 Henricson, Ellemtel @footnote{This document is ftp'able from
1769 @code{euagate.eua.ericsson.se}}.
1773 @code{linux} --- C coding standard for Linux development.
1775 @cindex Python style
1777 @code{python} --- C coding standard for Python extension
1778 modules@footnote{Python is a high level scripting language with a C/C++
1779 foreign function interface. For more information, see
1780 @code{<http://www.python.org/>}.}.
1785 @code{java} --- The style for editing Java code. Note that this style is
1786 automatically installed when you enter @code{java-mode}.
1790 @vindex c-default-style
1791 @vindex default-style (c-)
1793 @code{user} --- This is a special style for several reasons. First, if
1794 you customize @ccmode{} by using either the new Custom interface or by
1795 doing @code{setq}'s at the top level of your @file{.emacs} file, these
1796 settings will be captured in the @code{user} style. Also, all other
1797 styles implicitly inherit their settings from @code{user} style. This
1798 means that for any styles you add via @code{c-add-style} (@pxref{Adding
1799 Styles}) you need only define the differences between your new style and
1802 Note however that @code{user} style is @emph{not} the default style.
1803 @code{gnu} is the default style for all newly created buffers, but you
1804 can change this by setting variable @code{c-default-style}. Be careful
1805 if you customize @ccmode{} as described above; since your changes will
1806 be captured in the @code{user} style, you will also have to change
1807 @code{c-default-style} to "user" to see the effect of your
1813 @findex set-style (c-)
1815 If you'd like to experiment with these built-in styles you can simply
1816 type the following in a @ccmode{} buffer:
1820 @kbd{C-c . @var{STYLE-NAME} RET}
1825 @kbd{C-c .} runs the command @code{c-set-style}. Note that all style
1826 names are case insensitive, even the ones you define.
1828 Setting a style in this way does @emph{not} automatically re-indent your
1829 file. For commands that you can use to view the effect of your changes,
1832 Once you find a built-in style you like, you can make the change
1833 permanent by adding some lisp to your @file{.emacs} file. Let's say for
1834 example that you want to use the @samp{ellemtel} style in all your
1835 files. You would add this:
1839 (defun my-c-mode-common-hook ()
1840 ;; use Ellemtel style for all C like languages
1841 (c-set-style "ellemtel")
1842 ;; other customizations can go here
1844 (add-hook 'c-mode-common-hook 'my-c-mode-common-hook)
1849 @vindex c-indentation-style
1850 @vindex indentation-style (c-)
1851 Note that for BOCM compatibility, @samp{gnu} is the default
1852 style, and any non-style based customizations you make (i.e. in
1853 @code{c-mode-common-hook} in your
1854 @file{.emacs} file) will be based on @samp{gnu} style unless you do
1855 a @code{c-set-style} as the first thing in your hook. The variable
1856 @code{c-indentation-style} always contains the buffer's current style name,
1860 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1861 @node Adding Styles, File Styles, Built-in Styles, Styles
1862 @comment node-name, next, previous,up
1864 @subsection Adding Styles
1865 @cindex Adding Styles
1866 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1868 @vindex c-style-alist
1869 @vindex style-alist (c-)
1871 @findex add-style (c-)
1872 If none of the built-in styles is appropriate, you'll probably want to
1873 add a new @dfn{style definition}. Styles are kept in the
1874 @code{c-style-alist} variable, but you should never modify this variable
1875 directly. Instead, @ccmode{} provides the function
1876 @code{c-add-style} that you can use to easily add new styles or change
1877 existing styles. This function takes two arguments, a @var{stylename}
1878 string, and an association list @var{description} of style
1879 customizations. If @var{stylename} is not already in
1880 @code{c-style-alist}, the new style is added, otherwise the style is
1881 changed to the new @var{description}.
1882 This function also takes an optional third argument, which if
1883 non-@code{nil}, automatically applies the new style to the current
1886 @comment TBD: The next paragraph is bogus. I really need to better
1887 @comment document adding styles, including setting up inherited styles.
1889 The sample @file{.emacs} file provides a concrete example of how a new
1890 style can be added and automatically set. @xref{Sample .emacs File}.
1892 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1893 @node File Styles, , Adding Styles, Styles
1894 @comment node-name, next, previous,up
1896 @subsection File Styles
1898 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1900 @cindex local variables
1902 The Emacs manual describes how you can customize certain variables on a
1903 per-file basis by including a @dfn{Local Variable} block at the end of
1904 the file. So far, you've only seen a functional interface to @ccmode{}
1905 customization, which is highly inconvenient for use in a Local Variable
1906 block. @ccmode{} provides two variables that make it easier for you to
1907 customize your style on a per-file basis.
1908 It works via the standard Emacs hook variable
1909 @code{hack-local-variables-hook}.
1911 @vindex c-file-style
1912 @vindex file-style (c-)
1913 @vindex c-file-offsets
1914 @vindex file-offsets (c-)
1916 The variable @code{c-file-style} can be set to a style name string.
1917 When the file is visited, @ccmode{} will automatically set the
1918 file's style to this style using @code{c-set-style}.
1920 @vindex c-offsets-alist
1921 @vindex offsets-alist (c-)
1922 @findex c-set-offset
1923 @findex set-offset (c-)
1924 Another variable, @code{c-file-offsets}, takes an association list
1925 similar to what is allowed in @code{c-offsets-alist}. When the file is
1926 visited, @ccmode{} will automatically institute these offets using
1927 @code{c-set-offset}.
1929 Note that file style settings (i.e. @code{c-file-style}) are applied
1930 before file offset settings (i.e. @code{c-file-offsets}). Also, if
1931 either of these are set in a file's local variable section, all the
1932 style variable values are made local to that buffer.
1935 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1936 @node Advanced Customizations, , Styles, Customizing Indentation
1937 @comment node-name, next, previous,up
1939 @section Advanced Customizations
1940 @cindex Advanced Customizations
1941 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1943 @vindex c-style-alist
1944 @vindex style-alist (c-)
1945 @vindex c-basic-offset
1946 @vindex basic-offset (c-)
1947 For most users, @ccmode{} will support their coding styles with
1948 very little need for more advanced customizations. Usually, one of the
1949 standard styles defined in @code{c-style-alist} will do the trick. At
1950 most, perhaps one of the syntactic symbol offsets will need to be
1951 tweaked slightly, or maybe @code{c-basic-offset} will need to be
1952 changed. However, some styles require a more flexible framework for
1953 customization, and one of the real strengths of @ccmode{} is that
1954 the syntactic analysis model provides just such a framework. This allows
1955 you to implement custom indentation calculations for situations not
1956 handled by the mode directly.
1958 @vindex c-style-variables-are-local-p
1959 @vindex style-variables-are-local-p
1960 Note that the style controlling variables can either have global values,
1961 or can be buffer local (e.g. different in every buffer). If all the C
1962 files you edit tend to have the same style, you might want to keep the
1963 variables global. If you tend to edit files with many different styles,
1964 you will have to make the variables buffer local. The variable
1965 @code{c-style-variables-are-local-p} controls this.
1967 When @code{c-style-variables-are-local-p} is non-nil, then the style
1968 variables will have a different settable value for each buffer,
1969 otherwise all buffers will share the same values. By default, its value
1970 is @code{nil} (i.e. global values). You @strong{must} set this variable
1971 before @ccmode{} is loaded into your Emacs session, and once the
1972 variables are made buffer local, they cannot be made global again
1973 (unless you restart Emacs of course!)
1976 * Custom Indentation Functions::
1977 * Custom Brace and Colon Hanging::
1978 * Customizing Semi-colons and Commas::
1979 * Other Special Indentations::
1982 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1983 @node Custom Indentation Functions, Custom Brace and Colon Hanging, , Advanced Customizations
1984 @comment node-name, next, previous,up
1986 @subsection Custom Indentation Functions
1987 @cindex Custom Indentation Functions
1988 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1990 @cindex Custom Indentation Functions
1991 The most flexible way to customize @ccmode{} is by writing @dfn{custom
1992 indentation functions} and associating them with specific syntactic
1993 symbols (see @ref{Syntactic Symbols}). @ccmode{} itself uses custom
1994 indentation functions to provide more sophisticated indentation, for
1995 example when lining up C++ stream operator blocks:
1999 1: void main(int argc, char**)
2001 3: cout << "There were "
2003 5: << "arguments passed to the program"
2010 In this example, lines 4 through 6 are assigned the @code{stream-op}
2011 syntactic symbol. Here, @code{stream-op} has an offset of @code{+}, and
2012 with a @code{c-basic-offset} of 2, you can see that lines 4 through 6
2013 are simply indented two spaces to the right of line 3. But perhaps we'd
2014 like @ccmode{} to be a little more intelligent so that it aligns
2015 all the @samp{<<} symbols in lines 3 through 6. To do this, we have
2016 to write a custom indentation function which finds the column of first
2017 stream operator on the first line of the statement. Here is sample
2018 lisp code implementing this:
2022 (defun c-lineup-streamop (langelem)
2023 ;; lineup stream operators
2025 (let* ((relpos (cdr langelem))
2026 (curcol (progn (goto-char relpos)
2028 (re-search-forward "<<\\|>>" (c-point 'eol) 'move)
2029 (goto-char (match-beginning 0))
2030 (- (current-column) curcol))))
2035 Custom indent functions take a single argument, which is a syntactic
2036 component cons cell (see @ref{Syntactic Analysis}). The
2037 function returns an integer offset value that will be added to the
2038 running total indentation for the line. Note that what actually gets
2039 returned is the difference between the column that the first stream
2040 operator is on, and the column of the buffer relative position passed in
2041 the function's argument. Remember that @ccmode{} automatically
2042 adds in the column of the component's relative buffer position and we
2043 don't the column offset added in twice.
2045 @cindex stream-op syntactic symbol
2046 @findex c-lineup-streamop
2047 @findex lineup-streamop (c-)
2048 Now, to associate the function @code{c-lineup-streamop} with the
2049 @code{stream-op} syntactic symbol, we can add something like the
2050 following to our @code{c++-mode-hook}@footnote{It probably makes more
2051 sense to add this to @code{c++-mode-hook} than @code{c-mode-common-hook}
2052 since stream operators are only relevent for C++.}:
2055 (c-set-offset 'stream-op 'c-lineup-streamop)
2060 Now the function looks like this after re-indenting (using @kbd{C-c
2065 1: void main(int argc, char**)
2067 3: cout << "There were "
2069 5: << "arguments passed to the program"
2076 @vindex c-offsets-alist
2077 @vindex offsets-alist (c-)
2078 Custom indentation functions can be as simple or as complex as you like,
2079 and any syntactic symbol that appears in @code{c-offsets-alist} can have
2080 a custom indentation function associated with it. @ccmode{} comes
2081 with several standard custom indentation functions, not all of which are
2082 used by the default styles.
2085 @findex c-lineup-arglist
2086 @findex lineup-arglist (c-)
2088 @code{c-lineup-arglist} --- lines up function argument lines under the
2089 argument on the previous line.
2091 @findex c-lineup-arglist-intro-after-paren
2092 @findex lineup-arglist-intro-after-paren (c-)
2094 @code{c-lineup-arglist-intro-after-paren} --- similar to
2095 @code{c-lineup-arglist}, but works for argument lists that begin with an
2096 open parenthesis followed by a newline.
2098 @findex c-lineup-arglist-close-under-paren
2099 @findex lineup-arglist-close-under-paren (c-)
2101 @code{c-lineup-arglist-close-under-paren} --- set your
2102 @code{arglist-close} syntactic symbol to this line-up function so that
2103 parentheses that close argument lists will line up under the parenthesis
2104 that opened the argument list.
2106 @findex c-lineup-close-paren
2107 @findex lineup-close-paren (c-)
2109 @code{c-lineup-close-paren} --- lines up the closing parenthesis under
2110 its corresponding open parenthesis if that one is followed by code.
2111 Otherwise, if the open parenthesis ends its line, no indentation is
2112 added. Works with any @code{@dots{}-close} symbol.
2114 @findex c-lineup-streamop
2115 @findex lineup-streamop (c-)
2117 @code{c-lineup-streamop} --- lines up C++ stream operators
2118 (e.g. @samp{<<} and @samp{>>}).
2120 @findex c-lineup-multi-inher
2121 @findex lineup-multi-inher (c-)
2123 @code{c-lineup-multi-inher} --- lines up multiple inheritance lines.
2125 @findex c-indent-one-line-block
2126 @findex indent-one-line-block (c-)
2128 @code{c-indent-one-line-block} --- adds @code{c-basic-offset} to the
2129 indentation if the line is a one line block, otherwise 0. Intended to
2130 be used with any opening brace symbol, e.g. @code{substatement-open}.
2132 @findex c-lineup-C-comments
2133 @findex lineup-C-comments (c-)
2135 @code{c-lineup-C-comments} --- lines up C block comment continuation
2138 @findex c-lineup-comment
2139 @findex lineup-comment (c-)
2140 @vindex c-comment-only-line-offset
2141 @vindex comment-only-line-offset (c-)
2143 @code{c-lineup-comment} --- lines up comment only lines according to
2144 the variable @code{c-comment-only-line-offset}.
2146 @findex c-lineup-runin-statements
2147 @findex lineup-runin-statements (c-)
2149 @code{c-lineup-runin-statements} --- lines up @code{statement}s for coding
2150 standards which place the first statement in a block on the same line as
2151 the block opening brace@footnote{Run-in style doesn't really work too
2152 well. You might need to write your own custom indentation functions to
2153 better support this style.}.
2155 @findex c-lineup-math
2156 @findex lineup-math (c-)
2158 @code{c-lineup-math} --- lines up math @code{statement-cont} lines under
2159 the previous line after the equals sign.
2161 @findex c-lineup-ObjC-method-call
2162 @findex lineup-ObjC-method-call (c-)
2164 @code{c-lineup-ObjC-method-call} --- for Objective-C code, lines up
2165 selector arguments just after the message receiver.
2167 @findex c-lineup-ObjC-method-args
2168 @findex lineup-ObjC-method-args (c-)
2170 @code{c-lineup-ObjC-method-args} --- for Objective-C code, lines up the
2171 colons that separate arguments by aligning colons vertically.
2173 @findex c-lineup-ObjC-method-args-2
2174 @findex lineup-ObjC-method-args-2 (c-)
2176 @code{c-lineup-ObjC-method-args-2} --- similar to
2177 @code{c-lineup-ObjC-method-args} but lines up the colon on the current
2178 line with the colon on the previous line.
2180 @findex c-lineup-dont-change
2181 @findex lineup-dont-change (c-)
2183 @code{c-lineup-dont-change} --- this lineup function returns the
2184 indentation of the current line. Think of it as an identity function
2185 for lineups; it is used for @code{cpp-macro-cont} lines.
2189 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2190 @node Custom Brace and Colon Hanging, Customizing Semi-colons and Commas, Custom Indentation Functions, Advanced Customizations
2191 @comment node-name, next, previous,up
2193 @subsection Custom Brace and Colon Hanging
2194 @cindex Custom Brace and Colon Hanging
2195 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2197 @vindex c-hanging-braces-alist
2198 @vindex hanging-braces-alist (c-)
2199 Syntactic symbols aren't the only place where you can customize
2200 @ccmode{} with the lisp equivalent of callback functions. Brace
2201 ``hanginess'' can also be determined by custom functions associated with
2202 syntactic symbols on the @code{c-hanging-braces-alist} variable.
2203 Remember that @var{ACTION}'s are typically a list containing some
2204 combination of the symbols @code{before} and @code{after} (see
2205 @ref{Hanging Braces}). However, an @var{ACTION} can also be a function
2206 which gets called when a brace matching that syntactic symbol is
2209 @cindex customizing brace hanging
2210 These @var{ACTION} functions are called with two arguments: the
2211 syntactic symbol for the brace, and the buffer position at which the
2212 brace was inserted. The @var{ACTION} function is expected to return a
2213 list containing some combination of @code{before} and @code{after}. The
2214 function can also return @code{nil}. This return value has the normal
2215 brace hanging semantics.
2217 As an example, @ccmode{} itself uses this feature to dynamically
2218 determine the hanginess of braces which close ``do-while''
2223 void do_list( int count, char** atleast_one_string )
2227 handle_string( atleast_one_string[i] );
2229 @} while( i < count );
2235 @findex c-snug-do-while
2236 @findex snug-do-while (c-)
2237 @ccmode{} assigns the @code{block-close} syntactic symbol to the
2238 brace that closes the @code{do} construct, and normally we'd like the
2239 line that follows a @code{block-close} brace to begin on a separate
2240 line. However, with ``do-while'' constructs, we want the
2241 @code{while} clause to follow the closing brace. To do this, we
2242 associate the @code{block-close} symbol with the @var{ACTION} function
2243 @code{c-snug-do-while}:
2246 (defun c-snug-do-while (syntax pos)
2247 "Dynamically calculate brace hanginess for do-while statements.
2248 Using this function, `while' clauses that end a `do-while' block will
2249 remain on the same line as the brace that closes that block.
2251 See `c-hanging-braces-alist' for how to utilize this function as an
2252 ACTION associated with `block-close' syntax."
2255 (if (and (eq syntax 'block-close)
2256 (setq langelem (assq 'block-close c-syntactic-context))
2257 (progn (goto-char (cdr langelem))
2258 (if (= (following-char) ?@{)
2260 (looking-at "\\<do\\>[^_]")))
2266 This function simply looks to see if the brace closes a ``do-while''
2267 clause and if so, returns the list @samp{(before)} indicating
2268 that a newline should be inserted before the brace, but not after it.
2269 In all other cases, it returns the list @samp{(before after)} so
2270 that the brace appears on a line by itself.
2272 @vindex c-syntactic-context
2273 @vindex syntactic-context (c-)
2274 During the call to the brace hanging @var{ACTION} function, the variable
2275 @code{c-syntactic-context} is bound to the full syntactic analysis list.
2277 @cindex customizing colon hanging
2278 @vindex c-hanging-colon-alist
2279 @vindex hanging-colon-alist (c-)
2280 Note that for symmetry, colon hanginess should be customizable by
2281 allowing function symbols as @var{ACTION}s on the
2282 @code{c-hanging-colon-alist} variable. Since no use has actually been
2283 found for this feature, it isn't currently implemented!
2285 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2286 @node Customizing Semi-colons and Commas, Other Special Indentations, Custom Brace and Colon Hanging, Advanced Customizations
2287 @comment node-name, next, previous,up
2289 @subsection Customizing Semi-colons and Commas
2290 @cindex Customizing Semi-colons and Commas
2291 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2293 @cindex Customizing Semi-colons and Commas
2294 @vindex c-hanging-semi&comma-criteria
2295 @vindex hanging-semi&comma-criteria (c-)
2296 You can also customize the insertion of newlines after semi-colons and
2297 commas, when the auto-newline minor mode is enabled (see @ref{Minor
2298 Modes}). This is controlled by the variable
2299 @code{c-hanging-semi&comma-criteria}, which contains a list of functions
2300 that are called in the order they appear. Each function is called with
2301 zero arguments, and is expected to return one of the following values:
2305 non-@code{nil} --- A newline is inserted, and no more functions from the
2309 @code{stop} --- No more functions from the list are called, but no
2310 newline is inserted.
2313 @code{nil} --- No determination is made, and the next function in the
2318 If every function in the list is called without a determination being
2319 made, then no newline is added. The default value for this variable is a
2320 list containing a single function which inserts newlines only after
2321 semi-colons which do not appear inside parenthesis lists (i.e. those
2322 that separate @code{for}-clause statements).
2324 @findex c-semi&comma-no-newlines-before-nonblanks
2325 @findex semi&comma-no-newlines-before-nonblanks (c-)
2326 Here's an example of a criteria function, provided by @ccmode{}, that
2327 will prevent newlines from being inserted after semicolons when there is
2328 a non-blank following line. Otherwise, it makes no determination. To
2329 use, add this to the front of the @code{c-hanging-semi&comma-criteria}
2335 (defun c-semi&comma-no-newlines-before-nonblanks ()
2337 (if (and (eq last-command-char ?\;)
2338 (zerop (forward-line 1))
2339 (not (looking-at "^[ \t]*$")))
2346 @findex c-semi&comma-inside-parenlist
2347 @findex c-semi&comma-no-newlines-for-oneline-inliners
2348 @findex semi&comma-inside-parenlist (c-)
2349 @findex semi&comma-no-newlines-for-oneline-inliners (c-)
2350 The default value of @code{c-hanging-semi&comma-criteria} is a list
2351 containing just the function @code{c-semi&comma-inside-parenlist}, which
2352 suppresses newlines after semicolons inside parenthesis lists
2353 (e.g. @code{for}-loops). In addition to
2354 @code{c-semi&comma-no-newlines-before-nonblanks} described above,
2355 @ccmode{} also comes with the criteria function
2356 @code{c-semi&comma-no-newlines-for-oneline-inliners}, which suppresses
2357 newlines after semicolons inside one-line inline method definitions
2358 (i.e. in C++ or Java).
2360 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2361 @node Other Special Indentations, , Customizing Semi-colons and Commas, Advanced Customizations
2362 @comment node-name, next, previous,up
2364 @subsection Other Special Indentations
2365 @cindex Customizing Semi-colons and Commas
2366 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2368 @vindex c-label-minimum-indentation
2369 @vindex label-minimum-indentation (c-)
2370 In @samp{gnu} style (see @ref{Built-in Styles}), a minimum indentation
2371 is imposed on lines inside top-level constructs. This minimum
2372 indentation is controlled by the variable
2373 @code{c-label-minimum-indentation}. The default value for this variable
2376 @vindex c-special-indent-hook
2377 @vindex special-indent-hook (c-)
2378 One other customization variable is available in @ccmode{}:
2379 @code{c-special-indent-hook}. This is a standard hook variable that is
2380 called after every line is indented by @ccmode{}. You can use it
2381 to do any special indentation or line adjustments your style dictates,
2382 such as adding extra indentation to constructors or destructor
2383 declarations in a class definition, etc. Note however, that you should
2384 not change point or mark inside your @code{c-special-indent-hook}
2385 functions (i.e. you'll probably want to wrap your function in a
2386 @code{save-excursion}).
2388 Setting @code{c-special-indent-hook} in your style definition is handled
2389 slightly differently than other variables. In your style definition,
2390 you should set the value for
2391 @code{c-special-indent-hook} to a function or list of functions, which
2392 will be appended to @code{c-special-indent-hook} using @code{add-hook}.
2393 That way, the current setting for the buffer local value of
2394 @code{c-special-indent-hook} won't be overridden.
2397 @findex indent-for-comment
2398 @vindex c-indent-comments-syntactically-p
2399 @vindex indent-comments-syntactically-p (c-)
2400 @vindex comment-column
2402 Normally, the standard Emacs command @kbd{M-;}
2403 (@code{indent-for-comment}) will indent comment only lines to
2404 @code{comment-column}. Some users however, prefer that @kbd{M-;} act
2405 just like @kbd{TAB} for purposes of indenting comment-only lines;
2406 i.e. they want the comments to always indent as they would for normal
2407 code, regardless of whether @kbd{TAB} or @kbd{M-;} were used. This
2408 behavior is controlled by the variable
2409 @code{c-indent-comments-syntactically-p}. When @code{nil} (the
2410 default), @kbd{M-;} indents comment-only lines to @code{comment-column},
2411 otherwise, they are indented just as they would be if @kbd{TAB} were
2414 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2415 @node Syntactic Symbols, Performance Issues, Customizing Indentation, Top
2416 @comment node-name, next, previous,up
2418 @chapter Syntactic Symbols
2419 @cindex Syntactic Symbols
2420 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2422 @vindex c-offsets-alist
2423 @vindex offsets-alist (c-)
2425 Here is a complete list of the recognized syntactic symbols as described
2426 in the @code{c-offsets-alist} variable, along with a brief description.
2427 More detailed descriptions follow below.
2431 @code{string} --- inside multi-line string
2433 @code{c} --- inside a multi-line C style block comment
2435 @code{defun-open} --- brace that opens a function definition
2437 @code{defun-close} --- brace that closes a function definition
2439 @code{defun-block-intro} --- the first line in a top-level defun
2441 @code{class-open} --- brace that opens a class definition
2443 @code{class-close} --- brace that closes a class definition
2445 @code{inline-open} --- brace that opens an in-class inline method
2447 @code{inline-close} --- brace that closes an in-class inline method
2449 @code{func-decl-cont} --- the region between a function definition's
2450 argument list and the function opening brace (excluding K&R argument
2451 declarations). In C, you cannot put anything but whitespace and comments
2452 between them; in C++ and Java, @code{throws} declarations and other
2453 things can appear in this context.
2455 @code{knr-argdecl-intro} --- first line of a K&R C argument declaration
2457 @code{knr-argdecl} --- subsequent lines in a K&R C argument declaration
2459 @code{topmost-intro} --- the first line in a topmost definition
2461 @code{topmost-intro-cont} --- topmost definition continuation lines
2463 @code{member-init-intro} --- first line in a member initialization list
2465 @code{member-init-cont} --- subsequent member initialization list lines
2467 @code{inher-intro} --- first line of a multiple inheritance list
2469 @code{inher-cont} --- subsequent multiple inheritance lines
2471 @code{block-open} --- statement block open brace
2473 @code{block-close} --- statement block close brace
2475 @code{brace-list-open} --- open brace of an enum or static array list
2477 @code{brace-list-close} --- close brace of an enum or static array list
2479 @code{brace-list-intro} --- first line in an enum or static array list
2481 @code{brace-list-entry} --- subsequent lines in an enum or static array list
2483 @code{statement} --- a C statement
2485 @code{statement-cont} --- a continuation of a C statement
2487 @code{statement-block-intro} --- the first line in a new statement block
2489 @code{statement-case-intro} --- the first line in a case `block'
2491 @code{statement-case-open} --- the first line in a case block starting
2494 @code{substatement} --- the first line after a conditional
2496 @code{substatement-open} --- the brace that opens a substatement block
2498 @code{case-label} --- a case or default label
2500 @code{access-label} --- C++ access control label
2502 @code{label} --- any non-special C label
2504 @code{do-while-closure} --- the `while' that ends a
2505 @code{do}-@code{while} construct
2507 @code{else-clause} --- the `else' of an @code{if}-@code{else} construct
2509 @code{comment-intro} --- a line containing only a comment introduction
2511 @code{arglist-intro} --- the first line in an argument list
2513 @code{arglist-cont} --- subsequent argument list lines when no arguments
2514 follow on the same line as the the arglist opening paren
2516 @code{arglist-cont-nonempty} --- subsequent argument list lines when at
2517 least one argument follows on the same line as the arglist opening paren
2519 @code{arglist-close} --- the solo close paren of an argument list
2521 @code{stream-op} --- lines continuing a stream operator
2523 @code{inclass} --- the line is nested inside a class definition
2525 @code{cpp-macro} --- the start of a C preprocessor macro definition
2527 @code{cpp-macro-cont} --- subsequent lines of a multi-line C
2528 preprocessor macro definition
2530 @code{friend} --- a C++ friend declaration
2532 @code{objc-method-intro} --- the first line of an Objective-C method definition
2534 @code{objc-method-args-cont} --- lines continuing an Objective-C method
2537 @code{objc-method-call-cont} --- lines continuing an Objective-C method call
2539 @code{extern-lang-open} --- brace that opens an external language block
2541 @code{extern-lang-close} --- brace that closes an external language block
2543 @code{inextern-lang} --- analogous to `inclass' syntactic symbol, but
2544 used inside external language blocks (e.g. @code{extern "C" @{}).
2546 @code{namespace-open} --- brace that opens a C++ namespace block.
2548 @code{namespace-close} --- brace that closes a C++ namespace block.
2550 @code{innamespace} --- analogous to `inextern-lang' syntactic symbol,
2551 but used inside C++ namespace blocks.
2553 @code{template-args-cont} --- C++ template argument list continuations
2556 @cindex -open syntactic symbols
2557 @cindex -close syntactic symbols
2558 Most syntactic symbol names follow a general naming convention. When a
2559 line begins with an open or close brace, the syntactic symbol will
2560 contain the suffix @code{-open} or @code{-close} respectively.
2562 @cindex -intro syntactic symbols
2563 @cindex -cont syntactic symbols
2564 @cindex -block-intro syntactic symbols
2565 Usually, a distinction is made between the first line that introduces a
2566 construct and lines that continue a construct, and the syntactic symbols
2567 that represent these lines will contain the suffix @code{-intro} or
2568 @code{-cont} respectively. As a sub-classification of this scheme, a
2569 line which is the first of a particular brace block construct will
2570 contain the suffix @code{-block-intro}.
2573 Let's look at some examples to understand how this works. Remember that
2574 you can check the syntax of any line by using @kbd{C-c C-s}.
2579 2: swap( int& a, int& b )
2591 @cindex topmost-intro syntactic symbol
2592 @cindex topmost-intro-cont syntactic symbol
2593 @cindex defun-open syntactic symbol
2594 @cindex defun-close syntactic symbol
2595 @cindex defun-block-intro syntactic symbol
2596 Line 1 shows a @code{topmost-intro} since it is the first line that
2597 introduces a top-level construct. Line 2 is a continuation of the
2598 top-level construct introduction so it has the syntax
2599 @code{topmost-intro-cont}. Line 3 shows a @code{defun-open} since it is
2600 the brace that opens a top-level function definition. Line 9 is a
2601 @code{defun-close} since it contains the brace that closes the top-level
2602 function definition. Line 4 is a @code{defun-block-intro}, i.e. it is
2603 the first line of a brace-block, enclosed in a
2604 top-level function definition.
2606 @cindex statement syntactic symbol
2607 @cindex statement-cont syntactic symbol
2608 Lines 5, 6, and 7 are all given @code{statement} syntax since there
2609 isn't much special about them. Note however that line 8 is given
2610 @code{statement-cont} syntax since it continues the statement begun
2611 on the previous line.
2613 Here's another example, which illustrates some C++ class syntactic
2620 3: public Amplifiable
2624 7: : eString( new BassString( 0.105 )),
2625 8: aString( new BassString( 0.085 )),
2626 9: dString( new BassString( 0.065 )),
2627 10: gString( new BassString( 0.045 ))
2629 12: eString.tune( 'E' );
2630 13: aString.tune( 'A' );
2631 14: dString.tune( 'D' );
2632 15: gString.tune( 'G' );
2634 17: friend class Luthier;
2640 @cindex class-open syntactic symbol
2641 @cindex class-close syntactic symbol
2642 As in the previous example, line 1 has the @code{topmost-intro} syntax.
2643 Here however, the brace that opens a C++ class definition on line 4 is
2644 assigned the @code{class-open} syntax. Note that in C++, classes,
2645 structs, and unions are essentially equivalent syntactically (and are
2646 very similar semantically), so replacing the @code{class} keyword in the
2647 example above with @code{struct} or @code{union} would still result in a
2648 syntax of @code{class-open} for line 4 @footnote{This is the case even
2649 for C and Objective-C. For consistency, structs in all supported
2650 languages are syntactically equivalent to classes. Note however that
2651 the keyword @code{class} is meaningless in C and Objective-C.}.
2652 Similarly, line 18 is assigned @code{class-close} syntax.
2654 @cindex inher-intro syntactic symbol
2655 @cindex inher-cont syntactic symbol
2656 Line 2 introduces the inheritance list for the class so it is assigned
2657 the @code{inher-intro} syntax, and line 3, which continues the
2658 inheritance list is given @code{inher-cont} syntax.
2660 @cindex access-label syntactic symbol
2661 @cindex inclass syntactic symbol
2662 Hitting @kbd{C-c C-s} on line 5 shows the following analysis:
2667 @code{((inclass . 1) (access-label . 67))}
2673 The primary syntactic symbol for this line is @code{access-label} as
2674 this a label keyword that specifies access protection in C++. However,
2675 because this line is also a top-level construct inside a class
2676 definition, the analysis actually shows two syntactic symbols. The
2677 other syntactic symbol assigned to this line is @code{inclass}.
2678 Similarly, line 6 is given both @code{inclass} and @code{topmost-intro}
2684 @code{((inclass . 58) (topmost-intro . 60))}
2689 @cindex member-init-intro syntactic symbol
2690 @cindex member-init-cont syntactic symbol
2691 Line 7 introduces a C++ member initialization list and as such is given
2692 @code{member-init-intro} syntax. Note that in this case it is
2693 @emph{not} assigned @code{inclass} since this is not considered a
2694 top-level construct. Lines 8 through 10 are all assigned
2695 @code{member-init-cont} since they continue the member initialization
2696 list started on line 7.
2698 @cindex in-class inline methods
2699 @cindex inline-open syntactic symbol
2700 @cindex inline-close syntactic symbol
2701 Line 11's analysis is a bit more complicated:
2706 @code{((inclass . 1) (inline-open))}
2711 This line is assigned a syntax of both @code{inline-open} and
2712 @code{inclass} because it opens an @dfn{in-class} C++ inline method
2713 definition. This is distinct from, but related to, the C++ notion of an
2714 inline function in that its definition occurs inside an enclosing class
2715 definition, which in C++ implies that the function should be inlined.
2716 If though, the definition of the @code{Bass} constructor appeared
2717 outside the class definition, the construct would be given the
2718 @code{defun-open} syntax, even if the keyword @code{inline} appeared
2719 before the method name, as in:
2733 : eString( new BassString( 0.105 )),
2734 aString( new BassString( 0.085 )),
2735 dString( new BassString( 0.065 )),
2736 gString( new BassString( 0.045 ))
2738 eString.tune( 'E' );
2739 aString.tune( 'A' );
2740 dString.tune( 'D' );
2741 gString.tune( 'G' );
2747 @cindex friend syntactic symbol
2748 Returning to the previous example, line 16 is given @code{inline-close}
2749 syntax, while line 12 is given @code{defun-block-open} syntax, and lines
2750 13 through 15 are all given @code{statement} syntax. Line 17 is
2751 interesting in that its syntactic analysis list contains three
2756 @code{((friend) (inclass . 58) (topmost-intro . 380))}
2760 The @code{friend} syntactic symbol is a modifier that typically does not
2761 have a relative buffer position.
2763 Template definitions introduce yet another syntactic symbol:
2768 1: ThingManager <int,
2769 2: Framework::Callback *,
2770 3: Mutex> framework_callbacks;
2775 Here, line 1 is analyzed as a @code{topmost-intro}, but lines 2 and 3
2776 are both analyzed as @code{template-args-cont} lines.
2778 Here is another (totally contrived) example which illustrates how syntax
2779 is assigned to various conditional constructs:
2783 1: void spam( int index )
2785 3: for( int i=0; i<index; i++ )
2789 7: do_something_special();
2792 10: do_something( i );
2795 13: another_thing( i-- );
2805 Only the lines that illustrate new syntactic symbols will be discussed.
2807 @cindex substatement-open syntactic symbol
2808 @cindex substatement-block-intro syntactic symbol
2809 @cindex block-close syntactic symbol
2810 Line 4 has a brace which opens a conditional's substatement block. It
2811 is thus assigned @code{substatement-open} syntax, and since line 5 is
2812 the first line in the substatement block, it is assigned
2813 @code{substatement-block-intro} syntax. Lines 6 and 7 are assigned
2814 similar syntax. Line 8 contains the brace that closes the inner
2815 substatement block. It is given the syntax @code{block-close},
2816 as are lines 11 and 14.
2818 @cindex else-clause syntactic symbol
2819 @cindex substatement syntactic symbol
2820 Line 9 is a little different --- since it contains the keyword
2821 @code{else} matching the @code{if} statement introduced on line 5, it is
2822 given the @code{else-clause} syntax. Note also that line 10 is slightly
2823 different too. Because @code{else} is considered a conditional
2824 introducing keyword @footnote{The list of conditional keywords are (in
2825 C, C++, Objective-C, and Java): @code{for}, @code{if}, @code{do},
2826 @code{else}, @code{while}, and @code{switch}. C++ and Java have two
2827 additional conditional keywords: @code{try} and @code{catch}. Java also
2828 has the @code{finally} and @code{synchronized} keywords.}, and because
2829 the following substatement is not a brace block, line 10 is assigned the
2830 @code{substatement} syntax.
2832 @cindex do-while-closure syntactic symbol
2833 One other difference is seen on line 15. The @code{while} construct
2834 that closes a @code{do} conditional is given the special syntax
2835 @code{do-while-closure} if it appears on a line by itself. Note that if
2836 the @code{while} appeared on the same line as the preceding close brace,
2837 that line would have been assigned @code{block-close} syntax instead.
2839 Switch statements have their own set of syntactic symbols. Here's an
2844 1: void spam( enum Ingredient i )
2851 8: drink_some_water();
2864 @cindex case-label syntactic symbol
2865 @cindex statement-case-intro syntactic symbol
2866 @cindex statement-case-open syntactic symbol
2867 Here, lines 4, 7, and 10 are all assigned @code{case-label} syntax,
2868 while lines 5 and 8 are assigned @code{statement-case-intro}. Line 11
2869 is treated slightly differently since it contains a brace that opens a
2870 block --- it is given @code{statement-case-open} syntax.
2873 There are a set of syntactic symbols that are used to recognize
2874 constructs inside of brace lists. A brace list is defined as an
2875 @code{enum} or aggregate initializer list, such as might statically
2876 initialize an array of structs. For example:
2880 1: static char* ingredients[] =
2890 @cindex brace-list-open syntactic symbol
2891 @cindex brace-list-intro syntactic symbol
2892 @cindex brace-list-close syntactic symbol
2893 @cindex brace-list-entry syntactic symbol
2894 Following convention, line 2 in this example is assigned
2895 @code{brace-list-open} syntax, and line 3 is assigned
2896 @code{brace-list-intro} syntax. Likewise, line 6 is assigned
2897 @code{brace-list-close} syntax. Lines 4 and 5 however, are assigned
2898 @code{brace-list-entry} syntax, as would all subsequent lines in this
2901 External language definition blocks also have their own syntactic
2902 symbols. In this example:
2908 3: int thing_one( int );
2909 4: int thing_two( double );
2915 @cindex extern-lang-open syntactic symbol
2916 @cindex extern-lang-close syntactic symbol
2917 @cindex inextern-lang syntactic symbol
2918 @cindex inclass syntactic symbol
2920 line 2 is given the @code{extern-lang-open} syntax, while line 5 is given
2921 the @code{extern-lang-close} syntax. The analysis for line 3 yields:
2922 @code{((inextern-lang) (topmost-intro . 14))}, where
2923 @code{inextern-lang} is a modifier similar in purpose to @code{inclass}.
2925 Similarly, C++ namespace constructs have their own associated syntactic
2926 symbols. In this example:
2938 @cindex namespace-open syntactic-symbol
2939 @cindex namespace-close syntactic-symbol
2940 @cindex innamespace syntactic-symbol
2942 line 2 is given the @code{namespace-open} syntax, while line 4 is given
2943 the @code{namespace-close} syntax. The analysis for line 3 yields:
2944 @code{((innamespace) (topmost-intro . 17))}, where @code{innamespace} is
2945 a modifier similar in purpose to @code{inextern-lang} and @code{inclass}.
2947 A number of syntactic symbols are associated with parenthesis lists,
2948 a.k.a argument lists, as found in function declarations and function
2949 calls. This example illustrates these:
2953 1: void a_function( int line1,
2956 4: void a_longer_function(
2961 9: void call_them( int line1, int line2 )
2968 16: a_longer_function( line1,
2975 @cindex arglist-intro syntactic symbol
2976 @cindex arglist-close syntactic symbol
2977 Lines 5 and 12 are assigned @code{arglist-intro} syntax since they are
2978 the first line following the open parenthesis, and lines 7 and 14 are
2979 assigned @code{arglist-close} syntax since they contain the parenthesis
2980 that closes the argument list.
2982 @cindex arglist-cont-nonempty syntactic symbol
2983 @cindex arglist-cont syntactic symbol
2984 Lines that continue argument lists can be assigned one of two syntactic
2985 symbols. For example, Lines 2 and 17
2986 are assigned @code{arglist-cont-nonempty} syntax. What this means
2987 is that they continue an argument list, but that the line containing the
2988 parenthesis that opens the list is @emph{not empty} following the open
2989 parenthesis. Contrast this against lines 6 and 13 which are assigned
2990 @code{arglist-cont} syntax. This is because the parenthesis that opens
2991 their argument lists is the last character on that line.
2993 Note that there is no @code{arglist-open} syntax. This is because any
2994 parenthesis that opens an argument list, appearing on a separate line,
2995 is assigned the @code{statement-cont} syntax instead.
2997 A few miscellaneous syntactic symbols that haven't been previously
2998 covered are illustrated by this C++ example:
3002 1: void Bass::play( int volume )
3005 4: /* this line starts a multi-line
3006 5: * comment. This line should get `c' syntax */
3008 7: char* a_multiline_string = "This line starts a multi-line \
3009 8: string. This line should get `string' syntax.";
3017 16: cout << "I played "
3025 @cindex modifier syntactic symbol
3026 The lines to note in this example include:
3030 @cindex func-decl-cont syntactic symbol
3032 line 2, assigned the @code{func-decl-cont} syntax;
3034 @cindex comment-intro syntactic symbol
3036 line 4, assigned both @code{defun-block-intro} @emph{and}
3037 @code{comment-intro} syntax;
3039 @cindex c syntactic symbol
3041 line 5, assigned @code{c} syntax;
3044 @cindex syntactic whitespace
3045 line 6 which, even though it contains nothing but whitespace, is
3046 assigned @code{defun-block-intro}. Note that the appearance of the
3047 comment on lines 4 and 5 do not cause line 6 to be assigned
3048 @code{statement} syntax because comments are considered to be
3049 @dfn{syntactic whitespace}, which are ignored when analyzing
3052 @cindex string syntactic symbol
3054 line 8, assigned @code{string} syntax;
3056 @cindex label syntactic symbol
3058 line 10, assigned @code{label} syntax;
3060 @cindex block-open syntactic symbol
3062 line 11, assigned @code{block-open} syntax;
3064 @cindex cpp-macro syntactic symbol
3065 @cindex cpp-macro-cont syntactic symbol
3067 lines 12 and 14, assigned @code{cpp-macro} syntax.
3069 @cindex stream-op syntactic symbol
3071 line 17, assigned @code{stream-op} syntax.
3075 @cindex multi-line macros
3076 @cindex syntactic whitespace
3077 Multi-line C preprocessor macros are now (somewhat) supported. At least
3078 CC Mode now recognizes the fact that it is inside a multi-line macro,
3079 and it properly skips such macros as syntactic whitespace. In this
3084 1: #define LIST_LOOP(cons, listp) \
3085 2: for (cons = listp; !NILP (cons); cons = XCDR (cons)) \
3086 3: if (!CONSP (cons)) \
3087 4: signal_error ("Invalid list format", listp); \
3093 line 1 is given the syntactic symbol @code{cpp-macro}. This first line
3094 of a macro is always given this symbol. The second and subsequent lines
3095 (e.g. lines 2 through 5) are given the @code{cpp-macro-cont} syntactic
3096 symbol, with a relative buffer position pointing to the @code{#} which
3097 starts the macro definition.
3099 In Objective-C buffers, there are three additional syntactic symbols
3100 assigned to various message calling constructs. Here's an example
3105 1: - (void)setDelegate:anObject
3108 4: [delegate masterWillRebind:self
3109 5: toDelegate:anObject
3110 6: withExtraStuff:stuff];
3116 @cindex objc-method-intro syntactic symbol
3117 @cindex objc-method-args-cont syntactic symbol
3118 @cindex objc-method-call-cont syntactic symbol
3119 Here, line 1 is assigned @code{objc-method-intro} syntax, and line 2 is
3120 assigned @code{objc-method-args-cont} syntax. Lines 5 and 6 are both
3121 assigned @code{objc-method-call-cont} syntax.
3123 @cindex knr-argdecl-intro syntactic symbol
3124 @cindex knr-argdecl syntactic symbol
3125 Two other syntactic symbols can appear in old style, non-prototyped C
3126 code @footnote{a.k.a. K&R C, or Kernighan & Ritchie C}:
3130 1: int add_three_integers(a, b, c)
3135 6: return a + b + c;
3141 Here, line 2 is the first line in an argument declaration list and so is
3142 given the @code{knr-argdecl-intro} syntactic symbol. Subsequent lines
3143 (i.e. lines 3 and 4 in this example), are given @code{knr-argdecl}
3146 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3147 @node Performance Issues, Frequently Asked Questions, Syntactic Symbols, Top
3148 @comment node-name, next, previous,up
3150 @chapter Performance Issues
3151 @cindex Performance Issues
3152 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3154 C and its derivative languages are highly complex creatures. Often,
3155 ambiguous code situations arise that require @ccmode{} to scan
3156 large portions of the buffer to determine syntactic context. Such
3157 pathological code@footnote{such as the output of @code{lex(1)}!}
3158 can cause @ccmode{} to perform fairly badly.
3159 This section identifies some of the coding styles to watch out for, and
3160 suggests some workarounds that you can use to improve performance.
3162 Because @ccmode{} has to scan the buffer backwards from the current
3163 insertion point, and because C's syntax is fairly difficult to parse in
3164 the backwards direction, @ccmode{} often tries to find the nearest
3165 position higher up in the buffer from which to begin a forward scan.
3166 The farther this position is from the current insertion point, the
3167 slower the mode gets. Some coding styles can even force @ccmode{}
3168 to scan from the beginning of the buffer for every line of code!
3170 @findex beginning-of-defun
3171 @findex defun-prompt-regexp
3172 One of the simplest things you can do to reduce scan time, is make sure
3173 any brace that opens a top-level construct@footnote{e.g. a function in
3174 C, or outermost class definition in C++ or Java.} always appears in the
3175 leftmost column. This is actually an Emacs constraint, as embodied in
3176 the @code{beginning-of-defun} function which @ccmode{} uses
3177 heavily. If you insist on hanging top-level open braces on the right
3178 side of the line, then you might want to set the variable
3179 @code{defun-prompt-regexp} to something reasonable @footnote{Note that
3180 this variable is only defined in Emacs 19.}, however that ``something
3181 reasonable'' is difficult to define, so @ccmode{} doesn't do it
3184 @vindex c-Java-defun-prompt-regexp
3185 @vindex Java-defun-prompt-regexp (c-)
3186 A special note about @code{defun-prompt-regexp} in Java mode: while much
3187 of the early sample Java code seems to encourage a style where the brace
3188 that opens a class is hung on the right side of the line, this is not a
3189 good style to pursue in Emacs. @ccmode{} comes with a variable
3190 @code{c-Java-defun-prompt-regexp} which tries to define a regular
3191 expression usable for this style, but there are problems with it. In
3192 some cases it can cause @code{beginning-of-defun} to hang@footnote{This
3193 has been observed in Emacs 19.34 and XEmacs 19.15.}. For this reason,
3194 it is not used by default, but if you feel adventurous, you can set
3195 @code{defun-prompt-regexp} to it in your mode hook. In any event,
3196 setting and rely on @code{defun-prompt-regexp} will definitely slow
3199 You will probably notice pathological behavior from @ccmode{} when
3200 working in files containing large amounts of C preprocessor macros.
3201 This is because Emacs cannot skip backwards over these lines as quickly
3204 @vindex c-recognize-knr-p
3205 @vindex recognize-knr-p (c-)
3206 Previous versions of @ccmode{} had potential performance problems
3207 when recognizing K&R style function argument declarations. This was
3208 because there are ambiguities in the C syntax when K&R style argument
3209 lists are used@footnote{It is hard to distinguish them from top-level
3210 declarations.}. @ccmode{} has adopted BOCM's convention for
3211 limiting the search: it assumes that argdecls are indented at least one
3212 space, and that the function headers are not indented at all. With
3213 current versions of @ccmode{}, user customization of
3214 @code{c-recognize-knr-p} is deprecated. Just don't put argdecls in
3217 @cindex @file{cc-lobotomy.el} file
3218 @vindex cc-lobotomy-pith-list
3219 You might want to investigate the speed-ups contained in the
3220 file @file{cc-lobotomy.el}, which comes as part of the @ccmode{}
3221 distribution, but is completely unsupported.
3222 As mentioned previous, @ccmode{} always trades speed for accuracy,
3223 however it is recognized that sometimes you need speed and can sacrifice
3224 some accuracy in indentation. The file @file{cc-lobotomy.el} contains
3225 hacks that will ``dumb down'' @ccmode{} in some specific ways, making
3226 that trade-off of accurancy for speed. I won't go into details of its
3227 use here; you should read the comments at the top of the file, and look
3228 at the variable @code{cc-lobotomy-pith-list} for details.
3231 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3232 @node Frequently Asked Questions, Getting the latest CC Mode release, Performance Issues, Top
3233 @comment node-name, next, previous,up
3235 @chapter Frequently Asked Questions
3236 @cindex Frequently Asked Questions
3238 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3248 @findex newline-and-indent
3251 @strong{Q.} @emph{How do I re-indent the whole file?}
3253 @strong{A.} Visit the file and hit @kbd{C-x h} to mark the whole
3254 buffer. Then hit @kbd{ESC C-\}.
3257 @strong{Q.} @emph{How do I re-indent the entire function?
3258 @kbd{ESC C-x} doesn't work.}
3260 @strong{A.} @kbd{ESC C-x} is reserved for future Emacs use.
3261 To re-indent the entire function hit @kbd{C-c C-q}.
3264 @strong{Q.} @emph{How do I re-indent the current block?}
3266 @strong{A.} First move to the brace which opens the block with
3267 @kbd{ESC C-u}, then re-indent that expression with
3271 @strong{Q.} @emph{Why doesn't the @kbd{RET} key indent the line to
3272 where the new text should go after inserting the newline?}
3274 @strong{A.} Emacs' convention is that @kbd{RET} just adds a newline,
3275 and that @kbd{C-j} adds a newline and indents it. You can make
3276 @kbd{RET} do this too by adding this to your
3277 @code{c-mode-common-hook} (see the sample @file{.emacs} file
3278 @ref{Sample .emacs File}):
3281 (define-key c-mode-base-map "\C-m" 'newline-and-indent)
3285 This is a very common question. If you want this to be the default
3286 behavior, don't lobby me, lobby RMS! @code{:-)}
3289 @strong{Q.} @emph{I put @code{(c-set-offset 'substatement-open 0)}
3290 in my @file{.emacs} file but I get an error saying that
3291 @code{c-set-offset}'s function definition is void.}
3293 @strong{A.} This means that @ccmode{} wasn't loaded into your
3294 Emacs session by the time the @code{c-set-offset} call was reached,
3295 mostly likely because @ccmode{} is being autoloaded. Instead
3296 of putting the @code{c-set-offset} line in your top-level
3297 @file{.emacs} file, put it in your @code{c-mode-common-hook}, or
3298 simply add the following to the top of your @file{.emacs} file:
3305 See the sample @file{.emacs} file @ref{Sample .emacs File} for
3309 @strong{Q.} @emph{How do I make strings, comments, keywords, and other
3310 constructs appear in different colors, or in bold face, etc.?}
3312 @strong{A.} ``Syntax Colorization'' is a standard Emacs feature,
3313 controlled by @code{font-lock-mode}. It is not part of @ccmode{}.
3316 @strong{Q.} @emph{@kbd{M-a} and @kbd{M-e} used to move over entire
3317 balanced brace lists, but now they move into blocks. How do I get the
3320 @strong{A.} Use @kbd{C-M-f} and @kbd{C-M-b} to move over balanced brace
3321 blocks. Use @kbd{M-a} and @kbd{M-e} to move by statements, which will
3327 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3328 @node Getting the latest CC Mode release, Sample .emacs File, Frequently Asked Questions, Top
3329 @comment node-name, next, previous,up
3331 @chapter Getting the latest CC Mode release
3332 @cindex Getting the latest CC Mode release
3333 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3335 @ccmode{} is now standard with the latest versions of Emacs 19 and
3336 XEmacs 19. It is also the standard for Emacs 20 and XEmacs 20. You
3337 would typically just use the version that comes with your X/Emacs.
3338 These may be slightly out of date due to release schedule skew, so you
3339 should always check the canonical site for the latest version.
3346 @code{http://www.python.org/ftp/emacs/}
3350 @code{ftp://ftp.python.org/pub/emacs/}
3355 There are many files under these directories; you can pick up the entire
3356 distribution (named @code{cc-mode.tar.gz}; a gzip'd tar file), or any of
3357 the individual files, including PostScript documentation.
3359 If you do not have World Wide Web, or anonymous ftp access, you can get
3360 the distribution through an anonymous ftp-to-mail gateway, such as the
3364 @code{ftpmail@@decwrl.dec.com}
3367 To get @ccmode{} via email, send the following message in the body of
3368 your mail to that address:
3371 reply <a valid net address back to you>
3372 connect ftp.python.org
3380 or just send the message "help" for more information on ftpmail.
3381 Response times will vary with the number of requests in the queue. I am
3382 in no way connected to this service, so I make no claims or guarantees
3383 about its availability!
3385 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3386 @node Sample .emacs File, Limitations and Known Bugs, Getting the latest CC Mode release, Top
3387 @comment node-name, next, previous,up
3389 @chapter Sample .emacs file
3390 @cindex Sample .emacs file
3391 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3394 ;; Here's a sample .emacs file that might help you along the way. Just
3395 ;; copy this region and paste it into your .emacs file. You may want to
3396 ;; change some of the actual values.
3398 (defconst my-c-style
3399 '((c-tab-always-indent . t)
3400 (c-comment-only-line-offset . 4)
3401 (c-hanging-braces-alist . ((substatement-open after)
3403 (c-hanging-colons-alist . ((member-init-intro before)
3407 (access-label after)))
3408 (c-cleanup-list . (scope-operator
3411 (c-offsets-alist . ((arglist-close . c-lineup-arglist)
3412 (substatement-open . 0)
3415 (knr-argdecl-intro . -)))
3416 (c-echo-syntactic-information-p . t)
3418 "My C Programming Style")
3420 ;; Customizations for all of c-mode, c++-mode, and objc-mode
3421 (defun my-c-mode-common-hook ()
3422 ;; add my personal style and set it for the current buffer
3423 (c-add-style "PERSONAL" my-c-style t)
3424 ;; offset customizations not in my-c-style
3425 (c-set-offset 'member-init-intro '++)
3426 ;; other customizations
3428 ;; this will make sure spaces are used instead of tabs
3429 indent-tabs-mode nil)
3430 ;; we like auto-newline and hungry-delete
3431 (c-toggle-auto-hungry-state 1)
3432 ;; keybindings for all supported languages. We can put these in
3433 ;; c-mode-base-map because c-mode-map, c++-mode-map, objc-mode-map,
3434 ;; java-mode-map, and idl-mode-map inherit from it.
3435 (define-key c-mode-base-map "\C-m" 'newline-and-indent)
3438 (add-hook 'c-mode-common-hook 'my-c-mode-common-hook)
3441 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3442 @node Limitations and Known Bugs, Mailing Lists and Submitting Bug Reports, Sample .emacs File, Top
3443 @comment node-name, next, previous,up
3444 @chapter Limitations and Known Bugs
3445 @cindex Limitations and Known Bugs
3446 @comment * Limitations and Known Bugs
3447 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3451 Re-indenting large regions or expressions can be slow.
3454 Add-on fill packages may not work as well as @ccmode{}'s built-in
3455 filling routines. I no longer recommend you use @code{filladapt} to
3458 @cindex c-indent-exp
3459 @cindex indent-exp (c-)
3461 @code{c-indent-exp} has not been fully optimized. It essentially
3462 equivalent to hitting @kbd{TAB} (@code{c-indent-command}) on every
3463 line. Some information is cached from line to line, but such caching
3464 invariable causes inaccuracies in analysis in some bizarre situations.
3468 @c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3469 @node Mailing Lists and Submitting Bug Reports, Concept Index, Limitations and Known Bugs, Top
3470 @comment node-name, next, previous,up
3471 @chapter Mailing Lists and Submitting Bug Reports
3472 @cindex Mailing Lists and Submitting Bug Reports
3473 @c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3476 @findex c-submit-bug-report
3477 @findex submit-bug-report (c-)
3478 @cindex beta testers mailing list
3479 @cindex announcement mailing list
3480 To report bugs, use the @kbd{C-c C-b} (@code{c-submit-bug-report})
3481 command. This provides vital information I need to reproduce your
3482 problem. Make sure you include a concise, but complete code example.
3483 Please try to boil your example down to just the essential code needed
3484 to reproduce the problem, and include an exact recipe of steps needed to
3485 expose the bug. Be especially sure to include any code that appears
3486 @emph{before} your bug example, if you think it might affect my ability
3489 Bug reports are now sent to the following email addresses:
3490 @code{cc-mode-help@@python.org} and
3491 @code{bug-gnu-emacs@@gnu.org}; the latter is mirrored on the
3492 Usenet newsgroup @code{gnu.emacs.bug}. You can send other questions and
3493 suggestions (kudos? @code{;-)} to @code{cc-mode-help@@python.org}, or
3494 @code{help-gnu-emacs@@gnu.org} which is mirrored on newsgroup
3495 @code{gnu.emacs.help}.
3497 If you want to get announcements of new CC Mode releases, send the
3498 word @emph{subscribe} in the body of a message to
3499 @code{cc-mode-announce-request@@python.org}. Announcements will also be
3500 posted to the Usenet newsgroup @code{gnu.emacs.sources}. Note that the
3501 @code{cc-mode-victims@@python.org} mailing list was recently
3504 @c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3505 @node Concept Index, Command Index, Mailing Lists and Submitting Bug Reports, Top
3506 @comment node-name, next, previous, up
3507 @unnumbered Concept Index
3508 @c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3513 @c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3514 @node Command Index, Key Index, Concept Index, Top
3515 @comment node-name, next, previous, up
3516 @unnumbered Command Index
3517 @c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3522 Since all @ccmode{} commands are prepended with the string
3523 @samp{c-}, each appears under its @code{c-@var{<thing>}} name and its
3524 @code{@var{<thing>} (c-)} name.
3531 @c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3532 @node Key Index, Variable Index, Command Index, Top
3533 @comment node-name, next, previous, up
3534 @unnumbered Key Index
3535 @c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3540 @c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3541 @node Variable Index, , Key Index, Top
3542 @comment node-name, next, previous, up
3543 @unnumbered Variable Index
3544 @c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3549 Since all @ccmode{} variables are prepended with the string
3550 @samp{c-}, each appears under its @code{c-@var{<thing>}} name and its
3551 @code{@var{<thing>} (c-)} name.