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