*** empty log message ***
[emacs.git] / man / cc-mode.texi
blob2c0933a53350449ec74ab612b556678b64416f79
1 \input texinfo
3 @c Notes to self regarding line handling:
4 @c
5 @c Empty lines are often significant before @end directives; avoid them.
6 @c
7 @c Empty lines before and after @example directives are significant in
8 @c info output but not in TeX.  Empty lines inside @example directives
9 @c are significant.
11 @c Conventions for formatting examples:
12 @c o  If the example contains empty lines then put the surrounding empty
13 @c    lines inside the @example directives.  Put them outside otherwise.
14 @c o  Use @group inside the example only if it shows indentation where
15 @c    the relation between lines inside is relevant.
16 @c o  Format line number columns like this:
17 @c     1: foo
18 @c     2: bar
19 @c       ^ one space
20 @c    ^^ two columns, right alignment
21 @c o  Check line lengths in TeX output; they can typically be no longer
22 @c    than 70 chars, 60 if the paragraph is indented.
24 @comment TBD: Document the finer details of statement anchoring?
26 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
27 @comment %**start of header (This is for running Texinfo on a region)
28 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
30 @comment No overfull hbox marks in the dvi file.
31 @finalout
33 @setfilename  ../info/ccmode
34 @settitle     CC Mode Manual
35 @footnotestyle end
37 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
38 @comment @setchapternewpage odd !! we don't want blank pages !!
39 @comment %**end of header (This is for running Texinfo on a region)
40 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
43 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
44 @comment 
45 @comment Texinfo manual for CC Mode
46 @comment Generated from the original README file by Krishna Padmasola
47 @comment <krishna@earth-gw.njit.edu>
48 @comment
49 @comment Authors:
50 @comment Barry A. Warsaw
51 @comment Martin Stjernholm
52 @comment
53 @comment Maintained by Martin Stjernholm <bug-cc-mode@gnu.org>
54 @comment 
55 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
57 @comment Define an index for syntactic symbols.
58 @defindex ss
60 @comment Combine key, syntactic symbol and concept indices into one.
61 @syncodeindex ss cp
62 @syncodeindex ky cp
64 @copying
65 This manual is for CC Mode in Emacs.
67 Copyright @copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
68 2003 Free Software Foundation, Inc.
70 @quotation
71 Permission is granted to copy, distribute and/or modify this document
72 under the terms of the GNU Free Documentation License, Version 1.1 or
73 any later version published by the Free Software Foundation; with the
74 Invariant Sections being ``The GNU Manifesto'', ``Distribution'' and
75 ``GNU GENERAL PUBLIC LICENSE'', with the Front-Cover texts being ``A GNU
76 Manual'', and with the Back-Cover Texts as in (a) below.  A copy of the
77 license is included in the section entitled ``GNU Free Documentation
78 License'' in the Emacs manual.
80 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
81 this GNU Manual, like GNU software.  Copies published by the Free
82 Software Foundation raise funds for GNU development.''
84 This document is part of a collection distributed under the GNU Free
85 Documentation License.  If you want to distribute this document
86 separately from the collection, you can do so by adding a copy of the
87 license to the document, as described in section 6 of the license.
88 @end quotation
89 @end copying
91 @comment Info directory entry for use by install-info. The indentation
92 @comment here is by request from the FSF folks.
93 @dircategory Emacs
94 @direntry
95 * CC Mode: (ccmode).    Emacs mode for editing C, C++, Objective-C,
96                         Java, Pike, AWK, and CORBA IDL code.
97 @end direntry
99 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
100 @comment TeX title page
101 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
103 @titlepage
104 @sp 10
106 @center @titlefont{CC Mode 5.30}
107 @sp 2
108 @center @subtitlefont{A GNU Emacs mode for editing C and C-like languages}
109 @sp 2
110 @center Barry A. Warsaw, Martin Stjernholm, Alan Mackenzie (AWK support)
112 @page
113 @vskip 0pt plus 1filll
114 @insertcopying
115 @end titlepage
117 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
118 @comment The Top node contains the master menu for the Info file.
119 @comment This appears only in the Info file, not the printed manual.
120 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
122 @node    Top, Introduction, (dir), (dir)
123 @comment node-name, next, previous, up
125 @macro ccmode
126 CC Mode
127 @end macro
129 @ifinfo
130 @top @ccmode{}
132 @ccmode{} is a GNU Emacs mode for editing files containing C, C++,
133 Objective-C, Java, CORBA IDL (and the variants PSDL and CIDL), Pike
134 code and to a certain extent, AWK code @xref{AWK Mode}.  It provides
135 syntax-based indentation, font locking, and has several handy commands
136 and some minor modes to make the editing easier.  It does not provide
137 tools to look up and navigate between functions, classes etc - there are
138 other packages for that.
139 @end ifinfo
141 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
142 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
144 @menu
145 * Introduction::
146 * Getting Connected::
147 * Indentation Engine::
148 * Minor Modes::
149 * Text Filling and Line Breaking::
150 * Macro Handling::
151 * Font Locking::
152 * Commands::
153 * Customizing Indentation::
154 * Syntactic Symbols::
155 * Indentation Functions::
156 * AWK Mode::
157 * Odds and Ends::
158 * Performance Issues::
159 * Limitations and Known Bugs::
160 * Frequently Asked Questions::
161 * Getting the Latest CC Mode Release::
162 * Mailing Lists and Submitting Bug Reports::
163 * Sample .emacs File::
165  --- Indices ---
167 * Command and Function Index::
168 * Variable Index::
169 * Concept Index::
171 @detailmenu
172  --- The Detailed Node Listing ---
174 Indentation Engine
176 * Syntactic Analysis::
177 * Indentation Calculation::
179 Minor Modes
181 * Auto-newline Insertion::
182 * Hungry-deletion of Whitespace::
184 Font Locking
186 * Font Locking Preliminaries::
187 * Faces::
188 * Documentation Comments::
190 Auto-newline Insertion
192 * Hanging Braces::
193 * Hanging Colons::
194 * Hanging Semicolons and Commas::
195 * Other Electric Commands::
196 * Clean-ups::
198 Commands
200 * Indentation Commands::
201 * Movement Commands::
202 * Other Commands::
204 Customizing Indentation
206 * Interactive Customization::
207 * Permanent Customization::
208 * Hooks::
209 * Styles::
210 * Advanced Customizations::
212 Styles
214 * Built-in Styles::
215 * Choosing a Style::
216 * Adding Styles::
217 * File Styles::
219 Advanced Customizations
221 * Custom Indentation Functions::
222 * Custom Brace and Colon Hanging::
223 * Customizing Semicolons and Commas::
224 * Other Special Indentations::
226 AWK Mode
228 * Initialising AWK Mode::
229 * AWK Mode Font Locking::
230 * AWK Mode Defuns::
231 @end detailmenu
232 @end menu
235 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
236 @node    Introduction, Getting Connected, Top, Top
237 @comment node-name, next, previous, up
238 @chapter Introduction
239 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
241 @cindex BOCM
243 Welcome to @ccmode{}, a GNU Emacs mode for editing files containing C,
244 C++, Objective-C, Java, CORBA IDL (and the variants CORBA PSDL and
245 CIDL), Pike and to a certain extent, AWK code (@pxref{AWK Mode}).  This
246 incarnation of the mode is descended from @file{c-mode.el} (also called
247 ``Boring Old C Mode'' or BOCM @t{:-)}, and @file{c++-mode.el} version 2,
248 which Barry has been maintaining since 1992.  Late in 1997, Martin
249 joined the @ccmode{} Maintainers Team, and implemented the Pike support.
250 As of 2000 Martin has taken over as the sole maintainer.  @ccmode{} did
251 not originally contain the font lock support for its languages --- that
252 was added in version 5.30.  AWK support was also added in 5.30 by Alan
253 Mackenzie.
255 This manual describes @ccmode{}
256 @comment The following line must appear on its own, so that the automated
257 version 5.30.
258 @comment Release.py script can update the version number automatically
260 @ccmode{} supports the editing of K&R and ANSI C, C++, Objective-C,
261 Java, CORBA's Interface Definition Language, Pike@footnote{A C-like
262 scripting language with its roots in the LPC language used in some MUD
263 engines.  See @uref{http://pike.ida.liu.se/}.} and AWK files.  In this
264 way, you can easily set up consistent font locking and coding styles for
265 use in editing all of these languages, although AWK is not yet as
266 uniformly integrated as the other languages.
268 @findex c-mode
269 @findex c++-mode
270 @findex objc-mode
271 @findex java-mode
272 @findex idl-mode
273 @findex pike-mode
274 @findex awk-mode
275 Note that the name of this package is ``@ccmode{},'' but there is no top
276 level @code{cc-mode} entry point.  All of the variables, commands, and
277 functions in @ccmode{} are prefixed with @code{c-@var{thing}}, and
278 @code{c-mode}, @code{c++-mode}, @code{objc-mode}, @code{java-mode},
279 @code{idl-mode}, @code{pike-mode}, and @code{awk-mode} entry points are
280 provided.  This package is intended to be a replacement for
281 @file{c-mode.el}, @file{c++-mode.el} and @file{awk-mode.el}.
283 @c @cindex @file{cc-compat.el} file
284 @c This distribution also contains a file
285 @c called @file{cc-compat.el} which should ease your transition from BOCM
286 @c to @ccmode{}.  If you have a BOCM configuration you are really happy
287 @c with, and want to postpone learning how to configure @ccmode{}, take a
288 @c look at that file.  It maps BOCM configuration variables to @ccmode{}'s
289 @c indentation model.  It is not actively supported so for the long run,
290 @c you should learn how to customize @ccmode{} to support your coding
291 @c style.
293 A special word of thanks goes to Krishna Padmasola for his work in
294 converting the original @file{README} file to Texinfo format.  I'd also
295 like to thank all the @ccmode{} victims who help enormously during the
296 early beta stages of @ccmode{}'s development.
299 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
300 @node    Getting Connected, Indentation Engine, Introduction, Top
301 @comment node-name, next, previous, up
302 @chapter Getting Connected
303 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
305 If you got this version of @ccmode{} with Emacs or XEmacs, it should
306 work just fine right out of the box.  Note however that you may not have
307 the latest @ccmode{} release and may want to upgrade your copy.
309 If you are upgrading an existing @ccmode{} installation, please see the
310 @file{README} file for installation details.  @ccmode{} may not work
311 with older versions of Emacs or XEmacs.  See the @ccmode{} release notes
312 at @uref{http://cc-mode.sourceforge.net} for the latest information on
313 Emacs version and package compatibility (@pxref{Getting the Latest CC
314 Mode Release}).
316 @deffn Command c-version
317 @findex version (c-)
318 You can find out what version of @ccmode{} you are using by visiting a C
319 file and entering @kbd{M-x c-version RET}.  You should see this message in
320 the echo area:
322 @example
323 Using CC Mode version 5.XX
324 @end example
326 @noindent
327 where @samp{XX} is the minor release number.
328 @end deffn
331 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
332 @node    Indentation Engine, Minor Modes, Getting Connected, Top
333 @comment node-name, next, previous, up
334 @chapter Indentation Engine
335 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
337 @ccmode{} has an indentation engine that provides a flexible and general
338 mechanism for customizing indentation. It separates indentation
339 calculation into two steps: first, @ccmode{} analyzes the line of code
340 being indented to determine the kind of language construct it's looking
341 at, then it applies user defined offsets to the current line based on
342 this analysis.
344 This section will briefly cover how indentation is calculated in
345 @ccmode{}. It is important to understand the indentation model being
346 used so that you will know how to customize @ccmode{} for your personal
347 coding style.  All the details are in @ref{Customizing Indentation}, and
348 later chapters.
350 @defopt c-syntactic-indentation
351 @vindex syntactic-indentation (c-)
352 Syntactic analysis for indentation is done when this is non-@code{nil}
353 (which is the default).  When it's @code{nil} every line is just
354 indented to the same level as the previous one, and @kbd{TAB}
355 (@code{c-indent-command}) adjusts the indentation in steps of
356 @code{c-basic-offset}.  The indentation style has no effect, nor any of
357 the indentation associated variables, e.g., @code{c-special-indent-hook}.
358 @end defopt
360 @menu
361 * Syntactic Analysis::
362 * Indentation Calculation::
363 @end menu
366 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
367 @node    Syntactic Analysis, Indentation Calculation, , Indentation Engine
368 @comment node-name, next, previous, up
369 @section Syntactic Analysis
370 @cindex syntactic analysis
371 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
373 @cindex relative buffer position
374 @cindex syntactic symbols
375 @cindex syntactic component
376 @cindex syntactic component list
377 The first thing @ccmode{} does when indenting a line of code, is to
378 analyze the line, determining the @dfn{syntactic component list} of the
379 construct on that line.  A syntactic component consists of a pair of
380 elements (in lisp parlance, a @emph{cons cell}), the first being
381 a @dfn{syntactic symbol}, the second being a @dfn{relative
382 buffer position}.  Syntactic symbols describe elements of C code
383 @footnote{Unless otherwise noted, the term ``C code'' refers to all
384 the C-like languages.}, e.g., @code{statement}, @code{substatement},
385 @code{class-open}, @code{class-close}, etc.  @xref{Syntactic Symbols},
386 for a complete list of currently recognized syntactic symbols and their
387 semantics.  The style variable @code{c-offsets-alist} also contains the
388 list of currently supported syntactic symbols.
390 Conceptually, a line of C code is always indented relative to the
391 indentation of some line higher up in the buffer.  This is represented
392 by the relative buffer position in the syntactic component.
394 Here is an example.  Suppose we had the following code as the only thing
395 in a C++ buffer @footnote{The line numbers in this and future examples
396 don't actually appear in the buffer, of course!}:
398 @example
399  1: void swap( int& a, int& b )
400  2: @{
401  3:     int tmp = a;
402  4:     a = b;
403  5:     b = tmp;
404  6: @}
405 @end example
407 @kindex C-c C-s
408 @findex c-show-syntactic-information
409 @findex show-syntactic-information (c-)
410 We can use the command @kbd{C-c C-s} (bound to
411 @code{c-show-syntactic-information}) to simply report what the
412 syntactic analysis is for the current line.  Running this command on
413 line 4 of this example, we'd see in the echo area@footnote{With a
414 universal argument (i.e., @kbd{C-u C-c C-s}) the analysis is inserted
415 into the buffer as a comment on the current line.}:
417 @example
418 ((statement 35))
419 @end example
421 This tells us that the line is a statement and it is indented relative
422 to buffer position 35, which happens to be the @samp{i} in @code{int} on
423 line 3.  If you were to move point to line 3 and hit @kbd{C-c C-s}, you
424 would see:
426 @example
427 ((defun-block-intro 29))
428 @end example
430 This indicates that the @samp{int} line is the first statement in a top
431 level function block, and is indented relative to buffer position 29,
432 which is the brace just after the function header.
434 Here's another example:
436 @example
437  1: int add( int val, int incr, int doit )
438  2: @{
439  3:     if( doit )
440  4:         @{
441  5:             return( val + incr );
442  6:         @}
443  7:     return( val );
444  8: @}
445 @end example
447 @noindent
448 Hitting @kbd{C-c C-s} on line 4 gives us:
450 @example
451 ((substatement-open 46))
452 @end example
454 @cindex substatement
455 @cindex substatement block
456 @noindent
457 which tells us that this is a brace that @emph{opens} a substatement
458 block. @footnote{A @dfn{substatement} is the line after a
459 conditional statement, such as @code{if}, @code{else}, @code{while},
460 @code{do}, @code{switch}, etc.  A @dfn{substatement
461 block} is a brace block following one of these conditional statements.}
463 @cindex comment-only line
464 Syntactic component lists can contain more than one component, and
465 individual syntactic components need not have relative buffer positions.
466 The most common example of this is a line that contains a @dfn{comment
467 only line}.
469 @example
470  1: void draw_list( List<Drawables>& drawables )
471  2: @{
472  3:         // call the virtual draw() method on each element in list
473  4:     for( int i=0; i < drawables.count(), ++i )
474  5:     @{
475  6:         drawables[i].draw();
476  7:     @}
477  8: @}
478 @end example
480 @noindent
481 Hitting @kbd{C-c C-s} on line 3 of this example gives:
483 @example
484 ((comment-intro) (defun-block-intro 46))
485 @end example
487 @noindent
488 and you can see that the syntactic component list contains two syntactic
489 components.  Also notice that the first component,
490 @samp{(comment-intro)} has no relative buffer position.
493 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
494 @node    Indentation Calculation, , Syntactic Analysis, Indentation Engine
495 @comment node-name, next, previous, up
496 @section Indentation Calculation
497 @cindex indentation
498 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
500 Indentation for a line is calculated using the syntactic
501 component list derived in step 1 above (@pxref{Syntactic Analysis}).
502 Each component contributes to the final total indentation of the line in
503 two ways.
505 First, the syntactic symbols are looked up in the @code{c-offsets-alist}
506 style variable, which is an association list of syntactic symbols and
507 the offsets to apply for those symbols.  These offsets are added to a
508 running total.
510 Second, if the component has a relative buffer position, @ccmode{}
511 adds the column number of that position to the running total.  By adding
512 up the offsets and columns for every syntactic component on the list,
513 the final total indentation for the current line is computed.
515 Let's use our two code examples above to see how this works.  Here is
516 our first example again:
518 @example
519  1: void swap( int& a, int& b )
520  2: @{
521  3:     int tmp = a;
522  4:     a = b;
523  5:     b = tmp;
524  6: @}
525 @end example
527 Let's say point is on line 3 and we hit the @kbd{TAB} key to reindent
528 the line.  Remember that the syntactic component list for that
529 line is:
531 @example
532 ((defun-block-intro 29))
533 @end example
535 @noindent
536 @ccmode{} looks up @code{defun-block-intro} in the
537 @code{c-offsets-alist} style variable.  Let's say it finds the value
538 @samp{4}; it adds this to the running total (initialized to zero),
539 yielding a running total indentation of 4 spaces.
541 Next @ccmode{} goes to buffer position 29 and asks for the current
542 column.  This brace is in column zero, so @ccmode{}
543 adds @samp{0} to the running total.  Since there is only one syntactic
544 component on the list for this line, indentation calculation is
545 complete, and the total indentation for the line
546 is 4 spaces.
548 Here's another example:
550 @example
551  1: int add( int val, int incr, int doit )
552  2: @{
553  3:     if( doit )
554  4:         @{
555  5:             return( val + incr );
556  6:         @}
557  7:     return( val );
558  8: @}
559 @end example
561 If we were to hit @kbd{TAB} on line 4 in the above example, the same
562 basic process is performed, despite the differences in the syntactic
563 component list.  Remember that the list for this line is:
565 @example
566 ((substatement-open 46))
567 @end example
569 Here, @ccmode{} first looks up the @code{substatement-open} symbol
570 in @code{c-offsets-alist}. Let's say it finds the value @samp{4}.  This
571 yields a running total of 4.  @ccmode{} then goes to
572 buffer position 46, which is the @samp{i} in @code{if} on line 3.  This
573 character is in the fourth column on that line so adding this to the
574 running total yields an indentation for the line of 8 spaces.
576 Simple, huh?
578 Actually, the mode usually just does The Right Thing without you having
579 to think about it in this much detail.  But when customizing
580 indentation, it's helpful to understand the general indentation model
581 being used.
583 As you configure @ccmode{}, you might want to set the variable
584 @code{c-echo-syntactic-information-p} to non-@code{nil} so that the
585 syntactic component list and calculated offset will always be echoed in
586 the minibuffer when you hit @kbd{TAB}.
589 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
590 @node    Minor Modes, Text Filling and Line Breaking, Indentation Engine, Top
591 @comment node-name, next, previous, up
592 @chapter Minor Modes
593 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
595 @ccmode{} contains two minor-mode-like features that you should
596 find useful while entering new C code.  The first is called
597 @dfn{auto-newline} mode, and the second is called @dfn{hungry-delete}
598 mode.  These minor modes can be toggled on and off independently, and
599 @ccmode{} can be configured so that it starts up with any
600 combination of these minor modes.  By default, both of these minor modes
601 are turned off.
603 The state of the minor modes is always reflected in the minor mode list
604 on the modeline of the @ccmode{} buffer.  When auto-newline mode is
605 enabled, you will see @samp{C/a} on the mode line@footnote{The @samp{C}
606 would be replaced with the name of the language in question for the
607 other languages @ccmode{} supports.}.  When hungry delete mode is
608 enabled you will see @samp{C/h} and if both modes were enabled, you'd
609 see @samp{C/ah}.
611 @kindex C-c C-a
612 @kindex C-c C-d
613 @kindex C-c C-t
614 @findex c-toggle-hungry-state
615 @findex c-toggle-auto-state
616 @findex c-toggle-auto-hungry-state
617 @findex toggle-hungry-state (c-)
618 @findex toggle-auto-state (c-)
619 @findex toggle-auto-hungry-state (c-)
620 @ccmode{} provides key bindings which allow you to toggle the minor
621 modes on the fly while editing code.  To toggle just the auto-newline
622 state, hit @kbd{C-c C-a} (bound to @code{c-toggle-auto-state}).  When
623 you do this, you should see the @samp{a} indicator either appear or
624 disappear on the modeline.  Similarly, to toggle just the
625 hungry-delete state, use @kbd{C-c C-d} (@code{c-toggle-hungry-state}),
626 and to toggle both states, use @kbd{C-c C-t}
627 (@code{c-toggle-auto-hungry-state}).
629 To set up the auto-newline and hungry-delete states to your preferred
630 values, you would need to add some lisp to your @file{.emacs} file that
631 called one of the @code{c-toggle-*-state} functions directly.  When
632 called programmatically, each function takes a numeric value, where
633 a positive number enables the minor mode, a negative number disables the
634 mode, and zero toggles the current state of the mode.
636 So for example, if you wanted to enable both auto-newline and
637 hungry-delete for all your C file editing, you could add the following
638 to your @file{.emacs} file:
640 @example
641 (add-hook 'c-mode-common-hook
642           (lambda () (c-toggle-auto-hungry-state 1)))
643 @end example
645 @menu
646 * Auto-newline Insertion::
647 * Hungry-deletion of Whitespace::
648 @end menu
651 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
652 @node    Auto-newline Insertion, Hungry-deletion of Whitespace, , Minor Modes
653 @comment node-name, next, previous, up
654 @section Auto-newline Insertion
655 @cindex auto-newline
656 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
658 @cindex electric characters
659 Auto-newline minor mode works by enabling certain @dfn{electric
660 characters}.  Special characters such as the left and right braces,
661 colons, semicolons, etc., have been made electric to perform some
662 magic formatting in addition to inserting the typed character.  As a
663 general rule, electric characters are only electric when the following
664 conditions apply:
666 @itemize @bullet
667 @item
668 Auto-newline minor mode is enabled, as evidenced by a @samp{C/a} or
669 @samp{C/ah} indicator on the modeline.
671 @item
672 @cindex literal
673 @cindex syntactic whitespace
674 The character was not typed inside of a literal @footnote{A
675 @dfn{literal} is defined as any comment, string, or preprocessor macro
676 definition.  These constructs are also known as @dfn{syntactic
677 whitespace} since they are usually ignored when scanning C code.}.
679 @item
680 No numeric argument was supplied to the command (i.e., it was typed as
681 normal, with no @kbd{C-u} prefix).
682 @end itemize
684 @menu
685 * Hanging Braces::
686 * Hanging Colons::
687 * Hanging Semicolons and Commas::
688 * Other Electric Commands::
689 * Clean-ups::
690 @end menu
693 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
694 @node    Hanging Braces, Hanging Colons, , Auto-newline Insertion
695 @comment node-name, next, previous, up
696 @subsection Hanging Braces
697 @cindex hanging braces
698 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
700 @findex c-electric-brace
701 @findex electric-brace (c-)
702 @kindex @{
703 @kindex @}
705 When you type either an open or close brace (i.e., @kbd{@{} or @kbd{@}}),
706 the electric command @code{c-electric-brace} gets run.  This command has
707 two electric formatting behaviors.  First, it will perform some
708 reindentation of the line the brace was typed on, and second, it will
709 add various newlines before and/or after the typed brace.
710 Reindentation occurs automatically whenever the electric behavior is
711 enabled.  If the brace ends up on a line other than the one it was typed
712 on, then that line is also reindented.
714 The default in auto-newline mode is to insert newlines both before and
715 after a brace, but that can be controlled by the
716 @code{c-hanging-braces-alist} style variable.
718 @defopt c-hanging-braces-alist
719 @vindex hanging-braces-alist (c-)
721 This variable contains a mapping between syntactic symbols related to
722 braces, and a list of places to insert a newline.  The syntactic symbols
723 that are useful for this list are @code{brace-list-intro},
724 @code{statement-cont}, @code{inexpr-class-open},
725 @code{inexpr-class-close}, and all the @code{*-open} and @code{*-close}
726 symbols.  @xref{Syntactic Symbols}, for a more detailed description of
727 these syntactic symbols, except for @code{inexpr-class-open} and
728 @code{inexpr-class-close}, which aren't actual syntactic symbols.
730 The braces of anonymous inner classes in Java are given the special
731 symbols @code{inexpr-class-open} and @code{inexpr-class-close}, so that
732 they can be distinguished from the braces of normal classes@footnote{The
733 braces of anonymous classes produce a combination of
734 @code{inexpr-class}, and @code{class-open} or @code{class-close} in
735 normal indentation analysis.}.
737 Note that the aggregate constructs in Pike mode, @samp{(@{}, @samp{@})},
738 @samp{([}, @samp{])}, and @samp{(<}, @samp{>)}, do not count as brace
739 lists in this regard, even though they do for normal indentation
740 purposes.  It's currently not possible to set automatic newlines on
741 these constructs.
743 The value associated with each syntactic symbol in this association list
744 is called an @var{action}, which can be either a function or a list.
745 @xref{Custom Brace and Colon Hanging}, for a more detailed discussion of
746 using a function as a brace hanging @var{action}.
748 When the @var{action} is a list, it can contain any combination of the
749 symbols @code{before} and @code{after}, directing @ccmode{} where to
750 put newlines in relationship to the brace being inserted.  Thus, if the
751 list contains only the symbol @code{after}, then the brace is said to
752 @dfn{hang} on the right side of the line, as in:
754 @example
755 // here, open braces always `hang'
756 void spam( int i ) @{
757     if( i == 7 ) @{
758         dosomething(i);
759     @}
761 @end example
763 When the list contains both @code{after} and @code{before}, the braces
764 will appear on a line by themselves, as shown by the close braces in the
765 above example.  The list can also be empty, in which case no newlines
766 are added either before or after the brace.
768 If a syntactic symbol is missing entirely from
769 @code{c-hanging-braces-alist}, it's treated in the same way as an
770 @var{action} with a list containing @code{before} and @code{after}, so
771 that braces by default end up on their own line.
773 For example, the default value of @code{c-hanging-braces-alist} is:
775 @example
776 ((brace-list-open)
777  (brace-entry-open)
778  (statement-cont)
779  (substatement-open after)
780  (block-close . c-snug-do-while)
781  (extern-lang-open after)
782  (inexpr-class-open after)
783  (inexpr-class-close before))
784 @end example
786 @noindent which says that @code{brace-list-open},
787 @code{brace-entry-open} and @code{statement-cont}@footnote{Brace lists
788 inside statements, such as initializers for static array variables
789 inside functions in C, are recognized as @code{statement-cont}.  All
790 normal substatement blocks are recognized with other symbols.} braces
791 should both hang on the right side and allow subsequent text to follow
792 on the same line as the brace.  Also, @code{substatement-open},
793 @code{extern-lang-open}, and @code{inexpr-class-open} braces should hang
794 on the right side, but subsequent text should follow on the next line.
795 The opposite holds for @code{inexpr-class-close} braces; they won't
796 hang, but the following text continues on the same line.  Here, in the
797 @code{block-close} entry, you also see an example of using a function as
798 an @var{action}.  In all other cases, braces are put on a line by
799 themselves.
800 @end defopt
803 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
804 @node    Hanging Colons, Hanging Semicolons and Commas, Hanging Braces, Auto-newline Insertion
805 @comment node-name, next, previous, up
806 @subsection Hanging Colons
807 @cindex hanging colons
808 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
810 Using a mechanism similar to brace hanging (@pxref{Hanging Braces}),
811 colons can also be made to hang using the style variable
812 @code{c-hanging-colons-alist}.
814 @defopt c-hanging-colons-alist
815 @vindex hanging-colons-alist (c-)
817 The syntactic symbols appropriate for this association list are:
818 @code{case-label}, @code{label}, @code{access-label},
819 @code{member-init-intro}, and @code{inher-intro}.  Note however that for
820 @code{c-hanging-colons-alist}, @var{action}s as functions are not
821 supported. See also @ref{Custom Brace and Colon Hanging} for details.
823 In C++, double-colons are used as a scope operator but because these
824 colons always appear right next to each other, newlines before and after
825 them are controlled by a different mechanism, called @dfn{clean-ups} in
826 @ccmode{}.  @xref{Clean-ups}, for details.
827 @end defopt
830 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
831 @node    Hanging Semicolons and Commas, Other Electric Commands, Hanging Colons, Auto-newline Insertion
832 @comment node-name, next, previous, up
833 @subsection Hanging Semicolons and Commas
834 @cindex hanging semicolons
835 @cindex hanging commas
836 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
838 Semicolons and commas are also electric in @ccmode{}, but since
839 these characters do not correspond directly to syntactic symbols, a
840 different mechanism is used to determine whether newlines should be
841 automatically inserted after these characters.  @xref{Customizing
842 Semicolons and Commas}, for details.
845 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
846 @node    Other Electric Commands, Clean-ups, Hanging Semicolons and Commas, Auto-newline Insertion
847 @comment node-name, next, previous, up
848 @subsection Other Electric Commands
849 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
851 A few other keys also provide electric behavior, often only to reindent
852 the line.  Common to all of them is that they only reindent if used in
853 normal code (as opposed to in a string literal or comment), and
854 @code{c-syntactic-indentation} isn't @code{nil}.  They are:
856 @table @kbd
857 @item #
858 @kindex #
859 @findex c-electric-pound
860 @findex electric-pound (c-)
861 @vindex c-electric-pound-behavior
862 @vindex electric-pound-behavior (c-)
863 Pound (bound to @code{c-electric-pound}) is electric when typed as the
864 first non-whitespace character on a line and not within a macro
865 definition.  In this case, the variable @code{c-electric-pound-behavior}
866 is consulted for the electric behavior.  This variable takes a list
867 value, although the only element currently defined is @code{alignleft},
868 which tells this command to force the @samp{#} character into column
869 zero.  This is useful for entering preprocessor macro definitions.
871 Pound is not electric in AWK buffers, where @samp{#} starts a comment,
872 and is bound to @code{self-insert-command} like any typical printable
873 character.
875 @item *
876 @kindex *
877 @itemx /
878 @kindex /
879 @findex c-electric-star
880 @findex electric-star (c-)
881 @findex c-electric-slash
882 @findex electric-slash (c-)
883 Stars and slashes (bound to @code{c-electric-star} and
884 @code{c-electric-slash} respectively) are also electric under certain
885 circumstances.  If a @samp{*} is inserted as the second character of a C
886 style block comment on a comment-only line, then the comment delimiter
887 is indented as defined by @code{c-offsets-alist}.  A comment-only line
888 is defined as a line which contains only a comment, as in:
890 @example
891 @group
892 void spam( int i )
894     // this is a comment-only line...
895     if( i == 7 )                // but this is not
896     @{
897         dosomething(i);
898     @}
900 @end group
901 @end example
903 Likewise, if a @samp{/} is inserted as the second slash in a C++ style
904 line comment (also only on a comment-only line), then the line is
905 indented as defined by @code{c-offsets-alist}.
907 In AWK mode, @samp{*} and @samp{/} do not delimit comments and are
908 bound to @code{self-insert-command}.
910 @item <
911 @kindex <
912 @itemx >
913 @kindex >
914 @findex c-electric-lt-gt
915 @findex electric-lt-gt (c-)
916 Less-than and greater-than signs (bound to @code{c-electric-lt-gt}) are
917 electric, but only in C++ mode.  Hitting the second of two @kbd{<} or
918 @kbd{>} keys reindents the line if it is a C++ style stream operator.
920 @item (
921 @kindex (
922 @itemx )
923 @kindex )
924 @findex c-electric-paren
925 @findex electric-paren (c-)
926 The normal parenthesis characters @samp{(} and @samp{)} reindent the
927 current line.  This is useful for getting the closing parenthesis of an
928 argument list aligned automatically.
929 @end table
931 @deffn Command c-electric-continued-statement
932 @findex electric-continued-statement (c-)
934 Certain keywords, depending on language, are electric to cause
935 reindentation when they are preceded only by whitespace on the line.
936 The keywords are those that continue an earlier statement instead of
937 starting a new one: @code{else}, @code{while}, @code{catch} (only in C++
938 and Java) and @code{finally} (only in Java).
940 An example:
942 @example
943 @group
944 for (i = 0; i < 17; i++)
945   if (a[i])
946     res += a[i]->offset;
947 else
948 @end group
949 @end example
951 Here, the @code{else} should be indented like the preceding @code{if},
952 since it continues that statement. @ccmode{} will automatically reindent
953 it after the @code{else} has been typed in full, since it's not until
954 then it's possible to decide whether it's a new statement or a
955 continuation of the preceding @code{if}.
957 @vindex abbrev-mode
958 @findex abbrev-mode
959 @cindex Abbrev mode
960 @ccmode{} uses Abbrev mode (@pxref{Abbrevs,,, emacs, The Emacs Editor})
961 to accomplish this. It's therefore turned on by default in all language
962 modes except IDL mode, since CORBA IDL doesn't have any statements.
963 @end deffn
966 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
967 @node    Clean-ups, , Other Electric Commands, Auto-newline Insertion
968 @comment node-name, next, previous, up
969 @subsection Clean-ups
970 @cindex clean-ups
971 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
973 @dfn{Clean-ups} are mechanisms complementary to colon and brace hanging.
974 On the surface, it would seem that clean-ups overlap the functionality
975 provided by the @code{c-hanging-*-alist} variables.  Clean-ups are
976 however used to adjust code ``after-the-fact,'' i.e., to adjust the
977 whitespace in constructs after they are typed.
979 Most of the clean-ups are only applicable to counteract automatically
980 inserted newlines, and will therefore only have any effect if the
981 auto-newline minor mode is turned on.  Others will work all the time.
983 @defopt c-cleanup-list
984 @vindex cleanup-list (c-)
985 @cindex literal
987 You can configure @ccmode{}'s clean-ups by setting the style variable
988 @code{c-cleanup-list}, which is a list of clean-up symbols.  By default,
989 @ccmode{} cleans up only the @code{scope-operator} construct, which is
990 necessary for proper C++ support.  Note that clean-ups are only
991 performed when the construct does not occur within a literal
992 (@pxref{Auto-newline Insertion}), and when there is nothing but
993 whitespace appearing between the individual components of the construct.
994 @end defopt
996 These are the clean-ups that are only active in the auto-newline minor
997 mode:
999 @c TBD: Would like to use some sort of @deffoo here; @table indents a
1000 @c bit too much in dvi output.
1001 @table @code
1002 @item brace-else-brace
1003 Clean up @samp{@} else @{} constructs by placing the entire construct on
1004 a single line.  Clean-up occurs when the open brace after the
1005 @samp{else} is typed.  So for example, this:
1007 @example
1008 @group
1009 void spam(int i)
1011     if( i==7 ) @{
1012         dosomething();
1013     @}
1014     else
1015     @{
1016 @end group
1017 @end example
1019 @noindent
1020 appears like this after the last open brace is typed:
1022 @example
1023 @group
1024 void spam(int i)
1026     if( i==7 ) @{
1027         dosomething();
1028     @} else @{
1029 @end group
1030 @end example
1032 @item brace-elseif-brace
1033 Similar to the @code{brace-else-brace} clean-up, but this cleans up
1034 @samp{@} else if (...) @{} constructs.  For example:
1036 @example
1037 @group
1038 void spam(int i)
1040     if( i==7 ) @{
1041         dosomething();
1042     @}
1043     else if( i==3 )
1044     @{
1045 @end group
1046 @end example
1048 @noindent
1049 appears like this after the last open parenthesis is typed:
1051 @example
1052 @group
1053 void spam(int i)
1055     if( i==7 ) @{
1056         dosomething();
1057     @} else if( i==3 )
1058     @{
1059 @end group
1060 @end example
1062 @noindent
1063 and like this after the last open brace is typed:
1065 @example
1066 @group
1067 void spam(int i)
1069     if( i==7 ) @{
1070         dosomething();
1071     @} else if( i==3 ) @{
1072 @end group
1073 @end example
1075 @item brace-catch-brace
1076 Analogous to @code{brace-elseif-brace}, but cleans up @samp{@} catch
1077 (...) @{} in C++ and Java mode.
1079 @item empty-defun-braces
1080 Clean up braces following a top-level function or class definition that
1081 contains no body.  Clean up occurs when the closing brace is typed.
1082 Thus the following:
1084 @example
1085 @group
1086 class Spam
1089 @end group
1090 @end example
1092 @noindent
1093 is transformed into this when the close brace is typed:
1095 @example
1096 @group
1097 class Spam
1098 @{@}
1099 @end group
1100 @end example
1102 @item defun-close-semi
1103 Clean up the terminating semicolon on top-level function or class
1104 definitions when they follow a close brace.  Clean up occurs when the
1105 semicolon is typed.  So for example, the following:
1107 @example
1108 @group
1109 class Spam
1113 @end group
1114 @end example
1116 @noindent
1117 is transformed into this when the semicolon is typed:
1119 @example
1120 @group
1121 class Spam
1124 @end group
1125 @end example
1127 @item list-close-comma
1128 Clean up commas following braces in array and aggregate initializers.
1129 Clean up occurs when the comma is typed.
1131 @item scope-operator
1132 Clean up double colons which may designate a C++ scope operator split
1133 across multiple lines@footnote{Certain C++ constructs introduce
1134 ambiguous situations, so @code{scope-operator} clean-ups may not always
1135 be correct.  This usually only occurs when scoped identifiers appear in
1136 switch label tags.}.  Clean up occurs when the second colon is typed.
1137 You will always want @code{scope-operator} in the @code{c-cleanup-list}
1138 when you are editing C++ code.
1139 @end table
1141 The following clean-ups are always active when they occur on
1142 @code{c-cleanup-list}, and are thus not affected by the auto-newline
1143 minor mode:
1145 @table @code
1146 @item space-before-funcall
1147 Insert a space between the function name and the opening parenthesis of
1148 a function call.  This produces function calls in the style mandated by
1149 the GNU coding standards, e.g., @samp{signal (SIGINT, SIG_IGN)} and
1150 @samp{abort ()}.  Clean up occurs when the opening parenthesis is typed.
1152 @item compact-empty-funcall
1153 Clean up any space between the function name and the opening parenthesis
1154 of a function call that has no arguments.  This is typically used
1155 together with @code{space-before-funcall} if you prefer the GNU function
1156 call style for functions with arguments but think it looks ugly when
1157 it's only an empty parenthesis pair.  I.e., you will get @samp{signal
1158 (SIGINT, SIG_IGN)}, but @samp{abort()}.  Clean up occurs when the
1159 closing parenthesis is typed.
1160 @end table
1163 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1164 @node    Hungry-deletion of Whitespace, , Auto-newline Insertion, Minor Modes
1165 @comment node-name, next, previous, up
1166 @section Hungry-deletion of Whitespace
1167 @cindex hungry-deletion
1168 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1170 Hungry deletion of whitespace, or as it more commonly called,
1171 @dfn{hungry-delete mode}, is a simple feature that some people find
1172 extremely useful.  In fact, you might find yourself wanting
1173 hungry-delete in @strong{all} your editing modes!
1175 @kindex DEL
1176 @kindex C-d
1178 In a nutshell, when hungry-delete mode is enabled, hitting the @kbd{DEL}
1179 or @kbd{C-d} keys will consume all preceding or following whitespace,
1180 including newlines and tabs.  This can really cut down on the number of
1181 times you have to hit these keys if, for example, you made a mistake on
1182 the preceding line.
1184 @deffn Command c-electric-backspace
1185 @findex electric-backspace (c-)
1186 This command is run by default when you hit the @kbd{DEL} key.  It
1187 deletes any amount of whitespace in the backwards direction if
1188 hungry-delete mode is enabled.  When it's disabled, or when used with
1189 a prefix argument or in a literal (@pxref{Auto-newline Insertion}),
1190 the function contained in the @code{c-backspace-function} variable is
1191 called with the prefix argument.
1192 @end deffn
1194 @defvar c-backspace-function
1195 @vindex backspace-function (c-)
1196 @findex backward-delete-char-untabify
1197 Hook that gets called by @code{c-electric-backspace} when it doesn't
1198 do an ``electric'' deletion of the preceding whitespace.  The default
1199 value is @code{backward-delete-char-untabify}.
1200 @end defvar
1202 @deffn Command c-electric-delete-forward
1203 @findex electric-delete-forward (c-)
1204 This function, which is bound to @kbd{C-d} by default, works just like
1205 @code{c-electric-backspace} but in the forward direction.  When it
1206 doesn't do an ``electric'' deletion of the following whitespace, it
1207 calls the function in @code{c-delete-function} with its prefix
1208 argument.
1209 @end deffn
1211 @defvar c-delete-function
1212 @vindex delete-function (c-)
1213 @findex delete-char
1214 Hook that gets called by @code{c-electric-delete-forward} when it
1215 doesn't do an ``electric'' deletion of the following whitespace.  The
1216 default value is @code{delete-char}.
1217 @end defvar
1219 Above we have only talked about the @kbd{DEL} and @kbd{C-d} key events,
1220 without connecting them to the physical keys commonly known as
1221 @key{Backspace} and @key{Delete}.  The default behavior of those two
1222 depends on the flavor of (X)Emacs you are using.
1224 @findex c-electric-delete
1225 @findex electric-delete (c-)
1226 @vindex delete-key-deletes-forward
1228 In XEmacs 20.3 and beyond, the @key{Backspace} key is bound to
1229 @code{c-electric-backspace} and the @key{Delete} key is bound to
1230 @code{c-electric-delete}.  You control the direction it deletes in by
1231 setting the variable @code{delete-key-deletes-forward}, a standard
1232 XEmacs variable.  When this variable is non-@code{nil},
1233 @code{c-electric-delete} will do forward deletion with
1234 @code{c-electric-delete-forward}, otherwise it does backward deletion
1235 with @code{c-electric-backspace}.
1237 In other Emacs versions, @ccmode{} doesn't bind either @key{Backspace}
1238 or @key{Delete}.  In XEmacs 19 and Emacs prior to 21 that means that
1239 it's up to you to fix them.  Emacs 21 automatically binds them as
1240 appropriate to @kbd{DEL} and @kbd{C-d}.
1242 Another way to use hungry deletion is to bind
1243 @code{c-hungry-backspace} and @code{c-hungry-delete-forward} directly
1244 to keys, and not use the mode toggling.  For example @kbd{C-c C-d} and
1245 @kbd{C-c DEL} to match plain @kbd{C-d} and @kbd{DEL},
1247 @example
1248 (add-hook
1249  'c-mode-common-hook
1250  (lambda ()
1251    (define-key c-mode-base-map
1252                [?\C-c ?\d] 'c-hungry-backspace)
1253    (define-key c-mode-base-map
1254                [?\C-c ?\C-d] 'c-hungry-delete-forward)))
1255 @end example
1257 @deffn Command c-hungry-backspace
1258 @findex hungry-backspace (c-)
1259 Delete any amount of whitespace in the backwards direction (regardless
1260 whether hungry-delete mode is enabled or not).
1261 @end deffn
1263 @deffn Command c-hungry-delete-forward
1264 @findex hungry-delete-forward (c-)
1265 Delete any amount of whitespace in the forward direction (regardless
1266 whether hungry-delete mode is enabled or not).
1267 @end deffn
1270 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1271 @node    Text Filling and Line Breaking, Macro Handling, Minor Modes, Top
1272 @comment node-name, next, previous, up
1273 @chapter Text Filling and Line Breaking
1274 @cindex text filling
1275 @cindex line breaking
1276 @cindex comment handling
1277 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1279 Since there's a lot of normal text in comments and string literals,
1280 @ccmode{} provides features to edit these like in text mode.  The goal
1281 is to do it as seamlessly as possible, i.e., you can use auto fill mode,
1282 sentence and paragraph movement, paragraph filling, adaptive filling etc
1283 wherever there's a piece of normal text without having to think much
1284 about it.  @ccmode{} should keep the indentation, fix the comment line
1285 decorations, and so on, for you.  It does that by hooking in on the
1286 different line breaking functions and tuning relevant variables as
1287 necessary.
1289 @vindex c-comment-prefix-regexp
1290 @vindex comment-prefix-regexp (c-)
1291 @cindex comment line prefix
1292 @vindex comment-start
1293 @vindex comment-end
1294 @vindex comment-start-skip
1295 @vindex paragraph-start
1296 @vindex paragraph-separate
1297 @vindex paragraph-ignore-fill-prefix
1298 @vindex adaptive-fill-mode
1299 @vindex adaptive-fill-regexp
1300 @vindex adaptive-fill-first-line-regexp
1301 To make Emacs recognize comments and treat text in them as normal
1302 paragraphs, @ccmode{} makes several standard
1303 variables@footnote{@code{comment-start}, @code{comment-end},
1304 @code{comment-start-skip}, @code{paragraph-start},
1305 @code{paragraph-separate}, @code{paragraph-ignore-fill-prefix},
1306 @code{adaptive-fill-mode}, @code{adaptive-fill-regexp}, and
1307 @code{adaptive-fill-first-line-regexp}.} buffer local and modifies them
1308 according to the language syntax and the comment line prefix.
1310 @defopt c-comment-prefix-regexp
1311 @vindex comment-prefix-regexp (c-)
1312 This style variable contains the regexp used to recognize the
1313 @dfn{comment line prefix}, which is the line decoration that starts
1314 every line in a comment.  The default is @samp{//+\\|\\**}, which
1315 matches C++ style line comments like
1317 @example
1318 // blah blah
1319 @end example
1321 @noindent
1322 with two or more slashes in front of them, and C style block comments
1323 like
1325 @example
1326 @group
1328  * blah blah
1329  */
1330 @end group
1331 @end example
1333 @noindent
1334 with zero or more stars at the beginning of every line.  If you change
1335 this variable, please make sure it still matches the comment starter
1336 (i.e., @code{//}) of line comments @emph{and} the line prefix inside
1337 block comments.
1339 @findex c-setup-paragraph-variables
1340 @findex setup-paragraph-variables (c-)
1341 Also note that since @ccmode{} uses the value of
1342 @code{c-comment-prefix-regexp} to set up several other variables at mode
1343 initialization, there won't be any effect if you just change it inside a
1344 @ccmode{} buffer.  You need to call the command
1345 @code{c-setup-paragraph-variables} too, to update those other variables with
1346 the new value.  That's also the case if you modify this variable in a
1347 mode hook, since @ccmode{} sets up all variables before calling them.
1348 @end defopt
1350 @findex auto-fill-mode
1351 @cindex Auto Fill mode
1352 @cindex paragraph filling
1353 Line breaks are by default handled (almost) the same regardless whether
1354 they are made by auto fill mode (@pxref{Auto Fill,,, emacs, The Emacs
1355 Editor}), paragraph filling (e.g., with @kbd{M-q}), or explicitly with
1356 @kbd{M-j} or similar methods.  In string literals, the new line gets the
1357 same indentation as the previous nonempty line (may be changed with the
1358 @code{string} syntactic symbol).  In comments, @ccmode{} uses
1359 @code{c-comment-prefix-regexp} to adapt the line prefix from the other
1360 lines in the comment.
1362 @vindex adaptive-fill-mode
1363 @cindex Adaptive Fill mode
1364 @ccmode{} uses adaptive fill mode (@pxref{Adaptive Fill,,, emacs, The
1365 Emacs Editor}) to make Emacs correctly keep the line prefix when filling
1366 paragraphs.  That also makes Emacs preserve the text indentation
1367 @emph{inside} the comment line prefix.  e.g., in the following comment,
1368 both paragraphs will be filled with the left margins of the texts kept
1369 intact:
1371 @example
1372 @group
1373 /* Make a balanced b-tree of the nodes in the incoming
1374  * stream.  But, to quote the famous words of Donald E.
1375  * Knuth,
1377  *     Beware of bugs in the above code; I have only
1378  *     proved it correct, not tried it.
1379  */
1380 @end group
1381 @end example
1383 @findex c-setup-filladapt
1384 @findex setup-filladapt (c-)
1385 @findex filladapt-mode
1386 @vindex filladapt-mode
1387 @cindex Filladapt mode
1388 It's also possible to use other adaptive filling packages, notably Kyle
1389 E. Jones' Filladapt package@footnote{It's available from
1390 @uref{http://www.wonderworks.com/}.  As of version 2.12, it does however
1391 lack a feature that makes it work suboptimally when
1392 @code{c-comment-prefix-regexp} matches the empty string (which it does
1393 by default).  A patch for that is available from
1394 @uref{http://cc-mode.sourceforge.net/,, the CC Mode web site}.},
1395 which handles things like bulleted lists nicely.  There's a convenience
1396 function @code{c-setup-filladapt} that tunes the relevant variables in
1397 Filladapt for use in @ccmode{}.  Call it from a mode hook, e.g., with
1398 something like this in your @file{.emacs}:
1400 @example
1401 (defun my-c-mode-common-hook ()
1402   (c-setup-filladapt)
1403   (filladapt-mode 1))
1404 (add-hook 'c-mode-common-hook 'my-c-mode-common-hook)
1405 @end example
1407 @defopt c-block-comment-prefix
1408 @vindex block-comment-prefix (c-)
1409 @vindex c-comment-continuation-stars
1410 @vindex comment-continuation-stars (c-)
1411 Normally the comment line prefix inserted for a new line inside a
1412 comment is deduced from other lines in it.  However there's one
1413 situation when there's no hint about what the prefix should look like,
1414 namely when a block comment is broken for the first time.  This style
1415 variable@footnote{In versions before 5.26, this variable was called
1416 @code{c-comment-continuation-stars}.  As a compatibility measure,
1417 @ccmode{} still uses the value on that variable if it's set.} is used
1418 then as the comment prefix.  It defaults to @samp{*
1419 }@footnote{Actually, this default setting of
1420 @code{c-block-comment-prefix} typically gets overriden by the default
1421 style @code{gnu}, which sets it to blank.  You can see the line
1422 splitting effect described here by setting a different style,
1423 e.g. @code{k&r} @xref{Choosing a Style}}, which makes a comment
1425 @example
1426 /* Got O(n^2) here, which is a Bad Thing. */
1427 @end example
1429 @noindent
1430 break into
1432 @example
1433 @group
1434 /* Got O(n^2) here,
1435  * which is a Bad Thing. */
1436 @end group
1437 @end example
1439 Note that it won't work to adjust the indentation by putting leading
1440 spaces in @code{c-block-comment-prefix}, since @ccmode{} still uses the
1441 normal indentation engine to indent the line.  Thus, the right way to
1442 fix the indentation is by customizing the @code{c} syntactic symbol.  It
1443 defaults to @code{c-lineup-C-comments}, which handles the indentation of
1444 most common comment styles, see @ref{Indentation Functions}.
1445 @end defopt
1447 @defopt c-ignore-auto-fill
1448 @vindex ignore-auto-fill (c-)
1449 When auto fill mode is enabled, @ccmode{} can selectively ignore it
1450 depending on the context the line break would occur in, e.g., to never
1451 break a line automatically inside a string literal.  This variable
1452 takes a list of symbols for the different contexts where auto-filling
1453 never should occur:
1455 @table @code
1456 @item string
1457 Inside a string or character literal.
1458 @item c
1459 Inside a C style block comment.
1460 @item c++
1461 Inside a C++ style line comment.
1462 @item cpp
1463 Inside a preprocessor directive.
1464 @item code
1465 Anywhere else, i.e., in normal code.
1466 @end table
1468 By default, @code{c-ignore-auto-fill} is set to @code{'(string cpp
1469 code)}, which means that auto-filling only occurs in comments when
1470 auto-fill mode is activated.  In literals, it's often desirable to have
1471 explicit control over newlines.  In preprocessor directives, the
1472 necessary @samp{\} escape character before the newline is not
1473 automatically inserted, so an automatic line break would produce invalid
1474 code.  In normal code, line breaks are normally dictated by some logical
1475 structure in the code rather than the last whitespace character, so
1476 automatic line breaks there will produce poor results in the current
1477 implementation.
1478 @end defopt
1480 The commands that do the actual work follow.
1482 @table @asis
1483 @item @kbd{M-q} (@code{c-fill-paragraph})
1484 @kindex M-q
1485 @findex c-fill-paragraph
1486 @findex fill-paragraph (c-)
1487 @cindex Javadoc markup
1488 @cindex Pike autodoc markup
1489 This is the replacement for @code{fill-paragraph} in @ccmode{}
1490 buffers. It's used to fill multiline string literals and both block and
1491 line style comments.  In Java buffers, the Javadoc markup words are
1492 recognized as paragraph starters.  The line oriented Pike autodoc markup
1493 words are recognized in the same way in Pike mode.
1495 The function keeps the comment starters and enders of block comments as
1496 they were before the filling.  This means that a comment ender on the
1497 same line as the paragraph being filled will be filled with the
1498 paragraph, and one on a line by itself will stay as it is.  The comment
1499 starter is handled similarly@footnote{This means that the variables
1500 @code{c-hanging-comment-starter-p} and @code{c-hanging-comment-ender-p},
1501 which controlled this behavior in earlier versions of @ccmode{}, are now
1502 obsolete.}.
1504 @item @kbd{M-j} (@code{c-indent-new-comment-line})
1505 @kindex M-j
1506 @findex c-indent-new-comment-line
1507 @findex indent-new-comment-line (c-)
1508 This is the replacement for @code{indent-new-comment-line}.  It breaks
1509 the line at point and indents the new line like the current one.
1511 @vindex comment-multi-line
1512 If inside a comment and @code{comment-multi-line} is non-@code{nil}, the
1513 indentation and line prefix are preserved.  If inside a comment and
1514 @code{comment-multi-line} is @code{nil}, a new comment of the same type
1515 is started on the next line and indented as appropriate for comments.
1517 Note that @ccmode{} sets @code{comment-multi-line} to @code{t} at
1518 startup.  The reason is that @kbd{M-j} could otherwise produce sequences
1519 of single line block comments for texts that should logically be treated
1520 as one comment, and the rest of the paragraph handling code
1521 (e.g., @kbd{M-q} and @kbd{M-a}) can't cope with that, which would lead to
1522 inconsistent behavior.
1524 @item @kbd{M-x c-context-line-break}
1525 @findex c-context-line-break
1526 @findex context-line-break (c-)
1527 This is a function that works like @code{indent-new-comment-line} in
1528 comments and @code{newline-and-indent} elsewhere, thus combining those
1529 two in a way that uses each one in the context it's best suited for.
1530 I.e., in comments the comment line prefix and indentation is kept for
1531 the new line, and in normal code it's indented according to context by
1532 the indentation engine.
1534 In macros it acts like @code{newline-and-indent} but additionally
1535 inserts and optionally aligns the line ending backslash so that the
1536 macro remains unbroken.  @xref{Macro Handling}, for details about the
1537 backslash alignment.
1539 It's not bound to a key by default, but it's intended to be used on the
1540 @kbd{RET} key.  If you like the behavior of @code{newline-and-indent} on
1541 @kbd{RET}, you should consider switching to this function.
1543 @item @kbd{M-x c-context-open-line}
1544 @findex c-context-open-line
1545 @findex context-open-line (c-)
1546 This is to @kbd{C-o} (@kbd{M-x open-line}) as
1547 @code{c-context-line-break} is to @kbd{RET}.  I.e., it works just like
1548 @code{c-context-line-break} but leaves the point before the inserted
1549 line break.
1550 @end table
1553 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1554 @node    Macro Handling, Font Locking, Text Filling and Line Breaking, Top
1555 @comment node-name, next, previous, up
1556 @chapter Macro Handling
1557 @cindex macros
1558 @cindex preprocessor directives
1559 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1561 Preprocessor directives are handled as syntactic whitespace from other
1562 code, i.e., they can be interspersed anywhere without affecting the
1563 syntactic analysis, just like comments.
1565 The code inside macro definitions is still analyzed syntactically so
1566 that you get relative indentation there just as you'd get if the same
1567 code was outside a macro.  However, since there is no hint about the
1568 syntactic context, i.e., whether the macro expands to an expression, to some
1569 statements, or perhaps to whole functions, the syntactic recognition can be
1570 wrong.  @ccmode{} manages to figure it out correctly most of the time,
1571 though.  @xref{Syntactic Symbols}, for details about the indentation.
1573 @defopt c-syntactic-indentation-in-macros
1574 @vindex syntactic-indentation-in-macros (c-)
1575 Enable syntactic analysis inside macros, which is the default.  If this
1576 is @code{nil}, all lines inside macro definitions are analyzed as
1577 @code{cpp-macro-cont}.
1578 @end defopt
1580 @ccmode{} provides some tools to help keep the line continuation
1581 backslashes in macros neat and tidy:
1583 @table @asis
1584 @item @kbd{C-c C-\} (@code{c-backslash-region})
1585 @kindex C-c C-\
1586 @findex c-backslash-region
1587 @findex backslash-region (c-)
1588 This function inserts and aligns or deletes the end-of-line backslashes
1589 in the current region.
1591 With no prefix argument, it inserts any missing backslashes and aligns
1592 them according to the @code{c-backslash-column} and
1593 @code{c-backslash-max-column} variables.  With a prefix argument, it
1594 deletes any backslashes.
1596 The function does not modify blank lines at the start of the region.  If
1597 the region ends at the start of a line, it always deletes the backslash
1598 (if any) at the end of the previous line.
1599 @end table
1601 @defopt c-backslash-column
1602 @vindex backslash-column (c-)
1603 @defoptx c-backslash-max-column
1604 @vindex backslash-max-column (c-)
1605 These variables control the alignment columns for line continuation
1606 backslashes in multiline macros.  They are used by the functions that
1607 automatically insert or align such backslashes,
1608 e.g., @code{c-backslash-region} and @code{c-context-line-break}.
1610 @code{c-backslash-column} specifies the minimum column for the
1611 backslashes.  If any line in the macro exceeds it then the next tab
1612 stop from that line is used as the alignment column for all the
1613 backslashes, so that they remain in a single column.  However, if some
1614 lines exceed @code{c-backslash-max-column} then the backslashes in the
1615 rest of the macro will be kept at that column, so that the
1616 lines which are too long ``stick out'' instead.
1617 @end defopt
1619 @defopt c-auto-align-backslashes
1620 @vindex auto-align-backslashes (c-)
1621 Align automatically inserted line continuation backslashes if
1622 non-@code{nil}.  When line continuation backslashes are inserted
1623 automatically for line breaks in multiline macros, e.g., by
1624 @code{c-context-line-break}, they are aligned with the other backslashes
1625 in the same macro if this flag is set.  Otherwise the inserted
1626 backslashes are preceded by a single space.
1627 @end defopt
1629 The recommended line breaking function, @code{c-context-line-break}
1630 (@pxref{Text Filling and Line Breaking}), is especially nice if you edit
1631 multiline macros frequently.  When used inside a macro, it automatically
1632 inserts and adjusts the mandatory backslash at the end of the line to
1633 keep the macro together, and it leaves the point at the right
1634 indentation column for the code.  Thus you can write code inside macros
1635 almost exactly as you can elsewhere, without having to bother with the
1636 trailing backslashes.
1639 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1640 @node    Font Locking, Commands, Macro Handling, Top
1641 @comment node-name, next, previous, up
1642 @chapter Font Locking
1643 @cindex font locking
1644 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1646 @strong{Note:} The font locking in AWK mode is currently not integrated
1647 with the rest of @ccmode{}, so this section does not apply there.
1648 @xref{AWK Mode Font Locking}, instead.
1650 @cindex Font Lock mode
1652 @ccmode{} provides font locking for its supported languages by supplying
1653 patterns for use with Font Lock mode.  This means that you get distinct
1654 faces on the various syntactic parts such as comments, strings, keywords
1655 and types, which is very helpful in telling them apart at a glance and
1656 discovering syntactic errors.  @xref{Font Lock,,, emacs, The Emacs
1657 Editor}, for ways to enable font locking in @ccmode{} buffers.
1659 @menu
1660 * Font Locking Preliminaries::
1661 * Faces::
1662 * Documentation Comments::
1663 @end menu
1666 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1667 @node    Font Locking Preliminaries, Faces, , Font Locking
1668 @comment node-name, next, previous, up
1669 @section Font Locking Preliminaries
1670 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1672 The font locking for most of the @ccmode{} languages were provided
1673 directly by the Font Lock package prior to version 5.30 of @ccmode{}.
1674 In the transition to @ccmode{} the patterns have been reworked
1675 completely and are applied uniformly across all the languages except AWK
1676 mode, just like the indentation rules (although each language still has
1677 some pecularities of its own, of course).  Since the languages
1678 previously had completely separate font locking patterns, this means
1679 that it's a bit different in most languages now.
1681 The main goal for the font locking in @ccmode{} is accuracy, to provide
1682 a dependable aid in recognizing the various constructs.  Some, like
1683 strings and comments, are easy to recognize while others like
1684 declarations and types can be very tricky.  @ccmode{} can go to great
1685 lengths to recognize declarations and casts correctly, especially when
1686 the types aren't recognized by standard patterns.  This is a fairly
1687 demanding analysis which can be slow on older hardware, and it can
1688 therefore be disabled by choosing a lower decoration level with the
1689 variable @code{font-lock-maximum-decoration}.
1691 @vindex font-lock-maximum-decoration
1693 The decoration levels are used as follows:
1695 @enumerate
1696 @comment 1
1697 @item
1698 Minimal font locking: Fontify only comments, strings and preprocessor
1699 directives (in the languages that use cpp).
1701 @comment 2
1702 @item
1703 Fast normal font locking: In addition to level 1, fontify keywords,
1704 simple types and declarations that are easy to recognize.  The variables
1705 @code{*-font-lock-extra-types} (where @samp{*} is the name of the
1706 language) are used to recognize types (see below).  Documentation
1707 comments like Javadoc are fontified according to
1708 @code{c-doc-comment-style} (@pxref{Documentation Comments}).
1710 Use this if you think the font locking is too slow.  It's the closest
1711 corresponding level to level 3 in the old font lock patterns.
1713 @comment 3
1714 @item
1715 Accurate normal font locking: Like level 2 but uses a different approach
1716 that can recognize types and declarations much more accurately.  The
1717 @code{*-font-lock-extra-types} variables are still used, but user
1718 defined types are recognized correctly anyway in most cases.  Therefore
1719 those variables should be fairly restrictive and not contain patterns
1720 that are uncertain.
1722 @cindex Lazy Lock mode
1723 @cindex Just-in-time Lock mode
1725 This level is designed for fairly modern hardware and a font lock
1726 support mode like Lazy Lock or Just-in-time Lock mode that only
1727 fontifies the parts that are actually shown.
1728 @end enumerate
1730 @cindex user defined types
1731 @cindex types, user defined
1733 Since user defined types are hard to recognize you can provide
1734 additional regexps to match those you use:
1736 @defopt c-font-lock-extra-types
1737 @defoptx c++-font-lock-extra-types
1738 @defoptx objc-font-lock-extra-types
1739 @defoptx java-font-lock-extra-types
1740 @defoptx idl-font-lock-extra-types
1741 @defoptx pike-font-lock-extra-types
1742 For each language there's a variable @code{*-font-lock-extra-types},
1743 where @samp{*} stands for the language in question.  It contains a list
1744 of regexps that matches identifiers that should be recognized as types,
1745 e.g., @samp{\\sw+_t} to recognize all identifiers ending with @samp{_t}
1746 as is customary in C code.  Each regexp should not match more than a
1747 single identifier.
1749 The default values contain regexps for many types in standard runtime
1750 libraries that are otherwise difficult to recognize, and patterns for
1751 standard type naming conventions like the @samp{_t} suffix in C and C++.
1752 Java, Objective-C and Pike have as a convention to start class names
1753 with capitals, so there are patterns for that in those languages.
1755 Despite the names of these variables, they are not only used for
1756 fontification but in other places as well where @ccmode{} needs to
1757 recognize types.
1758 @end defopt
1761 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1762 @node    Faces, Documentation Comments, Font Locking Preliminaries, Font Locking
1763 @comment node-name, next, previous, up
1764 @section Faces
1765 @cindex faces
1766 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1768 @ccmode{} attempts to use the standard faces for programming languages
1769 in accordance with their intended purposes as far as possible.  No extra
1770 faces are currently provided, with the exception of a replacement face
1771 @code{c-invalid-face} for emacsen that don't provide
1772 @code{font-lock-warning-face}.
1774 @itemize @bullet
1775 @item
1776 @vindex font-lock-comment-face
1777 Normal comments are fontified in @code{font-lock-comment-face}.
1779 @item
1780 @vindex font-lock-doc-face
1781 @vindex font-lock-doc-string-face
1782 @vindex font-lock-comment-face
1783 Comments that are recognized as documentation (@pxref{Documentation
1784 Comments}) get @code{font-lock-doc-face} (Emacs) or
1785 @code{font-lock-doc-string-face} (XEmacs) if those faces exist.  If they
1786 don't then @code{font-lock-comment-face} is used.
1788 @item
1789 @vindex font-lock-string-face
1790 String and character literals are fontified in
1791 @code{font-lock-string-face}.
1793 @item
1794 @vindex font-lock-keyword-face
1795 Keywords are fontified with @code{font-lock-keyword-face}.
1797 @item
1798 @vindex font-lock-function-name-face
1799 @code{font-lock-function-name-face} is used for function names in
1800 declarations and definitions, and classes in those contexts.  It's also
1801 used for preprocessor defines with arguments.
1803 @item
1804 @vindex font-lock-variable-name-face
1805 Variables in declarations and definitions, and other identifiers in such
1806 variable contexts, get @code{font-lock-variable-name-face}.  It's also
1807 used for preprocessor defines without arguments.
1809 @item
1810 @vindex font-lock-constant-face
1811 @vindex font-lock-reference-face
1812 Builtin constants are fontified in @code{font-lock-constant-face} if it
1813 exists, @code{font-lock-reference-face} otherwise.  As opposed to the
1814 preceding two faces, this is used on the names in expressions, and it's
1815 not used in declarations, even if there happen to be a @samp{const} in
1816 them somewhere.
1818 @item
1819 @vindex font-lock-type-face
1820 @code{font-lock-type-face} is put on types (both predefined and user
1821 defined) and classes in type contexts.
1823 @item
1824 @vindex font-lock-constant-face
1825 @vindex font-lock-reference-face
1826 Label identifiers get @code{font-lock-constant-face} if it exists,
1827 @code{font-lock-reference-face} otherwise.
1829 @item
1830 Name qualifiers and identifiers for scope constructs are fontified like
1831 labels.
1833 @item
1834 Special markup inside documentation comments are also fontified like
1835 labels.
1837 @item
1838 @vindex font-lock-preprocessor-face
1839 @vindex font-lock-builtin-face
1840 @vindex font-lock-reference-face
1841 Preprocessor directives get @code{font-lock-preprocessor-face} if it
1842 exists (i.e., XEmacs).  In Emacs they get @code{font-lock-builtin-face}
1843 or @code{font-lock-reference-face}, for lack of a closer equivalent.
1845 @item
1846 @vindex font-lock-warning-face
1847 @vindex c-invalid-face
1848 @vindex invalid-face (c-)
1849 Some kinds of syntactic errors are fontified with
1850 @code{font-lock-warning-face} in Emacs.  In older XEmacs versions
1851 there's no corresponding standard face, so there a special
1852 @code{c-invalid-face} is used, which is defined to stand out sharply by
1853 default.
1855 Note that it's not used for @samp{#error} or @samp{#warning} directives,
1856 since those aren't syntactic errors in themselves.
1857 @end itemize
1860 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1861 @node    Documentation Comments, , Faces, Font Locking
1862 @comment node-name, next, previous, up
1863 @section Documentation Comments
1864 @cindex documentation comments
1865 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1867 There are various tools to supply documentation in the source as
1868 specially structured comments, e.g., the standard Javadoc tool in Java.
1869 @ccmode{} provides an extensible mechanism to fontify such comments and
1870 the special markup inside them.
1872 @defopt c-doc-comment-style
1873 @vindex doc-comment-style (c-)
1874 This is a style variable that specifies which documentation comment
1875 style to recognize, e.g., @code{javadoc} for Javadoc comments.
1877 The value may also be a list of styles, in which case all of them are
1878 recognized simultaneously (presumably with markup cues that don't
1879 conflict).
1881 The value may also be an association list to specify different comment
1882 styles for different languages.  The symbol for the major mode is then
1883 looked up in the alist, and the value of that element is interpreted as
1884 above if found.  If it isn't found then the symbol `other' is looked up
1885 and its value is used instead.
1887 Note that @ccmode{} uses this variable to set other variables that
1888 handle fontification etc.  That's done at mode initialization or when
1889 you switch to a style which sets this variable.  Thus, if you change it
1890 in some other way, e.g., interactively in a CC Mode buffer, you will need
1891 to do @kbd{M-x java-mode} (or whatever mode you're currently using) to
1892 reinitialize.
1894 @findex c-setup-doc-comment-style
1895 @findex setup-doc-comment-style (c-)
1896 Note also that when @ccmode{} starts up, the other variables are
1897 modified before the mode hooks are run.  If you change this variable in
1898 a mode hook, you have to call @code{c-setup-doc-comment-style}
1899 afterwards to redo that work.
1900 @end defopt
1902 @ccmode{} currently provides handing of the following doc comment
1903 styles:
1905 @table @code
1906 @item javadoc
1907 @cindex Javadoc markup
1908 Javadoc comments, the standard tool in Java.
1910 @item autodoc
1911 @cindex Pike autodoc markup
1912 For Pike autodoc markup, the standard in Pike.
1913 @end table
1915 The above is by no means complete.  If you'd like to see support for
1916 other doc comment styles, please let us know (@pxref{Mailing Lists and
1917 Submitting Bug Reports}).
1919 You can also write your own doc comment fontification support to use
1920 with @code{c-doc-comment-style}: Supply a variable or function
1921 @code{*-font-lock-keywords} where @samp{*} is the name you want to use
1922 in @code{c-doc-comment-style}.  If it's a variable, it's prepended to
1923 @code{font-lock-keywords}.  If it's a function, it's called at mode
1924 initialization and the result is prepended.  For an example, see
1925 @code{javadoc-font-lock-keywords} in @file{cc-fonts.el}.
1927 If you add support for another doc comment style, please consider
1928 contributing it --- send a note to @email{bug-cc-mode@@gnu.org}.
1931 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1932 @node    Commands, Customizing Indentation, Font Locking, Top
1933 @comment node-name, next, previous, up
1934 @chapter Commands
1935 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1937 @menu
1938 * Indentation Commands::
1939 * Movement Commands::
1940 * Other Commands::
1941 @end menu
1943 See also @ref{Text Filling and Line Breaking} and @ref{Macro Handling},
1944 for commands concerning those bits.
1947 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1948 @node    Indentation Commands, Movement Commands, , Commands
1949 @comment node-name, next, previous,up
1950 @section Indentation Commands
1951 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1953 The following list of commands reindent C constructs.  Note that when
1954 you change your coding style, either interactively or through some other 
1955 means, your file does @emph{not} automatically get reindented.  You
1956 will need to execute one of the following commands to see the effects of 
1957 your changes.
1959 @cindex GNU indent program
1960 Also, variables like @code{c-hanging-*} and @code{c-cleanup-list}
1961 only affect how on-the-fly code is formatted.  Changing the
1962 ``hanginess'' of a brace and then reindenting, will not move the brace
1963 to a different line.  For this, you're better off getting an external
1964 program like GNU @code{indent}, which will rearrange brace location,
1965 among other things.
1967 Reindenting large sections of code can take a long time.  When
1968 @ccmode{} reindents a region of code, it is essentially equivalent to
1969 hitting @kbd{TAB} on every line of the region.
1971 These commands are useful when indenting code:
1973 @table @asis
1974 @item @kbd{TAB} (@code{c-indent-command})
1975 @kindex TAB
1976 @findex c-indent-command
1977 @findex indent-command (c-)
1978 Indents the current line.  The actual behavior is controlled by several
1979 variables, described below.  See @code{c-tab-always-indent},
1980 @code{c-insert-tab-function}, and @code{indent-tabs-mode}.  With a
1981 numeric argument, this command rigidly indents the region, preserving
1982 the relative indentation among the lines.
1984 @item @kbd{C-M-q} (@code{c-indent-exp})
1985 @kindex C-M-q
1986 @findex c-indent-exp
1987 @findex indent-exp (c-)
1988 Indent an entire balanced brace or parenthesis expression.  Note that
1989 point must be on the opening brace or parenthesis of the expression you
1990 want to indent.
1992 @item @kbd{C-c C-q} (@code{c-indent-defun})
1993 @kindex C-c C-q
1994 @findex c-indent-defun
1995 @findex indent-defun (c-)
1996 Indents the entire top-level function, class or macro definition
1997 encompassing point.  It leaves point unchanged.  This function can't be
1998 used to reindent a nested brace construct, such as a nested class or
1999 function, or a Java method.  The top-level construct being reindented
2000 must be complete, i.e., it must have both a beginning brace and an ending
2001 brace.
2003 @item @kbd{C-M-\} (@code{indent-region})
2004 @kindex C-M-\
2005 @findex indent-region
2006 Indents an arbitrary region of code.  This is a standard Emacs command,
2007 tailored for C code in a @ccmode{} buffer.  Note, of course, that point
2008 and mark must delineate the region you want to indent.
2010 @item @kbd{M-;} (@code{indent-for-comment})
2011 @kindex M-;
2012 @findex indent-for-comment
2013 Insert a comment at the end of the current line, if none is there already.
2014 Then reindent the comment according to the variables
2015 @code{c-indent-comment-alist}, @code{c-indent-comments-syntactically-p}
2016 and @code{comment-column}.  Then position the point after the comment
2017 starter.  This is a standard Emacs command, but @ccmode{} enhances it a
2018 bit with two variables:
2020 @defopt c-indent-comment-alist
2021 @vindex indent-comment-alist (c-)
2022 @vindex comment-column
2023 This style variable allows you to control which column @kbd{M-;}
2024 indents the comment to, depending on the preceding code and the
2025 indentation of a similar comment on the preceding line, if there is
2026 any.  It is an association list that maps different types of lines to
2027 actions describing how they should be handled.  If a certain line type
2028 isn't present on the list then the line is indented to the column
2029 specified by @code{comment-column}.  See the documentation string for
2030 @code{c-indent-comment-alist} for a full description of the available
2031 line types and actions (use @kbd{C-h v c-indent-comment-alist}).
2032 @end defopt
2034 @defopt c-indent-comments-syntactically-p
2035 @vindex indent-comments-syntactically-p (c-)
2036 Normally, when this variable is @code{nil}, @kbd{M-;} will indent
2037 comment-only lines according to @code{c-indent-comment-alist}, just as
2038 it does with lines where other code precede the comments.  However, if
2039 you want it to act just like @kbd{TAB} for comment-only lines you can
2040 get that by setting @code{c-indent-comments-syntactically-p} to
2041 non-@code{nil}.
2043 If @code{c-indent-comments-syntactically-p} is non-@code{nil} then
2044 @code{c-indent-comment-alist} won't be consulted at all for comment-only
2045 lines.
2046 @end defopt
2048 @item @kbd{C-M-h} (@code{c-mark-function})
2049 @kindex C-M-h
2050 @findex c-mark-function
2051 @findex mark-function (c-)
2052 While not strictly an indentation command, this is useful for marking
2053 the current top-level function or class definition as the current
2054 region.  As with @code{c-indent-defun}, this command operates on
2055 top-level constructs, and can't be used to mark say, a Java method.
2056 @end table
2058 These variables are also useful when indenting code:
2060 @defopt c-tab-always-indent
2061 @vindex tab-always-indent (c-)
2062 @kindex TAB
2063 @cindex literal
2064 This variable controls how @kbd{TAB} (@code{c-indent-command})
2065 operates.  When it is @code{t}, @kbd{TAB} always indents the current
2066 line.  When it is @code{nil}, the line is indented only if point is at
2067 the left margin, or on or before the first non-whitespace character on
2068 the line, otherwise some whitespace is inserted.  If this variable is
2069 some other value (not @code{nil} or @code{t}), then some whitespace is
2070 inserted only within strings and comments (literals), but the line is
2071 always reindented.
2072 @end defopt
2074 @defopt c-insert-tab-function
2075 @vindex insert-tab-function (c-)
2076 @findex tab-to-tab-stop
2077 When ``some whitespace'' is inserted as described above, what actually
2078 happens is that the function stored in @code{c-insert-tab-function} is
2079 called.  Normally, this just inserts a real tab character, or the
2080 equivalent number of spaces, depending on @code{indent-tabs-mode}.
2081 Some people, however, set @code{c-insert-tab-function} to
2082 @code{tab-to-tab-stop} so as to get hard tab stops when indenting.
2083 @end defopt
2085 @defopt indent-tabs-mode
2086 This is a standard Emacs variable that controls how line indentation
2087 is composed.  When it's non-@code{nil}, tabs can be used in a line's
2088 indentation, otherwise only spaces can be used.
2089 @end defopt
2091 @defopt c-progress-interval
2092 @vindex progress-interval (c-)
2093 When indenting large regions of code, this variable controls how often a
2094 progress message is displayed.  Set this variable to @code{nil} to
2095 inhibit the progress messages, or set it to an integer which is how
2096 often (in seconds) progress messages are to be displayed.
2097 @end defopt
2100 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2101 @node    Movement Commands, Other Commands, Indentation Commands, Commands
2102 @comment node-name, next, previous, up
2103 @section Movement Commands
2104 @cindex movement
2105 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2107 @ccmode{} contains some useful commands for moving around in C
2108 code.
2110 @table @asis
2111 @item @kbd{M-x c-beginning-of-defun}
2112 @findex c-beginning-of-defun
2113 @findex beginning-of-defun (c-)
2114 @findex beginning-of-defun
2115 Move point back to the least-enclosing brace.  This function is
2116 analogous to the Emacs built-in command @code{beginning-of-defun},
2117 except it eliminates the constraint that the top-level opening brace
2118 must be in column zero.  See @code{beginning-of-defun} for more
2119 information.
2121 Depending on the coding style being used, you might prefer
2122 @code{c-beginning-of-defun} to @code{beginning-of-defun}.  If so,
2123 consider binding @kbd{C-M-a} to the former instead.  For backwards
2124 compatibility reasons, the default binding remains in effect.
2126 In AWK mode, a defun doesn't necessarily have braces at all.  AWK Mode
2127 therefore has its own version of this function which is bound by
2128 default to @kbd{C-M-a}.  You can thus chose freely which function to
2129 bind to @kbd{C-M-a} for the other modes without worrying about AWK
2130 buffers.  @xref{AWK Mode Defuns}.
2132 @item @kbd{M-x c-end-of-defun}
2133 @findex c-end-of-defun
2134 @findex end-of-defun (c-)
2135 @findex end-of-defun
2136 Moves point to the end of the current top-level definition.  This
2137 function is analogous to the Emacs built-in command @code{end-of-defun},
2138 except it eliminates the constraint that the top-level opening brace of
2139 the defun must be in column zero.  See @code{end-of-defun} for more
2140 information.
2142 Depending on the coding style being used, you might prefer
2143 @code{c-end-of-defun} to @code{end-of-defun}.  If so,
2144 consider binding @kbd{C-M-e} to the former instead.  For backwards
2145 compatibility reasons, the default binding remains in effect.
2147 In AWK Mode, a defun doesn't necessarily have braces at all.  AWK Mode
2148 therefore has its own version of this function which is bound by
2149 default to @kbd{C-M-e}.  You can thus chose freely which function to
2150 bind to @kbd{C-M-e} for the other modes without worrying about AWK
2151 buffers.  @ref{AWK Mode Defuns}.
2153 @item @kbd{C-c C-u} (@code{c-up-conditional})
2154 @kindex C-c C-u
2155 @findex c-up-conditional
2156 @findex up-conditional (c-)
2157 Move point back to the containing preprocessor conditional, leaving the
2158 mark behind.  A prefix argument acts as a repeat count.  With a negative
2159 argument, move point forward to the end of the containing
2160 preprocessor conditional.
2162 @samp{#elif} is treated like @samp{#else} followed by @samp{#if}, so the
2163 function stops at them when going backward, but not when going forward.
2165 @item @kbd{M-x c-up-conditional-with-else}
2166 @findex c-up-conditional-with-else
2167 @findex up-conditional-with-else (c-)
2168 A variety of @code{c-up-conditional} that also stops at @samp{#else}
2169 lines.  Normally those lines are ignored.
2171 @item @kbd{M-x c-down-conditional}
2172 @findex c-down-conditional
2173 @findex down-conditional (c-)
2174 Move point forward into the next nested preprocessor conditional,
2175 leaving the mark behind.  A prefix argument acts as a repeat count.
2176 With a negative argument, move point backward into the previous
2177 nested preprocessor conditional.
2179 @samp{#elif} is treated like @samp{#else} followed by @samp{#if}, so the
2180 function stops at them when going forward, but not when going backward.
2182 @item @kbd{M-x c-down-conditional-with-else}
2183 @findex c-down-conditional-with-else
2184 @findex down-conditional-with-else (c-)
2185 A variety of @code{c-down-conditional} that also stops at @samp{#else}
2186 lines.  Normally those lines are ignored.
2188 @item @kbd{C-c C-p} (@code{c-backward-conditional})
2189 @kindex C-c C-p
2190 @findex c-backward-conditional
2191 @findex backward-conditional (c-)
2192 Move point back over a preprocessor conditional, leaving the mark
2193 behind.  A prefix argument acts as a repeat count.  With a negative
2194 argument, move forward.
2196 @item @kbd{C-c C-n} (@code{c-forward-conditional})
2197 @kindex C-c C-n
2198 @findex c-forward-conditional
2199 @findex forward-conditional (c-)
2200 Move point forward across a preprocessor conditional, leaving the mark
2201 behind.  A prefix argument acts as a repeat count.  With a negative
2202 argument, move backward.
2204 @item @kbd{M-a} (@code{c-beginning-of-statement})
2205 @kindex M-a
2206 @findex c-beginning-of-statement
2207 @findex beginning-of-statement (c-)
2208 Move point to the beginning of the innermost C statement.  If point is
2209 already at the beginning of a statement, move to the beginning of the
2210 closest preceding statement, even if that means moving into a block (you
2211 can use @kbd{C-M-b} to move over a balanced block).  With prefix
2212 argument @var{n}, move back @var{n} @minus{} 1 statements.
2214 If point is within or next to a comment or a string which spans more
2215 than one line, this command moves by sentences instead of statements.
2217 When called from a program, this function takes three optional
2218 arguments: the repetition count, a buffer position limit which is the
2219 farthest back to search for the syntactic context, and a flag saying
2220 whether to do sentence motion in or near comments and multiline strings.
2222 @item @kbd{M-e} (@code{c-end-of-statement})
2223 @kindex M-e
2224 @findex c-end-of-statement
2225 @findex end-of-statement (c-)
2226 Move point to the end of the innermost C statement.  If point is at the
2227 end of a statement, move to the end of the next statement, even if it's
2228 inside a nested block (use @kbd{C-M-f} to move to the other side of the
2229 block).  With prefix argument @var{n}, move forward @var{n} @minus{} 1
2230 statements.
2232 If point is within or next to a comment or a string which spans more
2233 than one line, this command moves by sentences instead of statements.
2235 When called from a program, this function takes three optional
2236 arguments: the repetition count, a buffer position limit which is the
2237 farthest back to search for the syntactic context, and a flag saying
2238 whether to do sentence motion in or near comments and multiline strings.
2240 @item @kbd{M-x c-forward-into-nomenclature}
2241 @findex c-forward-into-nomenclature
2242 @findex forward-into-nomenclature (c-)
2243 A popular programming style, especially for object-oriented languages
2244 such as C++ is to write symbols in a mixed case format, where the first
2245 letter of each word is capitalized, and not separated by underscores.
2246 e.g., @samp{SymbolsWithMixedCaseAndNoUnderlines}.
2248 This command moves point forward to next capitalized word.  With prefix
2249 argument @var{n}, move @var{n} times.
2251 @item @kbd{M-x c-backward-into-nomenclature}
2252 @findex c-backward-into-nomenclature
2253 @findex backward-into-nomenclature (c-)
2254 Move point backward to beginning of the next capitalized
2255 word.  With prefix argument @var{n}, move @var{n} times.  If
2256 @var{n} is negative, move forward.
2257 @end table
2260 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2261 @node    Other Commands, , Movement Commands, Commands
2262 @comment node-name, next, previous, up
2263 @section Other Commands
2264 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2266 Here are the various other commands that didn't fit anywhere else:
2268 @table @asis
2269 @item @kbd{C-c :} (@code{c-scope-operator})
2270 @kindex C-c :
2271 @findex c-scope-operator
2272 @findex scope-operator (c-)
2273 In C++, it is also sometimes desirable to insert the double-colon scope
2274 operator without performing the electric behavior of colon insertion.
2275 @kbd{C-c :} does just this.
2276 @end table
2278 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2279 @node    Customizing Indentation, Syntactic Symbols, Commands, Top
2280 @comment node-name, next, previous, up
2281 @chapter Customizing Indentation
2282 @cindex customization, indentation
2283 @cindex indentation
2284 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2286 The context sensitive indentation is mainly controlled by the variable
2287 @code{c-offsets-alist}:
2289 @defopt c-offsets-alist
2290 @vindex offsets-alist (c-)
2291 This special style variable contains the mappings between syntactic
2292 symbols and the offsets to apply for those symbols.  It's set at mode
2293 initialization from a @emph{style} you may specify.  Styles are
2294 groupings of syntactic symbol offsets and other style variable values.
2295 Most likely, you'll find that one of the predefined styles will suit
2296 your needs.  @xref{Styles}, for an explanation of how to set up named
2297 styles.
2299 Only syntactic symbols not already bound on @code{c-offsets-alist} will
2300 be set from styles.  This means that any association you set on it, be
2301 it before or after mode initialization, will not be changed.  The
2302 @code{c-offsets-alist} variable may therefore be used from e.g., the
2303 Customization interface@footnote{Available in Emacs 20 and later, and
2304 XEmacs 19.15 and later.} to easily change indentation offsets without
2305 having to bother about styles.  Initially @code{c-offsets-alist} is
2306 empty, so that all syntactic symbols are set by the style system.
2308 The offset associated with any particular syntactic symbol can be an
2309 integer, a function or lambda expression, a variable name, a vector, a
2310 list, or one of the following special symbols: @code{+}, @code{-},
2311 @code{++}, @code{--}, @code{*}, or @code{/}.  The meaning of these
2312 values are described in detail below.
2313 @end defopt
2315 The special symbols describe an offset in multiples of the value of
2316 @code{c-basic-offset}:
2318 @defopt c-basic-offset
2319 @vindex basic-offset (c-)
2320 Style variable that holds the basic offset between indentation levels.
2321 @end defopt
2323 By defining a style's indentation in terms of @code{c-basic-offset},
2324 you can change the amount of whitespace given to an indentation level
2325 while maintaining the same basic shape of your code.  Here are the
2326 values that the special symbols correspond to:
2328 @table @code
2329 @item +
2330 @code{c-basic-offset} times 1
2331 @item -
2332 @code{c-basic-offset} times -1
2333 @item ++
2334 @code{c-basic-offset} times 2
2335 @item --
2336 @code{c-basic-offset} times -2
2337 @item *
2338 @code{c-basic-offset} times 0.5
2339 @item /
2340 @code{c-basic-offset} times -0.5
2341 @end table
2343 @cindex indentation functions
2345 When a function is used as offset, it's called an @dfn{indentation
2346 function}.  Such functions are useful when more context than just the
2347 syntactic symbol is needed to get the desired indentation.
2348 @xref{Indentation Functions}, and @ref{Custom Indentation Functions},
2349 for details about them.
2351 If the offset is a vector, its first element sets the absolute
2352 indentation column, which will override any previous relative
2353 indentation.  It won't override additional relative indentation for
2354 nested constructs, though.
2356 @vindex c-strict-syntax-p
2357 @vindex strict-syntax-p (c-)
2358 The offset can also be a list, in which case it is evaluated recursively
2359 using the semantics described above.  The first element of the list that
2360 returns a non-@code{nil} value succeeds and the evaluation stops.  If
2361 none of the list elements return a non-@code{nil} value, then an offset
2362 of 0 (zero) is used@footnote{There is however a variable
2363 @code{c-strict-syntax-p} that, when set to non-@code{nil}, will cause an
2364 error to be signalled in that case.  It's now considered obsolete since
2365 it doesn't work well with some of the alignment functions that now
2366 returns @code{nil} instead of zero to be more usable in lists.  You
2367 should therefore leave @code{c-strict-syntax-p} set to @code{nil}.}.
2369 So, for example, because most of the default offsets are defined in
2370 terms of @code{+}, @code{-}, and @code{0}, if you like the general
2371 indentation style, but you use 4 spaces instead of 2 spaces per level,
2372 you can probably achieve your style just by changing
2373 @code{c-basic-offset} like so@footnote{You can try this interactively in
2374 a C buffer by typing the text that appears in italics.}:
2376 @example
2377 @emph{M-x set-variable RET}
2378 Set variable: @emph{c-basic-offset RET}
2379 Set c-basic-offset to value: @emph{4 RET}
2380 @end example
2382 @noindent
2383 This would change
2385 @example
2386 @group
2387 int add( int val, int incr, int doit )
2389   if( doit )
2390     @{
2391       return( val + incr );
2392     @}
2393   return( val );
2395 @end group
2396 @end example
2398 @noindent
2401 @example
2402 @group
2403 int add( int val, int incr, int doit )
2405     if( doit )
2406         @{
2407             return( val + incr );
2408         @}
2409     return( val );
2411 @end group
2412 @end example
2414 To change indentation styles more radically, you will want to change the
2415 offsets associated with other syntactic symbols.  First, I'll show you
2416 how to do that interactively, then I'll describe how to make changes to
2417 your @file{.emacs} file so that your changes are more permanent.
2419 @menu
2420 * Interactive Customization::
2421 * Permanent Customization::
2422 * Hooks::
2423 * Styles::
2424 * Advanced Customizations::
2425 @end menu
2428 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2429 @node    Interactive Customization, Permanent Customization, , Customizing Indentation
2430 @comment node-name, next, previous, up
2431 @section Interactive Customization
2432 @cindex customization, interactive
2433 @cindex interactive customization
2434 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2436 As an example of how to customize indentation, let's change the
2437 style of this example@footnote{In this and subsequent examples, the
2438 original code is formatted using the @samp{gnu} style unless otherwise
2439 indicated.  @xref{Styles}.}:
2441 @example
2442 @group
2443  1: int add( int val, int incr, int doit )
2444  2: @{
2445  3:   if( doit )
2446  4:     @{
2447  5:       return( val + incr );
2448  6:     @}
2449  7:   return( val );
2450  8: @}
2451 @end group
2452 @end example
2454 @noindent
2457 @example
2458 @group
2459  1: int add( int val, int incr, int doit )
2460  2: @{
2461  3:   if( doit )
2462  4:   @{
2463  5:     return( val + incr );
2464  6:   @}
2465  7:   return( val );
2466  8: @}
2467 @end group
2468 @end example
2470 In other words, we want to change the indentation of braces that open a
2471 block following a condition so that the braces line up under the
2472 conditional, instead of being indented.  Notice that the construct we
2473 want to change starts on line 4.  To change the indentation of a line,
2474 we need to see which syntactic components affect the offset calculations
2475 for that line.  Hitting @kbd{C-c C-s} on line 4 yields:
2477 @example
2478 ((substatement-open 44))
2479 @end example
2481 @noindent
2482 so we know that to change the offset of the open brace, we need to
2483 change the indentation for the @code{substatement-open} syntactic
2484 symbol.
2486 To do this interactively, just hit @kbd{C-c C-o}.  This prompts
2487 you for the syntactic symbol to change, providing a reasonable default.
2488 In this case, the default is @code{substatement-open}, which is just the
2489 syntactic symbol we want to change!
2491 After you hit return, @ccmode{} will then prompt you for the new
2492 offset value, with the old value as the default.  The default in this
2493 case is @samp{+}, but we want no extra indentation so enter
2494 @samp{0} and @kbd{RET}.  This will associate the offset 0 with the
2495 syntactic symbol @code{substatement-open}.
2497 To check your changes quickly, just hit @kbd{C-c C-q}
2498 (@code{c-indent-defun}) to reindent the entire function.  The example
2499 should now look like:
2501 @example
2502 @group
2503  1: int add( int val, int incr, int doit )
2504  2: @{
2505  3:   if( doit )
2506  4:   @{
2507  5:     return( val + incr );
2508  6:   @}
2509  7:   return( val );
2510  8: @}
2511 @end group
2512 @end example
2514 Notice how just changing the open brace offset on line 4 is all we
2515 needed to do.  Since the other affected lines are indented relative to
2516 line 4, they are automatically indented the way you'd expect.  For more
2517 complicated examples, this may not always work.  The general approach to
2518 take is to always start adjusting offsets for lines higher up in the
2519 file, then reindent and see if any following lines need further
2520 adjustments.
2522 @deffn Command c-set-offset symbol offset
2523 @findex set-offset (c-)
2524 @kindex C-c C-o
2525 This is the command bound to @kbd{C-c C-o}.  It provides a convenient
2526 way to set offsets on @code{c-offsets-alist} both interactively (see
2527 the example above) and from your mode hook.
2529 It takes two arguments when used programmatically: @var{symbol} is the
2530 syntactic element symbol to change and @var{offset} is the new offset
2531 for that syntactic element.
2532 @end deffn
2535 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2536 @node    Permanent Customization, Hooks, Interactive Customization, Customizing Indentation
2537 @comment node-name, next, previous, up
2538 @section Permanent Customization
2539 @cindex customization, permanent
2540 @cindex permanent customization
2541 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2543 To make your changes permanent, you need to add some lisp code to your
2544 @file{.emacs} file.  @ccmode{} supports many different ways to be
2545 configured, from the straightforward way by setting variables globally
2546 in @file{.emacs} or in the Customization interface, to the complex and
2547 precisely controlled way by using styles and hook functions.
2549 The simplest way of customizing @ccmode{} permanently is to set the
2550 variables in your @file{.emacs} with @code{setq} and similar commands.
2551 So to make a permanent setting of @code{substatement-open} to 0, add
2552 this to the @file{.emacs} file:
2554 @example
2555 @group
2556 (setq c-offsets-alist
2557       '((substatement-open . 0)))
2558 @end group
2559 @end example
2561 When @ccmode{} initializes a buffer, it will fill out
2562 @code{c-offsets-alist} with the remaining syntactic symbols according to
2563 the style system.
2565 You can also use the more user friendly Customization interface, but
2566 this manual does not cover how that works.
2568 Variables set like this at the top level in @file{.emacs} take effect in
2569 all @ccmode{} buffers, regardless of language.  The indentation style
2570 related variables, e.g., @code{c-offsets-alist}, that you don't set this
2571 way get their value from the style system (@pxref{Styles}), and they
2572 therefore depend on the setting of @code{c-default-style}.  Note that if
2573 you use Customize, this means that the greyed-out default values
2574 presented there might not be the ones you actually get, since the actual
2575 values depend on the style, which may very well be different for
2576 different languages.
2578 If you want to make more advanced configurations, e.g., language-specific
2579 customization, setting global variables isn't enough.  For that you can
2580 use the language hooks, see @ref{Hooks}, and/or the style system, see
2581 @ref{Styles}.
2583 @defopt c-style-variables-are-local-p
2584 @vindex style-variables-are-local-p (c-)
2585 By default, all style variables are buffer local, so that different
2586 buffers can have different style settings.  If you only use one style
2587 in all the files you edit you might want to share them between buffers
2588 so that a change take effect in all buffers.  That's done by setting
2589 this variable to @code{nil}.  The value takes effect when @ccmode{} is
2590 activated in a buffer for the first time in the Emacs session, so you
2591 typically set it in your @file{.emacs} file and then restart Emacs.
2592 @end defopt
2595 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2596 @node    Hooks, Styles, Permanent Customization, Customizing Indentation
2597 @comment node-name, next, previous, up
2598 @section Hooks
2599 @cindex mode hooks
2600 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2602 @ccmode{} provides several hooks that you can use to customize the mode
2603 according to your coding style.  Each language mode has its own hook,
2604 adhering to standard Emacs major mode conventions.  There is also one
2605 general hook and one package initialization hook:
2607 @defvar c-initialization-hook
2608 @vindex initialization-hook (c-)
2609 Hook run only once per Emacs session, when @ccmode{} is initialized.
2610 @end defvar
2612 @defvar c-mode-common-hook
2613 @vindex mode-common-hook (c-)
2614 Common hook across all languages.  It's run immediately before the
2615 language specific hook.
2616 @end defvar
2618 @defvar c-mode-hook
2619 @defvarx c++-mode-hook
2620 @defvarx objc-mode-hook
2621 @defvarx java-mode-hook
2622 @defvarx idl-mode-hook
2623 @defvarx pike-mode-hook
2624 @defvarx awk-mode-hook
2625 The language specific mode hooks.  The appropriate one is run as the
2626 last thing when you enter that language mode.
2627 @end defvar
2629 Note that all the language-specific mode setup that CC Mode does is done
2630 prior to both @code{c-mode-common-hook} and the language specific hook.
2631 That includes installing the indentation style, which can be mode
2632 specific (and also is by default for Java mode).  Thus, any style
2633 settings done in @code{c-mode-common-hook} will override whatever
2634 language-specific style is chosen by @code{c-default-style}.
2636 Here's a simplified example of what you can add to your @file{.emacs}
2637 file to do things whenever any @ccmode{} language is edited.  See the
2638 Emacs manuals for more information on customizing Emacs via hooks.
2639 @xref{Sample .emacs File}, for a more complete sample @file{.emacs}
2640 file.
2642 @example
2643 (defun my-c-mode-common-hook ()
2644   ;; my customizations for all of c-mode and related modes
2645   (no-case-fold-search)
2646   )
2647 (add-hook 'c-mode-common-hook 'my-c-mode-common-hook)
2648 @end example
2651 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2652 @node    Styles, Advanced Customizations, Hooks, Customizing Indentation
2653 @comment node-name, next, previous, up
2654 @section Styles
2655 @cindex styles
2656 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2658 Most people only need to edit code formatted in just a few well-defined
2659 and consistent styles.  For example, their organization might impose a
2660 ``blessed'' style that all its programmers must conform to.  Similarly,
2661 people who work on GNU software will have to use the GNU coding style.
2662 Some shops are more lenient, allowing a variety of coding styles, and as
2663 programmers come and go, there could be a number of styles in use.  For
2664 this reason, @ccmode{} makes it convenient for you to set up logical
2665 groupings of customizations called @dfn{styles}, associate a single name
2666 for any particular style, and pretty easily start editing new or
2667 existing code using these styles.
2669 @cindex style variables
2670 The variables that the style system affect are called @dfn{style
2671 variables}.  They are handled specially in several ways:
2673 @itemize @bullet
2674 @item
2675 Style variables are by default buffer local variables.  However, they
2676 can instead be made global by setting
2677 @code{c-style-variables-are-local-p} to @code{nil} before @ccmode{} is
2678 initialized.
2680 @item
2681 @vindex c-old-style-variable-behavior
2682 @vindex old-style-variable-behavior (c-)
2683 The default value of any style variable (with two exceptions --- see
2684 below) is the special symbol @code{set-from-style}.  Variables that are
2685 still set to that symbol when a @ccmode{} buffer is initialized will be
2686 set according to the current style, otherwise they will keep their
2687 current value@footnote{This is a big change from versions of @ccmode{}
2688 earlier than 5.26, where such settings would get overridden by the style
2689 system unless special precautions were taken.  That was changed since it
2690 was counterintuitive and confusing, especially to novice users.  If your
2691 configuration depends on the old overriding behavior, you can set the
2692 variable @code{c-old-style-variable-behavior} to non-@code{nil}.}.
2694 Note that when we talk about the ``default value'' for a style variable,
2695 we don't mean the @code{set-from-style} symbol that all style variables
2696 are set to initially, but instead the value it will get at mode
2697 initialization when neither a style nor a global setting has set its
2698 value.
2700 The style variable @code{c-offsets-alist} is handled a little
2701 differently from the other style variables.  It's an association list,
2702 and is thus by default set to the empty list, @code{nil}.  When the
2703 style system is initialized, any syntactic symbols already on it are
2704 kept --- only the missing ones are filled in from the chosen style.
2706 The style variable @code{c-special-indent-hook} is also handled in a
2707 special way.  Styles may only add more functions on this hook, so the
2708 global settings on it are always preserved@footnote{This did not change
2709 in version 5.26.}.
2711 @item
2712 The global settings of style variables get captured in the special
2713 @code{user} style, which is used as the base for all the other styles.
2714 @xref{Built-in Styles}, for details.
2715 @end itemize
2717 The style variables are:
2718 @code{c-basic-offset},
2719 @code{c-comment-only-line-offset},
2720 @code{c-block-comment-prefix},
2721 @code{c-comment-prefix-regexp},
2722 @code{c-cleanup-list},
2723 @code{c-hanging-braces-alist},
2724 @code{c-hanging-colons-alist},
2725 @code{c-hanging-semi&comma-criteria},
2726 @code{c-backslash-column},
2727 @code{c-backslash-max-column},
2728 @code{c-special-indent-hook},
2729 @code{c-label-minimum-indentation}, and
2730 @code{c-offsets-alist}.
2732 @menu
2733 * Built-in Styles::
2734 * Choosing a Style::
2735 * Adding Styles::
2736 * File Styles::
2737 @end menu
2740 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2741 @node    Built-in Styles, Choosing a Style, , Styles
2742 @comment node-name, next, previous, up
2743 @subsection Built-in Styles
2744 @cindex styles, built-in
2745 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2747 If you're lucky, one of @ccmode{}'s built-in styles might be just
2748 what you're looking for.  These include:
2750 @table @code
2751 @item gnu
2752 @cindex GNU style
2753 Coding style blessed by the Free Software Foundation
2754 for C code in GNU programs.
2756 @item k&r
2757 @cindex K&R style
2758 The classic Kernighan and Ritchie style for C code.
2760 @item bsd
2761 @cindex BSD style
2762 Also known as ``Allman style'' after Eric Allman.
2764 @item whitesmith
2765 @cindex Whitesmith style
2766 Popularized by the examples that came with Whitesmiths C, an early
2767 commercial C compiler.
2769 @item stroustrup
2770 @cindex Stroustrup style
2771 The classic Stroustrup style for C++ code.
2773 @item ellemtel
2774 @cindex Ellemtel style
2775 Popular C++ coding standards as defined by ``Programming in C++, Rules
2776 and Recommendations,'' Erik Nyquist and Mats Henricson,
2777 Ellemtel@footnote{This document is available at
2778 @uref{http://www.doc.ic.ac.uk/lab/cplus/c++.rules/} among other
2779 places.}.
2781 @item linux
2782 @cindex Linux style
2783 C coding standard for Linux (the kernel).
2785 @item python
2786 @cindex Python style
2787 C coding standard for Python extension modules@footnote{Python is a
2788 high level scripting language with a C/C++ foreign function interface.
2789 For more information, see @uref{http://www.python.org/}.}.
2791 @item java
2792 @cindex Java style
2793 The style for editing Java code.  Note that the default
2794 value for @code{c-default-style} installs this style when you enter
2795 @code{java-mode}.
2797 @item user
2798 @cindex User style
2799 This is a special style for several reasons.  First, the
2800 @ccmode{} customizations you do by using either the Customization
2801 interface, or by writing @code{setq}'s at the top level of your
2802 @file{.emacs} file, will be captured in the @code{user} style.  Also,
2803 all other styles implicitly inherit their settings from @code{user}
2804 style.  This means that for any styles you add via @code{c-add-style}
2805 (@pxref{Adding Styles}) you need only define the differences between
2806 your new style and @code{user} style.
2807 @end table
2810 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2811 @node    Choosing a Style, Adding Styles, Built-in Styles, Styles
2812 @comment node-name, next, previous, up
2813 @subsection Choosing a Style
2814 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2816 Use @kbd{C-c .} to choose a style interactively:
2818 @deffn Command c-set-style style-name
2819 @findex set-style (c-)
2820 @kindex C-c .
2821 Switch to the specified style in the current buffer.  Use
2822 interactively like this:
2824 @example
2825 @kbd{C-c . @var{style-name} RET}
2826 @end example
2828 Note that all style names are case insensitive, even the ones you
2829 define.
2831 Setting a style in this way does @emph{not} automatically reindent your
2832 file.  For commands that you can use to view the effect of your changes,
2833 see @ref{Commands}.
2834 @end deffn
2836 The default style in all newly created buffers is @code{gnu}, except
2837 in Java mode where it's @code{java}.  Although the @code{user} style
2838 is not the default style, any style variable settings you do with the
2839 Customization interface or on the top level in your @file{.emacs} file
2840 will by default override the style system, so you don't need to set
2841 @code{c-default-style} to @code{user} to see the effect of such
2842 settings.
2844 @defopt c-default-style
2845 @vindex default-style (c-)
2846 This variable specifies which style to install by default in new
2847 buffers.  It takes either a style name string, or an association list
2848 of major mode symbols to style names:
2850 @enumerate
2851 @item
2852 When @code{c-default-style} is a string, it must be an existing style
2853 name.  This style is then used for all modes.
2855 @item
2856 When @code{c-default-style} is an association list, the mode language
2857 is looked up to find a style name string.
2859 @item
2860 If @code{c-default-style} is an association list where the mode
2861 language mode isn't found then the special symbol @samp{other} is
2862 looked up.  If it's found then the associated style is used.
2864 @item
2865 If @samp{other} is not found then the @samp{gnu} style is used.
2867 @item
2868 In all cases, the style described in @code{c-default-style} is installed 
2869 @emph{before} the language hooks are run, so you can always override
2870 this setting by including an explicit call to @code{c-set-style} in your 
2871 language mode hook, or in @code{c-mode-common-hook}.
2872 @end enumerate
2873 @end defopt
2875 @defvar c-indentation-style
2876 @vindex indentation-style (c-)
2877 This variable always contains the buffer's current style name, as a
2878 string.
2879 @end defvar
2882 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2883 @node    Adding Styles, File Styles, Choosing a Style, Styles
2884 @comment node-name, next, previous, up
2885 @subsection Adding and Amending Styles
2886 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2888 If none of the built-in styles is appropriate, you'll probably want to
2889 create a new @dfn{style definition}, possibly based on an existing
2890 style.  To do this, put the new style's settings into a list with the
2891 following format - the list can then be passed as an argument to the
2892 function @code{c-add-style}:
2894 @cindex style definition
2895 @defvr {List} style definition
2896 ([@var{base-style}] [(@var{variable} . @var{value}) @dots{}])
2898 Optional @var{base-style}, if present, must be a string which is the
2899 name of the @dfn{base style} from which this style inherits.  At most
2900 one @var{base-style} is allowed in a style definition.  If
2901 @var{base-style} is not specified, the style inherits from a table of
2902 default values@footnote{This table is stored internally in the
2903 variable c-fallback-style.  It is computed during the initialisation
2904 of @ccmode{} from the factory defaults of the style variables and any
2905 global values they may have been given since starting Emacs.} instead.
2906 All styles eventually inherit from this internal table.  Style loops
2907 generate errors.  The list of pre-existing styles can be seen in
2908 @ref{Built-in Styles}.
2910 The dotted pairs (@var{variable} . @var{value}) each consist of a
2911 variable and the value it is to be set to when the style is later
2912 activated.@footnote{In certain circumstances, this value can get
2913 overridden by another value.}  The variable can be either a @ccmode{}
2914 style variable or an arbitrary Emacs variable.  In the latter case, it
2915 is @emph{not} made buffer local by the @ccmode{} style system.
2916 @end defvr
2918 Two variables are treated specially in the dotted pair list:
2920 @table @code
2921 @item c-offsets-alist
2922 The value is in turn a dotted list on the form
2924 (@var{syntactic-symbol} . @var{offset})
2926 as described in @ref{Customizing Indentation}.  These are passed to
2927 @code{c-set-offset} so there is no need to set every syntactic symbol in
2928 your style, only those that are different from the inherited style.
2930 @item c-special-indent-hook
2931 The value is added to @code{c-special-indent-hook} using
2932 @code{add-hook}, so any functions already on it are kept.  If the value
2933 is a list, each element of the list is added with @code{add-hook}.
2934 @end table
2936 Styles are kept in the @code{c-style-alist} variable, but you
2937 should never modify this variable directly.  Instead, @ccmode{}
2938 provides the function @code{c-add-style} for this purpose.
2940 @defun c-add-style stylename description &optional set-p
2941 @findex add-style (c-)
2942 Add or update a style called @var{stylename}, a string.
2943 @var{description} is the new style definition in the form described
2944 above.  If @var{stylename} already exists in @code{c-style-alist} then
2945 it is replaced by @var{description}.  (Note, this replacement is
2946 total.  The old style is @emph{not} merged into the new one.)
2947 Otherwise, a new style is added.  If the optional @var{set-p} is
2948 non-@code{nil} then the new style is applied to the current buffer as
2949 well.
2951 The sample @file{.emacs} file provides a concrete example of how a new
2952 style can be added and automatically set.  @xref{Sample .emacs File}.
2953 @end defun
2955 @defvar c-style-alist
2956 @vindex style-alist (c-)
2957 This is the variable that holds the definitions for the styles.  It
2958 should not be changed directly; use @code{c-add-style} instead.
2959 @end defvar
2962 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2963 @node    File Styles, , Adding Styles, Styles
2964 @comment node-name, next, previous, up
2965 @subsection File Styles
2966 @cindex styles, file local
2967 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2969 @cindex file local variables
2971 The Emacs manual describes how you can customize certain variables on
2972 a per-file basis by including a @dfn{file local variable} block at the
2973 end of the file.  So far, you've only seen a functional interface to
2974 @ccmode{} customization, which can't be used there.  @ccmode{}
2975 provides two variables allow customization of the indentation style on
2976 a per-file basis:
2978 @defvar c-file-style
2979 @vindex file-style (c-)
2980 This variable can be set to a style name string.  When the file is
2981 visited, @ccmode{} will automatically set the file's style to this
2982 one using @code{c-set-style}.
2983 @end defvar
2985 @defvar c-file-offsets
2986 @vindex file-offsets (c-)
2987 This variable takes an association list similar to what is allowed in
2988 @code{c-offsets-alist}.  When the file is visited, @ccmode{} will
2989 automatically institute these offsets using @code{c-set-offset}.
2990 @end defvar
2992 Note that file style settings (i.e., @code{c-file-style}) are applied
2993 before file offset settings (i.e., @code{c-file-offsets}).  Also, if
2994 either of these are set in a file's local variable section, all the
2995 style variable values are made local to that buffer.
2998 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2999 @node    Advanced Customizations, , Styles, Customizing Indentation
3000 @comment node-name, next, previous, up
3001 @section Advanced Customizations
3002 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3004 For most users, @ccmode{} will support their coding styles with very
3005 little need for more advanced customizations.  Usually, one of the
3006 standard styles (@pxref{Built-in Styles}) will do the trick.  At most,
3007 perhaps one of the syntactic symbol offsets will need to be tweaked
3008 slightly, or maybe @code{c-basic-offset} will need to be changed.
3009 However, some styles require a more flexible framework for
3010 customization, and one of the real strengths of @ccmode{} is that the
3011 syntactic analysis model provides just such a framework. This allows
3012 you to implement custom indentation calculations for situations not
3013 handled by the mode directly.
3015 @menu
3016 * Custom Indentation Functions::
3017 * Custom Brace and Colon Hanging::
3018 * Customizing Semicolons and Commas::
3019 * Other Special Indentations::
3020 @end menu
3022 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3023 @node    Custom Indentation Functions, Custom Brace and Colon Hanging, , Advanced Customizations
3024 @comment node-name, next, previous, up
3025 @subsection Custom Indentation Functions
3026 @cindex customization, indentation functions
3027 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3029 The most flexible way to customize @ccmode{} is by writing custom
3030 indentation functions, and associating them with specific syntactic
3031 symbols (@pxref{Syntactic Symbols}).  @ccmode{} itself uses indentation
3032 functions to provide more sophisticated indentation, for example when
3033 lining up C++ stream operator blocks:
3035 @example
3036 @group
3037  1: void main(int argc, char**)
3038  2: @{
3039  3:   cout << "There were "
3040  4:     << argc
3041  5:     << "arguments passed to the program"
3042  6:     << endl;
3043  7: @}
3044 @end group
3045 @end example
3047 In this example, lines 4 through 6 are assigned the @code{stream-op}
3048 syntactic symbol.  Here, @code{stream-op} has an offset of @code{+}, and
3049 with a @code{c-basic-offset} of 2, you can see that lines 4 through 6
3050 are simply indented two spaces to the right of line 3.  But perhaps we'd
3051 like @ccmode{} to be a little more intelligent so that it aligns
3052 all the @samp{<<} symbols in lines 3 through 6.  To do this, we have
3053 to write a custom indentation function which finds the column of the first
3054 stream operator on the first line of the statement.  Here is sample 
3055 lisp code implementing this:
3057 @example
3058 (defun c-lineup-streamop (langelem)
3059   (save-excursion
3060     (goto-char (cdr langelem))
3061     (re-search-forward "<<\\|>>" (c-point 'eol) 'move)
3062     (goto-char (match-beginning 0))
3063     (vector (current-column))))
3064 @end example
3066 Indentation functions take a single argument, which is a syntactic
3067 component cons cell (@pxref{Syntactic Analysis}).  The function can
3068 return an integer which is added to the running total indentation for
3069 the line, or a vector containing an integer which is an absolute
3070 column to align to.  Usually an absolute column is wanted when
3071 aligning to existing text, as in this example.
3073 The function should return @code{nil} if it's used in a situation where
3074 it doesn't want to make any decision.  If the function is used in a list
3075 expression (@pxref{Customizing Indentation}), that will cause @ccmode{}
3076 to go on and check the next entry in the list.
3078 Now, to associate the function @code{c-lineup-streamop} with the
3079 @code{stream-op} syntactic symbol, we can add something like the
3080 following to our @code{c++-mode-hook}@footnote{It probably makes more
3081 sense to add this to @code{c++-mode-hook} than @code{c-mode-common-hook}
3082 since stream operators are only relevant for C++.}:
3084 @example
3085 (c-set-offset 'stream-op 'c-lineup-streamop)
3086 @end example
3088 Now the function looks like this after reindenting (using @kbd{C-c
3089 C-q}):
3091 @example
3092 @group
3093  1: void main(int argc, char**)
3094  2: @{
3095  3:   cout << "There were "
3096  4:        << argc
3097  5:        << " arguments passed to the program"
3098  6:        << endl;
3099  7: @}
3100 @end group
3101 @end example
3103 Custom indentation functions can be as simple or as complex as you like,
3104 and any syntactic symbol that appears in @code{c-offsets-alist} can have
3105 a custom indentation function associated with it.
3107 @ccmode{} comes with an extensive set of predefined indentation
3108 functions, not all of which are used by the default styles.  So there's
3109 a good chance the function you want already exists.  @xref{Indentation
3110 Functions}, for a list of them.  If you have written an indentation
3111 function that you think is generally useful, you're very welcome to
3112 contribute it; please contact @email{bug-cc-mode@@gnu.org}.
3115 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3116 @node    Custom Brace and Colon Hanging, Customizing Semicolons and Commas, Custom Indentation Functions, Advanced Customizations
3117 @comment node-name, next, previous, up
3118 @subsection Custom Brace and Colon Hanging
3119 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3121 @vindex c-hanging-braces-alist
3122 @vindex hanging-braces-alist (c-)
3123 Syntactic symbols aren't the only place where you can customize
3124 @ccmode{} with the lisp equivalent of callback functions.  Brace
3125 ``hanginess'' can also be determined by custom functions associated with
3126 syntactic symbols on the @code{c-hanging-braces-alist} style variable.
3127 Remember that @var{action}'s are typically a list containing some
3128 combination of the symbols @code{before} and @code{after}
3129 (@pxref{Hanging Braces}).  However, an @var{action} can also be a
3130 function which gets called when a brace matching that syntactic symbol
3131 is entered.
3133 @cindex customization, brace hanging
3134 These @var{action} functions are called with two arguments: the
3135 syntactic symbol for the brace, and the buffer position at which the
3136 brace was inserted.  The @var{action} function is expected to return a
3137 list containing some combination of @code{before} and @code{after},
3138 including neither of them (i.e., @code{nil}).  This return value has the
3139 normal brace hanging semantics.
3141 As an example, @ccmode{} itself uses this feature to dynamically
3142 determine the hanginess of braces which close ``do-while''
3143 constructs:
3145 @example
3146 void do_list( int count, char** atleast_one_string )
3148     int i=0;
3149     do @{
3150         handle_string( atleast_one_string[i] );
3151         i++;
3152     @} while( i < count );
3154 @end example
3156 @ccmode{} assigns the @code{block-close} syntactic symbol to the
3157 brace that closes the @code{do} construct, and normally we'd like the
3158 line that follows a @code{block-close} brace to begin on a separate
3159 line.  However, with ``do-while'' constructs, we want the
3160 @code{while} clause to follow the closing brace.  To do this, we
3161 associate the @code{block-close} symbol with the @var{action} function
3162 @code{c-snug-do-while}:
3164 @example
3165 (defun c-snug-do-while (syntax pos)
3166   "Dynamically calculate brace hanginess for do-while statements."
3167   (save-excursion
3168     (let (langelem)
3169       (if (and (eq syntax 'block-close)
3170                (setq langelem (assq 'block-close c-syntactic-context))
3171                (progn (goto-char (cdr langelem))
3172                       (if (= (following-char) ?@{)
3173                           (forward-sexp -1))
3174                       (looking-at "\\<do\\>[^_]")))
3175           '(before)
3176         '(before after)))))
3177 @end example
3179 @findex c-snug-do-while
3180 @findex snug-do-while (c-)
3181 This function simply looks to see if the brace closes a ``do-while''
3182 clause and if so, returns the list @samp{(before)} indicating
3183 that a newline should be inserted before the brace, but not after it.
3184 In all other cases, it returns the list @samp{(before after)} so
3185 that the brace appears on a line by itself.
3187 @defvar c-syntactic-context
3188 @vindex syntactic-context (c-)
3189 During the call to the indentation or brace hanging @var{action}
3190 function, this variable is bound to the full syntactic analysis list.
3191 @end defvar
3193 @cindex customization, colon hanging
3194 @vindex c-hanging-colons-alist
3195 @vindex hanging-colons-alist (c-)
3196 Note that for symmetry, colon hanginess should be customizable by
3197 allowing function symbols as @var{action}s on the
3198 @code{c-hanging-colons-alist} style variable.  Since no use has actually
3199 been found for this feature, it isn't currently implemented!
3202 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3203 @node    Customizing Semicolons and Commas, Other Special Indentations, Custom Brace and Colon Hanging, Advanced Customizations
3204 @comment node-name, next, previous, up
3205 @subsection Customizing Semicolons and Commas
3206 @cindex customization, semicolon newlines
3207 @cindex customization, comma newlines
3208 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3210 You can also customize the insertion of newlines after semicolons and
3211 commas when the auto-newline minor mode is enabled (@pxref{Minor
3212 Modes}).
3214 @defopt c-hanging-semi&comma-criteria
3215 @vindex hanging-semi&comma-criteria (c-)
3216 This style variable takes a list of hooks that get called when a
3217 semicolon or comma is inserted.  The hooks are called in order without
3218 arguments, and are expected to return one of the following values:
3220 @table @code
3221 @item t
3222 A newline is inserted, and no more functions from the list are called.
3223 @item stop
3224 No more functions from the list are called, but no newline is
3225 inserted.
3226 @item nil
3227 No determination is made, and the next function in the list is called.
3228 @end table
3230 If every function in the list is called without a determination being
3231 made, then no newline is added. The default value for this variable is a
3232 list containing a single function which inserts newlines only after
3233 semicolons which do not appear inside parenthesis lists (i.e., those
3234 that separate @code{for}-clause statements).
3235 @end defopt
3237 @defun c-semi&comma-no-newlines-before-nonblanks
3238 @findex semi&comma-no-newlines-before-nonblanks (c-)
3239 This is an example of a criteria function, provided by @ccmode{}.  It
3240 prevents newlines from being inserted after semicolons when there is a
3241 non-blank following line.  Otherwise, it makes no determination.  To
3242 use, add this function to the front of the
3243 @code{c-hanging-semi&comma-criteria} list.
3245 @example
3246 (defun c-semi&comma-no-newlines-before-nonblanks ()
3247   (save-excursion
3248     (if (and (eq last-command-char ?\;)
3249              (zerop (forward-line 1))
3250              (not (looking-at "^[ \t]*$")))
3251         'stop
3252       nil)))
3253 @end example
3254 @end defun
3256 @defun c-semi&comma-inside-parenlist
3257 @findex semi&comma-inside-parenlist (c-)
3258 @defunx c-semi&comma-no-newlines-for-oneline-inliners
3259 @findex semi&comma-no-newlines-for-oneline-inliners (c-)
3260 The function @code{c-semi&comma-inside-parenlist} is what prevents
3261 newlines from being inserted inside the parenthesis list of @code{for}
3262 statements.  In addition to
3263 @code{c-semi&comma-no-newlines-before-nonblanks} described above,
3264 @ccmode{} also comes with the criteria function
3265 @code{c-semi&comma-no-newlines-for-oneline-inliners}, which suppresses
3266 newlines after semicolons inside one-line inline method definitions
3267 (e.g., in C++ or Java).
3268 @end defun
3271 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3272 @node    Other Special Indentations, , Customizing Semicolons and Commas, Advanced Customizations
3273 @comment node-name, next, previous, up
3274 @subsection Other Special Indentations
3275 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3277 Here are the remaining odds and ends regarding indentation:
3279 @defopt c-label-minimum-indentation
3280 @vindex label-minimum-indentation (c-)
3281 In @samp{gnu} style (@pxref{Built-in Styles}), a minimum indentation
3282 is imposed on lines inside top-level constructs.  This minimum
3283 indentation is controlled by this style variable.  The default value
3284 is 1.
3285 @end defopt
3287 @defopt c-special-indent-hook
3288 @vindex special-indent-hook (c-)
3289 This style variable is a standard hook variable that is called after
3290 every line is indented by @ccmode{}.  You can use it to do any special
3291 indentation or line adjustments your style dictates, such as adding
3292 extra indentation to constructors or destructor declarations in a
3293 class definition, etc.  Note that you should not change point or mark
3294 inside your @code{c-special-indent-hook} functions, i.e., you'll
3295 probably want to wrap your function in a @code{save-excursion}.
3297 Setting @code{c-special-indent-hook} in your style definition is
3298 handled slightly differently than other variables.  In your style
3299 definition, you should set the value for @code{c-special-indent-hook}
3300 to a function or list of functions, which will be appended to
3301 @code{c-special-indent-hook} using @code{add-hook}.  That way, the
3302 current setting for the buffer local value of
3303 @code{c-special-indent-hook} won't be overridden.
3304 @end defopt
3307 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3308 @node    Syntactic Symbols, Indentation Functions, Customizing Indentation, Top
3309 @comment node-name, next, previous, up
3310 @chapter Syntactic Symbols
3311 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3313 @cindex syntactic symbols, brief list
3314 @vindex c-offsets-alist
3315 @vindex offsets-alist (c-)
3316 Here is a complete list of the recognized syntactic symbols as described
3317 in the @code{c-offsets-alist} style variable, along with a brief
3318 description.  More detailed descriptions follow.
3320 @table @code
3321 @item string
3322 Inside a multiline string.
3323 @item c
3324 Inside a multiline C style block comment.
3325 @item defun-open
3326 Brace that opens a top-level function definition.
3327 @item defun-close
3328 Brace that closes a top-level function definition.
3329 @item defun-block-intro
3330 The first line in a top-level defun.
3331 @item class-open
3332 Brace that opens a class definition.
3333 @item class-close
3334 Brace that closes a class definition.
3335 @item inline-open
3336 Brace that opens an in-class inline method.
3337 @item inline-close
3338 Brace that closes an in-class inline method.
3339 @item func-decl-cont
3340 The region between a function definition's argument list and the
3341 function opening brace (excluding K&R argument declarations).  In C, you
3342 cannot put anything but whitespace and comments in this region, however
3343 in C++ and Java, @code{throws} declarations and other things can appear
3344 here.
3345 @item knr-argdecl-intro
3346 First line of a K&R C argument declaration.
3347 @item knr-argdecl
3348 Subsequent lines in a K&R C argument declaration.
3349 @item topmost-intro
3350 The first line in a ``topmost'' definition.
3351 @item topmost-intro-cont
3352 Topmost definition continuation lines.  This is only used in the parts
3353 that aren't covered by other symbols such as @code{func-decl-cont} and
3354 @code{knr-argdecl}.
3355 @item member-init-intro
3356 First line in a member initialization list.
3357 @item member-init-cont
3358 Subsequent member initialization list lines.
3359 @item inher-intro
3360 First line of a multiple inheritance list.
3361 @item inher-cont
3362 Subsequent multiple inheritance lines.
3363 @item block-open
3364 Statement block open brace.
3365 @item block-close
3366 Statement block close brace.
3367 @item brace-list-open
3368 Open brace of an enum or static array list.
3369 @item brace-list-close
3370 Close brace of an enum or static array list.
3371 @item brace-list-intro
3372 First line in an enum or static array list.
3373 @item brace-list-entry
3374 Subsequent lines in an enum or static array list.
3375 @item brace-entry-open
3376 Subsequent lines in an enum or static array list where the line begins
3377 with an open brace.
3378 @item statement
3379 A statement.
3380 @item statement-cont
3381 A continuation of a statement.
3382 @item statement-block-intro
3383 The first line in a new statement block.
3384 @item statement-case-intro
3385 The first line in a case block.
3386 @item statement-case-open
3387 The first line in a case block that starts with a brace.
3388 @item substatement
3389 The first line after a conditional or loop construct.
3390 @item substatement-open
3391 The brace that opens a substatement block.
3392 @item substatement-label
3393 The first line after a conditional or loop construct if it's a label.
3394 @item case-label
3395 A label in a @code{switch} block.
3396 @item access-label
3397 C++ access control label.
3398 @item label
3399 Any other label.
3400 @item do-while-closure
3401 The @code{while} line that ends a @code{do}-@code{while} construct.
3402 @item else-clause
3403 The @code{else} line of an @code{if}-@code{else} construct.
3404 @item catch-clause
3405 The @code{catch} or @code{finally} (in Java) line of a
3406 @code{try}-@code{catch} construct.
3407 @item comment-intro
3408 A line containing only a comment introduction.
3409 @item arglist-intro
3410 The first line in an argument list.
3411 @item arglist-cont
3412 Subsequent argument list lines when no arguments follow on the same line
3413 as the arglist opening paren.
3414 @item arglist-cont-nonempty
3415 Subsequent argument list lines when at least one argument follows on the
3416 same line as the arglist opening paren.
3417 @item arglist-close
3418 The solo close paren of an argument list.
3419 @item stream-op
3420 Lines continuing a stream operator (C++ only).
3421 @item inclass
3422 The line is nested inside a class definition.
3423 @item cpp-macro
3424 The start of a preprocessor macro definition.
3425 @item cpp-define-intro
3426 The first line inside a multiline preproprocessor macro if
3427 @code{c-syntactic-indentation-in-macros} is set.
3428 @item cpp-macro-cont
3429 All lines inside multiline preprocessor macros if
3430 @code{c-syntactic-indentation-in-macros} is @code{nil}.
3431 @item friend
3432 A C++ friend declaration.
3433 @item objc-method-intro
3434 The first line of an Objective-C method definition.
3435 @item objc-method-args-cont
3436 Lines continuing an Objective-C method definition.
3437 @item objc-method-call-cont
3438 Lines continuing an Objective-C method call.
3439 @item extern-lang-open
3440 Brace that opens an @code{extern} block (e.g., @code{extern "C" @{...@}}).
3441 @item extern-lang-close
3442 Brace that closes an @code{extern} block.
3443 @item inextern-lang
3444 Analogous to @code{inclass} syntactic symbol, but used inside
3445 @code{extern} blocks.
3446 @item namespace-open
3447 @itemx namespace-close
3448 @itemx innamespace
3449 These are analogous to the three @code{extern-lang} symbols above, but
3450 are returned for C++ namespace blocks.
3451 @item module-open
3452 @itemx module-close
3453 @itemx inmodule
3454 Analogous to the above, but for CORBA IDL @code{module} blocks.
3455 @item composition-open
3456 @itemx composition-close
3457 @itemx incomposition
3458 Analogous to the above, but for CORBA CIDL @code{composition} blocks.
3459 @item template-args-cont
3460 C++ template argument list continuations.
3461 @item inlambda
3462 Analogous to @code{inclass} syntactic symbol, but used inside lambda
3463 (i.e., anonymous) functions.  Only used in Pike mode.
3464 @item lambda-intro-cont
3465 Lines continuing the header of a lambda function, i.e., between the
3466 @code{lambda} keyword and the function body.  Only used in Pike mode.
3467 @item inexpr-statement
3468 A statement block inside an expression.  The gcc C and C++ extension for
3469 this is recognized.  It's also used for the special functions that take
3470 a statement block as an argument in Pike.
3471 @item inexpr-class
3472 A class definition inside an expression.  This is used for anonymous
3473 classes in Java.  It's also used for anonymous array initializers in
3474 Java.
3475 @end table
3477 @ssindex -open symbols
3478 @ssindex -close symbols
3479 Most syntactic symbol names follow a general naming convention.  When a
3480 line begins with an open or close brace, the syntactic symbol will
3481 contain the suffix @code{-open} or @code{-close} respectively.
3483 @ssindex -intro symbols
3484 @ssindex -cont symbols
3485 @ssindex -block-intro symbols
3486 Usually, a distinction is made between the first line that introduces a
3487 construct and lines that continue a construct, and the syntactic symbols
3488 that represent these lines will contain the suffix @code{-intro} or
3489 @code{-cont} respectively.  As a sub-classification of this scheme, a
3490 line which is the first of a particular brace block construct will
3491 contain the suffix @code{-block-intro}.
3493 Let's look at some examples to understand how this works.  Remember that
3494 you can check the syntax of any line by using @kbd{C-c C-s}.
3496 @example
3497  1: void
3498  2: swap( int& a, int& b )
3499  3: @{
3500  4:     int tmp = a;
3501  5:     a = b;
3502  6:     b = tmp;
3503  7:     int ignored =
3504  8:         a + b;
3505  9: @}
3506 @end example
3508 @ssindex topmost-intro
3509 @ssindex topmost-intro-cont
3510 @ssindex defun-open
3511 @ssindex defun-close
3512 @ssindex defun-block-intro
3513 Line 1 shows a @code{topmost-intro} since it is the first line that
3514 introduces a top-level construct.  Line 2 is a continuation of the
3515 top-level construct introduction so it has the syntax
3516 @code{topmost-intro-cont}.  Line 3 shows a @code{defun-open} since it is
3517 the brace that opens a top-level function definition.  Line 9 is the
3518 corresponding
3519 @code{defun-close} since it contains the brace that closes the top-level
3520 function definition.  Line 4 is a @code{defun-block-intro}, i.e., it is
3521 the first line of a brace-block, enclosed in a
3522 top-level function definition.
3524 @ssindex statement
3525 @ssindex statement-cont
3526 Lines 5, 6, and 7 are all given @code{statement} syntax since there
3527 isn't much special about them.  Note however that line 8 is given
3528 @code{statement-cont} syntax since it continues the statement begun
3529 on the previous line.
3531 Here's another example, which illustrates some C++ class syntactic
3532 symbols:
3534 @example
3535  1: class Bass
3536  2:     : public Guitar,
3537  3:       public Amplifiable
3538  4: @{
3539  5: public:
3540  6:     Bass()
3541  7:         : eString( new BassString( 0.105 )),
3542  8:           aString( new BassString( 0.085 )),
3543  9:           dString( new BassString( 0.065 )),
3544 10:           gString( new BassString( 0.045 ))
3545 11:     @{
3546 12:         eString.tune( 'E' );
3547 13:         aString.tune( 'A' );
3548 14:         dString.tune( 'D' );
3549 15:         gString.tune( 'G' );
3550 16:     @}
3551 17:     friend class Luthier;
3552 18: @};
3553 @end example
3555 @ssindex class-open
3556 @ssindex class-close
3557 As in the previous example, line 1 has the @code{topmost-intro} syntax.
3558 Here however, the brace that opens a C++ class definition on line 4 is
3559 assigned the @code{class-open} syntax.  Note that in C++, classes,
3560 structs, and unions are essentially equivalent syntactically (and are
3561 very similar semantically), so replacing the @code{class} keyword in the
3562 example above with @code{struct} or @code{union} would still result in a
3563 syntax of @code{class-open} for line 4 @footnote{This is the case even
3564 for C and Objective-C.  For consistency, structs in all supported
3565 languages are syntactically equivalent to classes.  Note however that
3566 the keyword @code{class} is meaningless in C and Objective-C.}.
3567 Similarly, line 18 is assigned @code{class-close} syntax.
3569 @ssindex inher-intro
3570 @ssindex inher-cont
3571 Line 2 introduces the inheritance list for the class so it is assigned
3572 the @code{inher-intro} syntax, and line 3, which continues the
3573 inheritance list is given @code{inher-cont} syntax.
3575 @ssindex access-label
3576 @ssindex inclass
3577 Hitting @kbd{C-c C-s} on line 5 shows the following analysis:
3579 @example
3580 ((inclass 58) (access-label 58))
3581 @end example
3583 @noindent
3584 The primary syntactic symbol for this line is @code{access-label} as
3585 this a label keyword that specifies access protection in C++.  However,
3586 because this line is also a top-level construct inside a class
3587 definition, the analysis actually shows two syntactic symbols.  The
3588 other syntactic symbol assigned to this line is @code{inclass}.
3589 Similarly, line 6 is given both @code{inclass} and @code{topmost-intro}
3590 syntax:
3592 @example
3593 ((inclass 58) (topmost-intro 60))
3594 @end example
3596 @ssindex member-init-intro
3597 @ssindex member-init-cont
3598 Line 7 introduces a C++ member initialization list and as such is given
3599 @code{member-init-intro} syntax.  Note that in this case it is
3600 @emph{not} assigned @code{inclass} since this is not considered a
3601 top-level construct.  Lines 8 through 10 are all assigned
3602 @code{member-init-cont} since they continue the member initialization
3603 list started on line 7.
3605 @cindex in-class inline methods
3606 @ssindex inline-open
3607 @ssindex inline-close
3608 Line 11's analysis is a bit more complicated:
3610 @example
3611 ((inclass 58) (inline-open))
3612 @end example
3614 This line is assigned a syntax of both @code{inline-open} and
3615 @code{inclass} because it opens an @dfn{in-class} C++ inline method
3616 definition.  This is distinct from, but related to, the C++ notion of an
3617 inline function in that its definition occurs inside an enclosing class
3618 definition, which in C++ implies that the function should be inlined.
3619 However, if the definition of the @code{Bass} constructor appeared
3620 outside the class definition, the construct would be given the
3621 @code{defun-open} syntax, even if the keyword @code{inline} appeared
3622 before the method name, as in:
3624 @example
3625  1: class Bass
3626  2:     : public Guitar,
3627  3:       public Amplifiable
3628  4: @{
3629  5: public:
3630  6:     Bass();
3631  7: @};
3632  8:
3633  9: inline
3634 10: Bass::Bass()
3635 11:     : eString( new BassString( 0.105 )),
3636 12:       aString( new BassString( 0.085 )),
3637 13:       dString( new BassString( 0.065 )),
3638 14:       gString( new BassString( 0.045 ))
3639 15: @{
3640 16:     eString.tune( 'E' );
3641 17:     aString.tune( 'A' );
3642 18:     dString.tune( 'D' );
3643 19:     gString.tune( 'G' );
3644 20: @}
3645 @end example
3647 @ssindex friend
3648 Returning to the previous example, line 16 is given @code{inline-close}
3649 syntax, while line 12 is given @code{defun-block-open} syntax, and lines
3650 13 through 15 are all given @code{statement} syntax.  Line 17 is
3651 interesting in that its syntactic analysis list contains three
3652 elements:
3654 @example
3655 ((inclass 58) (topmost-intro 380) (friend))
3656 @end example
3658 The @code{friend} syntactic symbol is a modifier that typically does not
3659 have a relative buffer position.
3661 Template definitions introduce yet another syntactic symbol:
3663 @example
3664  1: ThingManager <int,
3665  2:    Framework::Callback *,
3666  3:    Mutex> framework_callbacks;
3667 @end example
3669 Here, line 1 is analyzed as a @code{topmost-intro}, but lines 2 and 3
3670 are both analyzed as @code{template-args-cont} lines.
3672 Here is another (totally contrived) example which illustrates how syntax
3673 is assigned to various conditional constructs:
3675 @example
3676  1: void spam( int index )
3677  2: @{
3678  3:     for( int i=0; i<index; i++ )
3679  4:     @{
3680  5:         if( i == 10 )
3681  6:             do_something_special();
3682  7:         else
3683  8:           silly_label:
3684  9:             do_something( i );
3685 10:     @}
3686 11:     do @{
3687 12:         another_thing( i-- );
3688 13:     @}
3689 14:     while( i > 0 );
3690 15: @}
3691 @end example
3693 Only the lines that illustrate new syntactic symbols will be discussed.
3695 @ssindex substatement-open
3696 @ssindex substatement-block-intro
3697 @ssindex block-close
3698 Line 4 has a brace which opens a conditional's substatement block.  It
3699 is thus assigned @code{substatement-open} syntax, and since line 5 is
3700 the first line in the substatement block, it is assigned
3701 @code{substatement-block-intro} syntax.  Line 10 contains the brace that
3702 closes the inner substatement block, and is therefore given the syntax
3703 @code{block-close}.  Line 13 is treated the same way.
3705 @ssindex substatement
3706 Lines 6 and 9 are also substatements of conditionals, but since they
3707 don't start blocks they are given @code{substatement} syntax
3708 instead of @code{substatement-open}.
3710 @ssindex substatement-label
3711 Line 8 contains a label, which is normally given @code{label} syntax.
3712 This one is however a bit special since it's between a conditional and
3713 its substatement.  It's analyzed as @code{substatement-label} to let you
3714 handle this rather odd case differently from normal labels.
3716 @ssindex else-clause
3717 @ssindex catch-clause
3718 Line 7 start with an @code{else} that matches the @code{if} statement on
3719 line 5.  It is therefore given the @code{else-clause} syntax and is
3720 anchored on the matching @code{if}.  The @code{try}-@code{catch}
3721 constructs in C++ and Java are treated this way too, except that
3722 @code{catch} and (in Java) @code{finally}, are marked with
3723 @code{catch-clause}.
3725 @ssindex do-while-closure
3726 The @code{while} construct on line 14 that closes a @code{do}
3727 conditional is given the special syntax @code{do-while-closure} if it
3728 appears on a line by itself.  Note that if the @code{while} appeared on
3729 the same line as the preceding close brace, that line would still have
3730 @code{block-close} syntax.
3732 Switch statements have their own set of syntactic symbols.  Here's an
3733 example:
3735 @example
3736  1: void spam( enum Ingredient i )
3737  2: @{
3738  3:     switch( i ) @{
3739  4:     case Ham:
3740  5:         be_a_pig();
3741  6:         break;
3742  7:     case Salt:
3743  8:         drink_some_water();
3744  9:         break;
3745 10:     default:
3746 11:         @{
3747 12:             what_is_it();
3748 13:             break;
3749 14:         @}
3750 15:     @}
3751 14: @}
3752 @end example
3754 @ssindex case-label
3755 @ssindex statement-case-intro
3756 @ssindex statement-case-open
3757 Here, lines 4, 7, and 10 are all assigned @code{case-label} syntax,
3758 while lines 5 and 8 are assigned @code{statement-case-intro}.  Line 11
3759 is treated slightly differently since it contains a brace that opens a
3760 block --- it is given @code{statement-case-open} syntax.
3762 @cindex brace lists
3763 There are a set of syntactic symbols that are used to recognize
3764 constructs inside of brace lists.  A brace list is defined as an
3765 @code{enum} or aggregate initializer list, such as might statically
3766 initialize an array of structs.  The three special aggregate constructs
3767 in Pike, @code{(@{ @})}, @code{([ ])} and @code{(< >)}, are treated as
3768 brace lists too.  An example:
3770 @example
3771  1: static char* ingredients[] =
3772  2: @{
3773  3:     "Ham",
3774  4:     "Salt",
3775  5:     NULL
3776  6: @};
3777 @end example
3779 @ssindex brace-list-open
3780 @ssindex brace-list-intro
3781 @ssindex brace-list-close
3782 @ssindex brace-list-entry
3783 Following convention, line 2 in this example is assigned
3784 @code{brace-list-open} syntax, and line 3 is assigned
3785 @code{brace-list-intro} syntax.  Likewise, line 6 is assigned
3786 @code{brace-list-close} syntax.  Lines 4 and 5 however, are assigned
3787 @code{brace-list-entry} syntax, as would all subsequent lines in this
3788 initializer list.
3790 @ssindex brace-entry-open
3791 Your static initializer might be initializing nested structures, for
3792 example:
3794 @example
3795  1: struct intpairs[] =
3796  2: @{
3797  3:     @{ 1, 2 @},
3798  4:     @{
3799  5:         3,
3800  6:         4
3801  7:     @}
3802  8:     @{ 1,
3803  9:       2 @},
3804 10:     @{ 3, 4 @}
3805 11: @};
3806 @end example
3808 Here, you've already seen the analysis of lines 1, 2, 3, and 11.  On
3809 line 4, things get interesting; this line is assigned
3810 @code{brace-entry-open} syntactic symbol because it's a bracelist entry
3811 line that starts with an open brace.  Lines 5 and 6 (and line 9) are
3812 pretty standard, and line 7 is a @code{brace-list-close} as you'd
3813 expect.  Once again, line 8 is assigned as @code{brace-entry-open} as is
3814 line 10.
3816 External language definition blocks also have their own syntactic
3817 symbols.  In this example:
3819 @example
3820  1: extern "C"
3821  2: @{
3822  3:     int thing_one( int );
3823  4:     int thing_two( double );
3824  5: @}
3825 @end example
3827 @ssindex extern-lang-open
3828 @ssindex extern-lang-close
3829 @ssindex inextern-lang
3830 @ssindex inclass
3831 @noindent
3832 line 2 is given the @code{extern-lang-open} syntax, while line 5 is given
3833 the @code{extern-lang-close} syntax.  The analysis for line 3 yields:
3835 @example
3836 ((inextern-lang) (topmost-intro 14))
3837 @end example
3839 @noindent
3840 where @code{inextern-lang} is a modifier similar in purpose to
3841 @code{inclass}.
3843 There are various other top level blocks like @code{extern}, and they
3844 are all treated in the same way except that the symbols are named after
3845 the keyword that introduces the block.  e.g., C++ namespace blocks get
3846 the three symbols @code{namespace-open}, @code{namespace-close} and
3847 @code{innamespace}.  The currently recognized top level blocks are:
3849 @table @asis
3850 @item @code{extern-lang-open}, @code{extern-lang-close}, @code{inextern-lang}
3851 @code{extern} blocks in C and C++.@footnote{These should logically be
3852 named @code{extern-open}, @code{extern-close} and @code{inextern}, but
3853 that isn't the case for historical reasons.}
3855 @item @code{namespace-open}, @code{namespace-close}, @code{innamespace}
3856 @ssindex namespace-open
3857 @ssindex namespace-close
3858 @ssindex innamespace
3859 @code{namespace} blocks in C++.
3861 @item @code{module-open}, @code{module-close}, @code{inmodule}
3862 @ssindex module-open
3863 @ssindex module-close
3864 @ssindex inmodule
3865 @code{module} blocks in CORBA IDL.
3867 @item @code{composition-open}, @code{composition-close}, @code{incomposition}
3868 @ssindex composition-open
3869 @ssindex composition-close
3870 @ssindex incomposition
3871 @code{composition} blocks in CORBA CIDL.
3872 @end table
3874 A number of syntactic symbols are associated with parenthesis lists,
3875 a.k.a argument lists, as found in function declarations and function
3876 calls.  This example illustrates these:
3878 @example
3879  1: void a_function( int line1,
3880  2:                  int line2 );
3881  3: 
3882  4: void a_longer_function(
3883  5:     int line1,
3884  6:     int line2
3885  7:     );
3886  8: 
3887  9: void call_them( int line1, int line2 )
3888 10: @{
3889 11:     a_function(
3890 12:         line1,
3891 13:         line2
3892 14:         );
3893 15: 
3894 16:     a_longer_function( line1,
3895 17:                        line2 );
3896 18: @}
3897 @end example
3899 @ssindex arglist-intro
3900 @ssindex arglist-close
3901 Lines 5 and 12 are assigned @code{arglist-intro} syntax since they are
3902 the first line following the open parenthesis, and lines 7 and 14 are
3903 assigned @code{arglist-close} syntax since they contain the parenthesis
3904 that closes the argument list.
3906 @ssindex arglist-cont-nonempty
3907 @ssindex arglist-cont
3908 Lines that continue argument lists can be assigned one of two syntactic
3909 symbols.  For example, Lines 2 and 17
3910 are assigned @code{arglist-cont-nonempty} syntax.  What this means
3911 is that they continue an argument list, but that the line containing the
3912 parenthesis that opens the list is @emph{not empty} following the open
3913 parenthesis.  Contrast this against lines 6 and 13 which are assigned
3914 @code{arglist-cont} syntax.  This is because the parenthesis that opens
3915 their argument lists is the last character on that line.
3917 Note that there is no @code{arglist-open} syntax.  This is because any
3918 parenthesis that opens an argument list, appearing on a separate line,
3919 is assigned the @code{statement-cont} syntax instead.
3921 A few miscellaneous syntactic symbols that haven't been previously
3922 covered are illustrated by this C++ example:
3924 @example
3925  1: void Bass::play( int volume )
3926  2: const
3927  3: @{
3928  4:     /* this line starts a multiline
3929  5:      * comment.  This line should get `c' syntax */
3930  6: 
3931  7:     char* a_multiline_string = "This line starts a multiline \
3932  8: string.  This line should get `string' syntax.";
3933  9: 
3934 10:   note:
3935 11:     @{
3936 12: #ifdef LOCK
3937 13:         Lock acquire();
3938 14: #endif // LOCK
3939 15:         slap_pop();
3940 16:         cout << "I played "
3941 17:              << "a note\n";
3942 18:     @}
3943 19: @}
3944 @end example
3946 The lines to note in this example include:
3948 @itemize @bullet
3949 @item
3950 @ssindex func-decl-cont
3951 Line 2 is assigned the @code{func-decl-cont} syntax.
3953 @item
3954 @ssindex comment-intro
3955 Line 4 is assigned both @code{defun-block-intro} @emph{and}
3956 @code{comment-intro} syntax.
3958 @item
3959 @ssindex c
3960 Line 5 is assigned @code{c} syntax.
3962 @item
3963 @cindex syntactic whitespace
3964 Line 6 which, even though it contains nothing but whitespace, is
3965 assigned @code{defun-block-intro}.  Note that the appearance of the
3966 comment on lines 4 and 5 do not cause line 6 to be assigned
3967 @code{statement} syntax because comments are considered to be
3968 @dfn{syntactic whitespace}, which are ignored when analyzing
3969 code.
3971 @item
3972 @ssindex string
3973 Line 8 is assigned @code{string} syntax.
3975 @item
3976 @ssindex label
3977 Line 10 is assigned @code{label} syntax.
3979 @item
3980 @ssindex block-open
3981 Line 11 is assigned @code{block-open} syntax.
3983 @item
3984 @ssindex cpp-macro
3985 Lines 12 and 14 are assigned @code{cpp-macro} syntax in addition to the
3986 normal syntactic symbols (@code{statement-block-intro} and
3987 @code{statement}, respectively).  Normally @code{cpp-macro} is
3988 configured to cancel out the normal syntactic context to make all
3989 preprocessor directives stick to the first column, but that's easily
3990 changed if you want preprocessor directives to be indented like the rest
3991 of the code.
3993 @item
3994 @ssindex stream-op
3995 Line 17 is assigned @code{stream-op} syntax.
3996 @end itemize
3998 @cindex multiline macros
3999 @cindex syntactic whitespace
4000 @ssindex cpp-define-intro
4001 Multiline preprocessor macro definitions are normally handled just like
4002 other code, i.e., the lines inside them are indented according to the
4003 syntactic analysis of the preceding lines inside the macro.  The first
4004 line inside a macro definition (i.e., the line after the starting line of
4005 the cpp directive itself) gets @code{cpp-define-intro}.  In this example:
4007 @example
4008  1: #define LIST_LOOP(cons, listp)                         \
4009  2:   for (cons = listp; !NILP (cons); cons = XCDR (cons)) \
4010  3:     if (!CONSP (cons))                                 \
4011  4:       signal_error ("Invalid list format", listp);     \
4012  5:     else
4013 @end example
4015 @noindent
4016 line 1 is given the syntactic symbol @code{cpp-macro}.  The first line
4017 of a cpp directive is always given that symbol.  Line 2 is given
4018 @code{cpp-define-intro}, so that you can give the macro body as a whole
4019 some extra indentation.  Lines 3 through 5 are then analyzed as normal
4020 code, i.e., @code{substatement} on lines 3 and 4, and @code{else-clause}
4021 on line 5.
4023 The syntactic analysis inside macros can be turned off with
4024 @code{c-syntactic-indentation-in-macros}.  In that case, lines 2 through
4025 5 would all be given @code{cpp-macro-cont} with a relative buffer
4026 position pointing to the @code{#} which starts the cpp
4027 directive@footnote{This is how @ccmode{} 5.28 and earlier analyzed
4028 macros.}.
4030 @xref{Macro Handling}, for more info about the treatment of macros.
4032 In Objective-C buffers, there are three additional syntactic symbols
4033 assigned to various message calling constructs.  Here's an example
4034 illustrating these:
4036 @example
4037  1: - (void)setDelegate:anObject
4038  2:           withStuff:stuff
4039  3: @{
4040  4:     [delegate masterWillRebind:self
4041  5:               toDelegate:anObject
4042  6:               withExtraStuff:stuff];
4043  7: @}
4044 @end example
4046 @ssindex objc-method-intro
4047 @ssindex objc-method-args-cont
4048 @ssindex objc-method-call-cont
4049 Here, line 1 is assigned @code{objc-method-intro} syntax, and line 2 is
4050 assigned @code{objc-method-args-cont} syntax.  Lines 5 and 6 are both
4051 assigned @code{objc-method-call-cont} syntax.
4053 Java has a concept of anonymous classes, which may look something like
4054 this:
4056 @example
4057  1: public void watch(Observable o) @{
4058  2:     o.addObserver(new Observer() @{
4059  3:             public void update(Observable o, Object arg) @{
4060  4:                 history.addElement(arg);
4061  5:             @}
4062  6:         @});
4063  7: @}
4064 @end example
4066 @ssindex inexpr-class
4067 The brace following the @code{new} operator opens the anonymous class.
4068 Lines 3 and 6 are assigned the @code{inexpr-class} syntax, besides the
4069 @code{inclass} symbol used in normal classes.  Thus, the class will be
4070 indented just like a normal class, with the added indentation given to
4071 @code{inexpr-class}.
4073 There are a few occasions where a statement block may be used inside an
4074 expression.  One is in C or C++ code using the gcc extension for this,
4075 e.g:
4077 @example
4078  1: int res = (@{
4079  2:         int y = foo (); int z;
4080  3:         if (y > 0) z = y; else z = - y;
4081  4:         z;
4082  5:     @});
4083 @end example
4085 @ssindex inexpr-statement
4086 Lines 2 and 5 get the @code{inexpr-statement} syntax, besides the
4087 symbols they'd get in a normal block.  Therefore, the indentation put on
4088 @code{inexpr-statement} is added to the normal statement block
4089 indentation.
4091 In Pike code, there are a few other situations where blocks occur inside
4092 statements, as illustrated here:
4094 @example
4095  1: array itgob()
4096  2: @{
4097  3:     string s = map (backtrace()[-2][3..],
4098  4:                     lambda
4099  5:                         (mixed arg)
4100  6:                     @{
4101  7:                         return sprintf ("%t", arg);
4102  8:                     @}) * ", " + "\n";
4103  9:     return catch @{
4104 10:             write (s + "\n");
4105 11:         @};
4106 12: @}
4107 @end example
4109 @ssindex inlambda
4110 @ssindex lambda-intro-cont
4111 Lines 4 through 8 contain a lambda function, which @ccmode{} recognizes
4112 by the @code{lambda} keyword.  If the function argument list is put
4113 on a line of its own, as in line 5, it gets the @code{lambda-intro-cont}
4114 syntax.  The function body is handled as an inline method body, with the
4115 addition of the @code{inlambda} syntactic symbol.  This means that line
4116 6 gets @code{inlambda} and @code{inline-open}, and line 8 gets
4117 @code{inline-close}@footnote{You might wonder why it doesn't get
4118 @code{inlambda} too.  It's because the closing brace is relative to the
4119 opening brace, which stands on its own line in this example.  If the
4120 opening brace was hanging on the previous line, then the closing brace
4121 would get the @code{inlambda} syntax too to be indented correctly.}.
4123 @ssindex inexpr-statement
4124 On line 9, @code{catch} is a special function taking a statement block
4125 as its argument.  The block is handled as an in-expression statement
4126 with the @code{inexpr-statement} syntax, just like the gcc extended C
4127 example above.  The other similar special function, @code{gauge}, is
4128 handled like this too.
4130 @ssindex knr-argdecl-intro
4131 @ssindex knr-argdecl
4132 Two other syntactic symbols can appear in old style, non-prototyped C
4133 code @footnote{a.k.a. K&R C, or Kernighan & Ritchie C}:
4135 @example
4136  1: int add_three_integers(a, b, c)
4137  2:      int a;
4138  3:      int b;
4139  4:      int c;
4140  5: @{
4141  6:     return a + b + c;
4142  7: @}
4143 @end example
4145 Here, line 2 is the first line in an argument declaration list and so is
4146 given the @code{knr-argdecl-intro} syntactic symbol.  Subsequent lines
4147 (i.e., lines 3 and 4 in this example), are given @code{knr-argdecl}
4148 syntax.
4151 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4152 @node    Indentation Functions, AWK Mode, Syntactic Symbols, Top
4153 @comment node-name, next, previous, up
4154 @chapter Indentation Functions
4155 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4157 @cindex indentation function
4158 @cindex line-up function
4159 Often there are cases when a simple offset setting on a syntactic
4160 symbol isn't enough to get the desired indentation.  Therefore, it's
4161 also possible to use an @dfn{indentation function} (a.k.a. @dfn{line-up
4162 function}) for a syntactic symbol.
4164 @ccmode{} comes with many predefined indentation functions for common
4165 situations.  If none of these does what you want, you can write your
4166 own, see @ref{Custom Indentation Functions}.  If you do, it's probably a
4167 good idea to start working from one of these predefined functions, they
4168 can be found in the file @file{cc-align.el}.
4170 For every function below there is a ``works with'' list that indicates
4171 which syntactic symbols the function is intended to be used with.
4173 @macro workswith
4174 @emph{Works with:@ }
4175 @end macro
4176 @ifinfo
4177 @unmacro workswith
4178 @macro workswith
4179 Works with:
4180 @end macro
4181 @end ifinfo
4183 @macro sssTBasicOffset
4184 <--> @i{c-basic-offset}@c
4185 @end macro
4187 @macro sssTsssTBasicOffset
4188 <--><--> @i{c-basic-offset}@c
4189 @end macro
4191 @macro hereFn{func}
4192 <- @i{\func\}@c
4193 @end macro
4195 @c The TeX backend seems to insert extra spaces around the argument. :P
4196 @iftex
4197 @unmacro hereFn
4198 @macro hereFn{func}
4199 <-@i{\func\}@c
4200 @end macro
4201 @end iftex
4203 @comment ------------------------------------------------------------
4205 @defun c-indent-one-line-block
4206 @findex indent-one-line-block (c-)
4207 Indent a one line block @code{c-basic-offset} extra.  E.g:
4209 @example
4210 @group
4211 if (n > 0)
4212     @{m+=n; n=0;@}      @hereFn{c-indent-one-line-block}
4213 @sssTBasicOffset{}
4214 @end group
4215 @end example
4217 @noindent
4220 @example
4221 @group
4222 if (n > 0)
4223 @{                     @hereFn{c-indent-one-line-block}
4224     m+=n; n=0;
4226 @end group
4227 @end example
4229 The block may be surrounded by any kind of parenthesis characters.
4230 @code{nil} is returned if the line doesn't start with a one line block,
4231 which makes the function usable in list expressions.
4233 @workswith Almost all syntactic symbols, but most useful on the
4234 @code{-open} symbols.
4235 @end defun
4237 @comment ------------------------------------------------------------
4239 @defun c-indent-multi-line-block
4240 @findex indent-multi-line-block (c-)
4241 Indent a multiline block @code{c-basic-offset} extra.  E.g:
4243 @example
4244 @group
4245 int *foo[] = @{
4246     NULL,                 
4247     @{17@},             @hereFn{c-indent-multi-line-block}
4248 @end group
4249 @end example
4251 @noindent
4254 @example
4255 @group
4256 int *foo[] = @{
4257     NULL,
4258         @{             @hereFn{c-indent-multi-line-block}
4259         17
4260         @},
4261     @sssTBasicOffset{}
4262 @end group
4263 @end example
4265 The block may be surrounded by any kind of parenthesis characters.
4266 @code{nil} is returned if the line doesn't start with a multiline
4267 block, which makes the function usable in list expressions.
4269 @workswith Almost all syntactic symbols, but most useful on the
4270 @code{-open} symbols.
4271 @end defun
4273 @comment ------------------------------------------------------------
4275 @defun c-lineup-argcont
4276 @findex lineup-argcont (c-)
4277 Line up a continued argument.  E.g:
4279 @example
4280 @group
4281 foo (xyz, aaa + bbb + ccc
4282           + ddd + eee + fff);  @hereFn{c-lineup-argcont}
4283 @end group
4284 @end example
4286 Only continuation lines like this are touched, @code{nil} is returned on
4287 lines which are the start of an argument.
4289 Within a gcc @code{asm} block, @code{:} is recognised as an argument
4290 separator, but of course only between operand specifications, not in the
4291 expressions for the operands.
4293 @workswith @code{arglist-cont}, @code{arglist-cont-nonempty}.
4294 @end defun
4296 @comment ------------------------------------------------------------
4298 @defun c-lineup-arglist
4299 @findex lineup-arglist (c-)
4300 Line up the current argument line under the first argument.
4302 As a special case, if an argument on the same line as the open
4303 parenthesis starts with a brace block opener, the indentation is
4304 @code{c-basic-offset} only.  This is intended as a ``DWIM'' measure in
4305 cases like macros that contains statement blocks, e.g:
4307 @example
4308 @group
4309 A_VERY_LONG_MACRO_NAME (@{
4310         some (code, with + long, lines * in[it]);
4311     @});
4312 @sssTBasicOffset{}
4313 @end group
4314 @end example
4316 This is motivated partly because it's more in line with how code
4317 blocks are handled, and partly since it approximates the behavior of
4318 earlier CC Mode versions, which due to inaccurate analysis tended to
4319 indent such cases this way.
4321 @workswith @code{arglist-cont-nonempty}, @code{arglist-close}.
4322 @end defun
4324 @comment ------------------------------------------------------------
4326 @defun c-lineup-arglist-intro-after-paren
4327 @findex lineup-arglist-intro-after-paren (c-)
4328 Line up a line to just after the open paren of the surrounding paren or
4329 brace block.
4331 @workswith @code{defun-block-intro}, @code{brace-list-intro},
4332 @code{statement-block-intro}, @code{statement-case-intro},
4333 @code{arglist-intro}.
4334 @end defun
4336 @comment ------------------------------------------------------------
4338 @defun c-lineup-arglist-close-under-paren
4339 @findex lineup-arglist-close-under-paren (c-)
4340 Set your @code{arglist-close} syntactic symbol to this line-up function
4341 so that parentheses that close argument lists will line up under the
4342 parenthesis that opened the argument list.  It can also be used with
4343 @code{arglist-cont} and @code{arglist-cont-nonempty} to line up all
4344 lines inside a parenthesis under the open paren.
4346 As a special case, if a brace block is opened at the same line as the
4347 open parenthesis of the argument list, the indentation is
4348 @code{c-basic-offset} only.  See @code{c-lineup-arglist} for further
4349 discussion of this ``DWIM'' measure.
4351 @workswith Almost all symbols, but are typically most useful on
4352 @code{arglist-close}, @code{brace-list-close}, @code{arglist-cont} and
4353 @code{arglist-cont-nonempty}.
4354 @end defun
4356 @comment ------------------------------------------------------------
4358 @defun c-lineup-arglist-operators
4359 @findex lineup-arglist-operators (c-)
4360 Line up lines starting with an infix operator under the open paren.
4361 Return @code{nil} on lines that don't start with an operator, to leave
4362 those cases to other lineup functions.  Example:
4364 @example
4365 @group
4366 if (  x < 10
4367    || at_limit (x,     @hereFn{c-lineup-arglist-operators}
4368                 list)  @hereFn{c-lineup-arglist-operators@r{ returns nil}}
4369    )
4370 @end group
4371 @end example
4373 Since this function doesn't do anything for lines without an infix
4374 operator you typically want to use it together with some other lineup
4375 settings, e.g., as follows (the @code{arglist-close} setting is just a
4376 suggestion to get a consistent style):
4378 @example
4379 (c-set-offset 'arglist-cont
4380               '(c-lineup-arglist-operators 0))
4381 (c-set-offset 'arglist-cont-nonempty
4382               '(c-lineup-arglist-operators c-lineup-arglist))
4383 (c-set-offset 'arglist-close
4384               '(c-lineup-arglist-close-under-paren))
4385 @end example
4387 @workswith @code{arglist-cont}, @code{arglist-cont-nonempty}.
4388 @end defun
4390 @comment ------------------------------------------------------------
4392 @defun c-lineup-C-comments
4393 @findex lineup-C-comments (c-)
4394 Line up C block comment continuation lines.  Various heuristics are used
4395 to handle most of the common comment styles.  Some examples:
4397 @example
4398 @group
4399 /*                 /**               /*
4400  * text             * text             text
4401  */                 */               */
4402 @end group
4403 @end example
4405 @example
4406 @group
4407 /* text            /*                /**
4408    text            ** text            ** text
4409 */                 */                 */
4410 @end group
4411 @end example
4413 @example
4414 @group
4415 /**************************************************
4416  * text
4417  *************************************************/
4418 @end group
4419 @end example
4421 @vindex comment-start-skip
4422 @example
4423 @group
4424 /**************************************************
4425     Free form text comments:
4426  In comments with a long delimiter line at the
4427  start, the indentation is kept unchanged for lines
4428  that start with an empty comment line prefix.  The
4429  delimiter line is whatever matches the
4430  @code{comment-start-skip} regexp.
4431 **************************************************/
4432 @end group
4433 @end example
4435 The style variable @code{c-comment-prefix-regexp} is used to recognize
4436 the comment line prefix, e.g., the @samp{*} that usually starts every
4437 line inside a comment.
4439 @workswith The @code{c} syntactic symbol.
4440 @end defun
4442 @comment ------------------------------------------------------------
4444 @defun c-lineup-cascaded-calls
4445 @findex lineup-cascaded-calls (c-)
4446 Line up ``cascaded calls'' under each other.  If the line begins with
4447 @code{->} or @code{.} and the preceding line ends with one or more
4448 function calls preceded by the same token, then the arrow is lined up
4449 with the first of those tokens.  E.g:
4451 @example
4452 @group
4453 r = proc->add(17)->add(18)
4454         ->add(19) +         @hereFn{c-lineup-cascaded-calls}
4455   offset;                   @hereFn{c-lineup-cascaded-calls@r{ (inactive)}}
4456 @end group
4457 @end example
4459 In any other situation @code{nil} is returned to allow use in list
4460 expressions.
4462 @workswith @code{topmost-intro-cont}, @code{statement-cont},
4463 @code{arglist-cont}, @code{arglist-cont-nonempty}.
4464 @end defun
4466 @comment ------------------------------------------------------------
4468 @defun c-lineup-close-paren
4469 @findex lineup-close-paren (c-)
4470 Line up the closing paren under its corresponding open paren if the
4471 open paren is followed by code.  If the open paren ends its line, no
4472 indentation is added.  E.g:
4474 @example
4475 @group
4476 main (int,
4477       char **           
4478      )                @hereFn{c-lineup-close-paren}
4479 @end group
4480 @end example
4482 @noindent
4485 @example
4486 @group
4487 main (
4488     int, char **
4489 )                     @hereFn{c-lineup-close-paren}
4490 @end group
4491 @end example
4493 As a special case, if a brace block is opened at the same line as the
4494 open parenthesis of the argument list, the indentation is
4495 @code{c-basic-offset} instead of the open paren column.  See
4496 @code{c-lineup-arglist} for further discussion of this ``DWIM'' measure.
4498 @workswith All @code{*-close} symbols.
4499 @end defun
4501 @comment ------------------------------------------------------------
4503 @defun c-lineup-comment
4504 @findex lineup-comment (c-)
4505 Line up a comment-only line according to the style variable
4506 @code{c-comment-only-line-offset}.  If the comment is lined up with a
4507 comment starter on the previous line, that alignment is preserved.
4509 @defopt c-comment-only-line-offset
4510 @vindex comment-only-line-offset (c-)
4511 This style variable specifies the extra offset for the line.  It can
4512 contain an integer or a cons cell of the form
4514 @example
4515 (@r{@var{non-anchored-offset}} . @r{@var{anchored-offset}})
4516 @end example
4518 @noindent
4519 where @var{non-anchored-offset} is the amount of offset given to
4520 non-column-zero anchored lines, and @var{anchored-offset} is the amount
4521 of offset to give column-zero anchored lines.  Just an integer as value
4522 is equivalent to @code{(@r{@var{value}} . -1000)}.
4523 @end defopt
4525 @workswith @code{comment-intro}.
4526 @end defun
4528 @comment ------------------------------------------------------------
4530 @defun c-lineup-cpp-define
4531 @findex lineup-cpp-define (c-)
4532 Line up macro continuation lines according to the indentation of the
4533 construct preceding the macro.  E.g:
4535 @example
4536 @group
4537 const char msg[] =    @hereFn{@r{The beginning of the preceding construct.}}
4538   \"Some text.\";
4540 #define X(A, B)  \
4541 do @{             \    @hereFn{c-lineup-cpp-define}
4542   printf (A, B); \
4543 @} while (0)
4544 @end group
4545 @end example
4547 @noindent
4548 and:
4550 @example
4551 @group
4552 int dribble() @{
4553   if (!running)       @hereFn{@r{The beginning of the preceding construct.}}
4554     error(\"Not running!\");
4556 #define X(A, B)    \
4557   do @{             \  @hereFn{c-lineup-cpp-define}
4558     printf (A, B); \
4559   @} while (0)
4560 @end group
4561 @end example
4563 If @code{c-syntactic-indentation-in-macros} is non-@code{nil}, the
4564 function returns the relative indentation to the macro start line to
4565 allow accumulation with other offsets.  e.g., in the following cases,
4566 @code{cpp-define-intro} is combined with the
4567 @code{statement-block-intro} that comes from the @samp{do @{} that hangs
4568 on the @samp{#define} line:
4570 @example
4571 @group
4572 const char msg[] =
4573   \"Some text.\";
4575 #define X(A, B) do @{ \
4576   printf (A, B);     \  @hereFn{c-lineup-cpp-define}
4577   this->refs++;      \
4578 @} while (0)             @hereFn{c-lineup-cpp-define}
4579 @end group
4580 @end example
4582 @noindent
4583 and:
4585 @example
4586 @group
4587 int dribble() @{
4588   if (!running)
4589     error(\"Not running!\");
4591 #define X(A, B) do @{ \
4592     printf (A, B);   \  @hereFn{c-lineup-cpp-define}
4593     this->refs++;    \
4594   @} while (0)           @hereFn{c-lineup-cpp-define}
4595 @end group
4596 @end example
4598 The relative indentation returned by @code{c-lineup-cpp-define} is zero
4599 and two, respectively, on the two lines in each of these examples.  They
4600 are then added to the two column indentation that
4601 @code{statement-block-intro} gives in both cases here.
4603 If the relative indentation is zero, then @code{nil} is returned
4604 instead.  That is useful in a list expression to specify the default
4605 indentation on the top level.
4607 If @code{c-syntactic-indentation-in-macros} is @code{nil} then this
4608 function keeps the current indentation, except for empty lines (ignoring
4609 the ending backslash) where it takes the indentation from the closest
4610 preceding nonempty line in the macro.  If there's no such line in the
4611 macro then the indentation is taken from the construct preceding it, as
4612 described above.
4614 @workswith @code{cpp-define-intro}.
4615 @end defun
4617 @comment ------------------------------------------------------------
4619 @defun c-lineup-dont-change
4620 @findex lineup-dont-change (c-)
4621 This lineup function makes the line stay at whatever indentation it
4622 already has; think of it as an identity function for lineups.
4624 @workswith Any syntactic symbol.
4625 @end defun
4627 @comment ------------------------------------------------------------
4629 @defun c-lineup-gcc-asm-reg
4630 @findex lineup-gcc-asm-reg (c-)
4631 Line up a gcc asm register under one on a previous line.
4633 @example
4634 @group
4635     asm ("foo %1, %0\n"
4636          "bar %0, %1"
4637          : "=r" (w),
4638            "=r" (x)
4639          :  "0" (y),
4640             "1" (z));
4641 @end group
4642 @end example
4644 The @samp{x} line is aligned to the text after the @samp{:} on the
4645 @samp{w} line, and similarly @samp{z} under @samp{y}.
4647 This is done only in an @samp{asm} or @samp{__asm__} block, and only to
4648 those lines mentioned.  Anywhere else @code{nil} is returned.  The usual
4649 arrangement is to have this routine as an extra feature at the start of
4650 arglist lineups, e.g.
4652 @example
4653 (c-lineup-gcc-asm-reg c-lineup-arglist)
4654 @end example
4656 @workswith @code{arglist-cont}, @code{arglist-cont-nonempty}.
4657 @end defun
4659 @comment ------------------------------------------------------------
4661 @defun c-lineup-inexpr-block
4662 @findex lineup-inexpr-block (c-)
4663 This can be used with the in-expression block symbols to indent the
4664 whole block to the column where the construct is started.  e.g., for Java
4665 anonymous classes, this lines up the class under the @samp{new} keyword,
4666 and in Pike it lines up the lambda function body under the @samp{lambda}
4667 keyword.  Returns @code{nil} if the block isn't part of such a
4668 construct.
4670 @workswith @code{inlambda}, @code{inexpr-statement},
4671 @code{inexpr-class}.
4672 @end defun
4674 @comment ------------------------------------------------------------
4676 @defun c-lineup-java-inher
4677 @findex lineup-java-inher (c-)
4678 Line up Java implements and extends declarations.  If class names
4679 follow on the same line as the @samp{implements}/@samp{extends}
4680 keyword, they are lined up under each other.  Otherwise, they are
4681 indented by adding @code{c-basic-offset} to the column of the keyword.
4682 E.g:
4684 @example
4685 @group
4686 class Foo
4687     extends           
4688         Bar           @hereFn{c-lineup-java-inher}
4689     @sssTBasicOffset{}
4690 @end group
4691 @end example
4693 @noindent
4696 @example
4697 @group
4698 class Foo
4699     extends Cyphr,
4700             Bar       @hereFn{c-lineup-java-inher}
4701 @end group
4702 @end example
4704 @workswith @code{inher-cont}.
4705 @end defun
4707 @comment ------------------------------------------------------------
4709 @defun c-lineup-java-throws
4710 @findex lineup-java-throws (c-)
4711 Line up Java throws declarations.  If exception names follow on the
4712 same line as the throws keyword, they are lined up under each other.
4713 Otherwise, they are indented by adding @code{c-basic-offset} to the
4714 column of the @samp{throws} keyword.  The @samp{throws} keyword itself
4715 is also indented by @code{c-basic-offset} from the function declaration
4716 start if it doesn't hang.  E.g:
4718 @example
4719 @group
4720 int foo()
4721     throws            @hereFn{c-lineup-java-throws}
4722         Bar           @hereFn{c-lineup-java-throws}
4723 @sssTsssTBasicOffset{}
4724 @end group
4725 @end example
4727 @noindent
4730 @example
4731 @group
4732 int foo() throws Cyphr,
4733                  Bar,    @hereFn{c-lineup-java-throws}
4734                  Vlod    @hereFn{c-lineup-java-throws}
4735 @end group
4736 @end example
4738 @workswith @code{func-decl-cont}.
4739 @end defun
4741 @comment ------------------------------------------------------------
4743 @defun c-lineup-knr-region-comment
4744 @findex lineup-knr-region-comment (c-)
4745 Line up a comment in the ``K&R region'' with the declaration.  That is
4746 the region between the function or class header and the beginning of the
4747 block.  E.g:
4749 @example
4750 @group
4751 int main()
4752 /* Called at startup. */  @hereFn{c-lineup-knr-region-comment}
4754   return 0;
4756 @end group
4757 @end example
4759 Return @code{nil} if called in any other situation, to be useful in list
4760 expressions.
4762 @workswith @code{comment-intro}.
4763 @end defun
4765 @comment ------------------------------------------------------------
4767 @defun c-lineup-math
4768 @findex lineup-math (c-)
4769 Line up the current line to after the equal sign on the first line in the
4770 statement.  If there isn't any, indent with @code{c-basic-offset}.  If
4771 the current line contains an equal sign too, try to align it with the
4772 first one.
4774 @workswith @code{topmost-intro-cont}, @code{statement-cont},
4775 @code{arglist-cont}, @code{arglist-cont-nonempty}.
4776 @end defun
4778 @comment ------------------------------------------------------------
4780 @defun c-lineup-multi-inher
4781 @findex lineup-multi-inher (c-)
4782 Line up the classes in C++ multiple inheritance clauses and member
4783 initializers under each other.  E.g:
4785 @example
4786 @group
4787 Foo::Foo (int a, int b):
4788     Cyphr (a),
4789     Bar (b)           @hereFn{c-lineup-multi-inher}
4790 @end group
4791 @end example
4793 @noindent
4796 @example
4797 @group
4798 class Foo
4799     : public Cyphr,
4800       public Bar      @hereFn{c-lineup-multi-inher}
4801 @end group
4802 @end example
4804 @noindent
4807 @example
4808 @group
4809 Foo::Foo (int a, int b)
4810     : Cyphr (a)
4811     , Bar (b)         @hereFn{c-lineup-multi-inher}
4812 @end group
4813 @end example
4815 @workswith @code{inher-cont}, @code{member-init-cont}.
4816 @end defun
4818 @comment ------------------------------------------------------------
4820 @defun c-lineup-ObjC-method-call
4821 @findex lineup-ObjC-method-call (c-)
4822 For Objective-C code, line up selector args as Emacs Lisp mode does
4823 with function args: go to the position right after the message receiver,
4824 and if you are at the end of the line, indent the current line
4825 c-basic-offset columns from the opening bracket; otherwise you are
4826 looking at the first character of the first method call argument, so
4827 lineup the current line with it.
4829 @workswith @code{objc-method-call-cont}.
4830 @end defun
4832 @comment ------------------------------------------------------------
4834 @defun c-lineup-ObjC-method-args
4835 @findex lineup-ObjC-method-args (c-)
4836 For Objective-C code, line up the colons that separate args.  The colon
4837 on the current line is aligned with the one on the first line.
4839 @workswith @code{objc-method-args-cont}.
4840 @end defun
4842 @comment ------------------------------------------------------------
4844 @defun c-lineup-ObjC-method-args-2
4845 @findex lineup-ObjC-method-args-2 (c-)
4846 Similar to @code{c-lineup-ObjC-method-args} but lines up the colon on
4847 the current line with the colon on the previous line.
4849 @workswith @code{objc-method-args-cont}.
4850 @end defun
4852 @comment ------------------------------------------------------------
4854 @defun c-lineup-runin-statements
4855 @findex lineup-runin-statements (c-)
4856 Line up statements for coding standards which place the first statement
4857 in a block on the same line as the block opening brace@footnote{Run-in
4858 style doesn't really work too well.  You might need to write your own
4859 custom indentation functions to better support this style.}.  E.g:
4861 @example
4862 @group
4863 int main()
4864 @{ puts ("Hello!");
4865   return 0;           @hereFn{c-lineup-runin-statements}
4867 @end group
4868 @end example
4870 If there is no statement after the opening brace to align with,
4871 @code{nil} is returned.  This makes the function usable in list
4872 expressions.
4874 @workswith The @code{statement} syntactic symbol.
4875 @end defun
4877 @comment ------------------------------------------------------------
4879 @defun c-lineup-streamop
4880 @findex lineup-streamop (c-)
4881 Line up C++ stream operators (i.e., @samp{<<} and @samp{>>}).
4883 @workswith @code{stream-op}.
4884 @end defun
4886 @comment ------------------------------------------------------------
4888 @defun c-lineup-string-cont
4889 @findex lineup-string-cont (c-)
4890 Line up a continued string under the one it continues.  A continued
4891 string in this sense is where a string literal follows directly after
4892 another one.  E.g:
4894 @example
4895 @group
4896 result = prefix + "A message "
4897                   "string.";    @hereFn{c-lineup-string-cont}
4898 @end group
4899 @end example
4901 @code{nil} is returned in other situations, to allow stacking with other
4902 lineup functions.
4904 @workswith @code{topmost-intro-cont}, @code{statement-cont},
4905 @code{arglist-cont}, @code{arglist-cont-nonempty}.
4906 @end defun
4908 @comment ------------------------------------------------------------
4910 @defun c-lineup-template-args
4911 @findex lineup-template-args (c-)
4912 Line up the arguments of a template argument list under each other, but
4913 only in the case where the first argument is on the same line as the
4914 opening @samp{<}.
4916 To allow this function to be used in a list expression, @code{nil} is
4917 returned if there's no template argument on the first line.
4919 @workswith @code{template-args-cont}.
4920 @end defun
4922 @comment ------------------------------------------------------------
4924 @defun c-lineup-topmost-intro-cont
4925 @findex lineup-topmost-intro-cont (c-)
4926 Line up declaration continuation lines zero or one indentation
4927 step@footnote{This function is mainly provided to mimic the behavior of
4928 CC Mode 5.28 and earlier where this case wasn't handled consistently so
4929 that those lines could be analyzed as either topmost-intro-cont or
4930 statement-cont.  It's used for @code{topmost-intro-cont} by default, but
4931 you might consider using @code{+} instead.}.  For lines preceding a
4932 definition, zero is used.  For other lines, @code{c-basic-offset} is
4933 added to the indentation.  E.g:
4935 @example
4936 @group
4938 neg (int i)           @hereFn{c-lineup-topmost-intro-cont}
4940     return -i;
4942 @end group
4943 @end example
4945 @noindent
4948 @example
4949 @group
4950 struct
4951 larch                 @hereFn{c-lineup-topmost-intro-cont}
4953     double height;
4955     the_larch,        @hereFn{c-lineup-topmost-intro-cont}
4956     another_larch;    @hereFn{c-lineup-topmost-intro-cont}
4957 @sssTBasicOffset{}
4958 @end group
4959 @end example
4961 @noindent
4964 @example
4965 @group
4966 struct larch
4967 the_larch,            @hereFn{c-lineup-topmost-intro-cont}
4968     another_larch;    @hereFn{c-lineup-topmost-intro-cont}
4969 @end group
4970 @end example
4972 @workswith @code{topmost-intro-cont}.
4973 @end defun
4975 @comment ------------------------------------------------------------
4977 @defun c-lineup-whitesmith-in-block
4978 @findex lineup-whitesmith-in-block (c-)
4979 Line up lines inside a block in Whitesmith style.  It's done in a way
4980 that works both when the opening brace hangs and when it doesn't.  E.g:
4982 @example
4983 @group
4984 something
4985     @{
4986     foo;              @hereFn{c-lineup-whitesmith-in-block}
4987     @}
4988 @end group
4989 @end example
4991 @noindent
4994 @example
4995 @group
4996 something @{
4997     foo;              @hereFn{c-lineup-whitesmith-in-block}
4998     @}
4999 @sssTBasicOffset{}
5000 @end group
5001 @end example
5003 In the first case the indentation is kept unchanged, in the second
5004 @code{c-basic-offset} is added.
5006 @workswith @code{defun-close}, @code{defun-block-intro},
5007 @code{block-close}, @code{brace-list-close}, @code{brace-list-intro},
5008 @code{statement-block-intro} and all @code{in*} symbols,
5009 e.g., @code{inclass} and @code{inextern-lang}.
5010 @end defun
5013 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5014 @node AWK Mode, Odds and Ends, Indentation Functions, Top
5015 @comment  node-name,  next,  previous,  up
5016 @chapter Status of AWK Mode
5017 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5019 @dfn{AWK mode} existed until recently in the file @file{awk-mode.el}
5020 as a mode derived from c-mode.  It had not been actively maintained to
5021 keep pace with the newer @ccmode{}, and its indentation mechanism no
5022 longer worked satisfactorally.
5024 The current AWK mode is based around the GNU implementation,
5025 @emph{GAWK version 3.1.0}, though it should work pretty well with any
5026 AWK.  It has now been updated and integrated into @ccmode{} to a
5027 substantial extent, though as yet not all the features of @ccmode{}
5028 have been adapted to support it.
5030 If your (X)Emacs is set up to use the old file @file{awk-mode.elc}
5031 (which will usually be the case if you have obtained this @ccmode{}
5032 independently of (X)Emacs itself), or if you are not sure, insert the
5033 following form into your @file{.emacs} or @file{init.el} so that the new
5034 AWK mode will be used instead:
5036 @example
5037 (autoload 'awk-mode "cc-mode" nil t)
5038 @end example
5040 You can check which AWK mode you are running by displaying the mode
5041 documentation string with @kbd{C-h m} from an AWK buffer.  The newer
5042 mode's doc string contains @code{To submit a problem report, enter
5043 `C-c C-b'} near the top of the doc string where the older mode has
5044 @code{This is much like C mode except ....}.
5046 Since this newer AWK mode makes essential use of a relatively new
5047 Emacs Lisp feature@footnote{Specifically, the @code{syntax-table} text
5048 property.}, you need either GNU Emacs 20.1 (or later) or XEmacs 21.4
5049 (or later) to use it.  If your Emacs version is earlier than one of
5050 these, the older @file{awk-mode.el} will get loaded and run in place
5051 of the AWK mode described here, even when you have put the above
5052 @code{autoload} form into your @file{.emacs} or @file{init.el}.
5053 Upgrading your (X)Emacs is strongly recommended if this is the case.
5055 Here is an overview of which @ccmode{} features currently work with
5056 AWK mode and which don't:
5058 @table @asis
5059 @item Indentation Engine
5060 The @ccmode{} indentation engine fully supports AWK mode.
5061 @xref{Indentation Engine}.
5063 AWK mode handles code formatted in the conventional AWK fashion:
5064 @samp{@{}s which start actions, user-defined functions, or compound
5065 statements are placed on the same line as the associated construct; the
5066 matching @samp{@}}s are normally placed under the start of the
5067 respective pattern, function definition, or structured statement.
5068 @c Add in a bit about the @samp{@}} being on the same line when the
5069 @c contents are short.
5071 The predefined indentation functions (@pxref{Indentation Functions})
5072 haven't yet been adapted for AWK mode, though some of them may work
5073 serendipitously.  There shouldn't be any problems writing custom
5074 indentation functions for AWK mode.
5076 The command @kbd{C-c C-q} (@code{c-indent-defun}) hasn't yet been
5077 adapted for AWK, though in practice it works properly nearly all the
5078 time.  Should it fail, explicitly set the region around the function
5079 (using @kbd{C-u C-SPC}: @kbd{C-M-h} probably won't work either) then do
5080 @kbd{C-M-\} (@code{indent-region}).
5082 @item Font Locking
5083 There is a single level of font locking in AWK mode, rather than the
5084 three distinct levels the other modes have.  There are several
5085 idiosyncrasies in AWK mode's font-locking due to the peculiarities of
5086 the AWK language itself.  @xref{AWK Mode Font Locking}.
5088 @item Comment Commands
5089 @kbd{M-;} (@code{indent-for-comment}) works fine.  None of the other
5090 @ccmode{} comment formatting commands have yet been adapted for AWK
5091 mode.  @xref{Text Filling and Line Breaking}.
5093 @item Movement Commands
5094 Most of the movement commands work in AWK mode.  The most important
5095 exceptions are @kbd{M-a} (@code{c-beginning-of-statement}) and
5096 @kbd{M-e} (@code{c-end-of-statement}) which haven't yet been adapted.
5098 The notion of @dfn{defun} has been augmented to include pattern-action
5099 pairs.  See @ref{AWK Mode Defuns} for a description of commands which
5100 work on AWK ``defuns''.
5102 Since there is no preprocessor in AWK, the commands which move to
5103 preprocessor directives (e.g., @code{c-up-conditional}) are meaningless
5104 in AWK mode and are not bound in the AWK mode keymap.
5106 @item Auto-newline Insertion and Clean-ups
5107 Auto-newline insertion hasn't yet been adapted for AWK.  Some of the
5108 clean-ups can actually convert good AWK code into syntactically
5109 invalid code.
5111 If auto-newline or its associated clean-ups are enabled generally for
5112 the modes in @ccmode{}, you are strongly recommended to disable them
5113 in the AWK Mode hook.  @xref{Initialising AWK Mode}.
5115 The clean-up @code{space-before-funcall}, which is independent of
5116 auto-newline, should never be active in AWK mode (since inserting a
5117 space between a user function's name and its opening @samp{(} makes
5118 the call syntactically invalid).  If necessary, this should be
5119 disabled in the AWK Mode hook.  @xref{Initialising AWK Mode}.
5121 @end table
5123 @menu
5124 * Initialising AWK Mode::
5125 * AWK Mode Font Locking::
5126 * AWK Mode Defuns::
5127 @end menu
5130 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5131 @node Initialising AWK Mode, AWK Mode Font Locking, , AWK Mode
5132 @comment  node-name,  next,  previous,  up
5133 @section AWK mode - What to put in your @file{.emacs} or @file{init.el}
5134 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5136 Much of the AWK mode initialization can, of course, be done by the
5137 @ccmode{} general initialization procedure.  You may want to use certain
5138 @ccmode{} features such as @code{auto-newline} and @code{clean-ups} in
5139 the other modes, and you might thus have enabled them in a
5140 @code{c-mode-common-hook} function, as described in @ref{Sample .emacs File}.
5141 These features have not yet been amended for AWK mode, and far from
5142 being useful, can be irritating in AWK mode or actually make AWK code
5143 syntactically invalid.  Adding the following code to your
5144 @file{.emacs} or @file{init.el} file will disable them for AWK mode.
5146 @example
5147 (defun my-awk-mode-hook ()
5148   "Disable certain @ccmode{} features which could impair AWK mode."
5149   (c-toggle-auto-state -1)       ; disable automatic insertions of newlines
5150   (if (memq 'space-before-funcall c-cleanup-list)
5151       (setq c-cleanup-list ; don't automatically insert a space into "foo("
5152             (remove 'space-before-funcall c-cleanup-list))))
5153 (add-hook 'awk-mode-hook 'my-awk-mode-hook)
5154 @end example
5156 Naturally you can add your own AWK-specific customizations to this
5157 function.  @xref{Hooks}.
5160 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5161 @node AWK Mode Font Locking, AWK Mode Defuns, Initialising AWK Mode, AWK Mode
5162 @comment  node-name,  next,  previous,  up
5163 @section AWK Mode Font Locking
5164 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5166 The general appearance of font-locking in AWK mode is much like in any
5167 other programming mode.  @xref{Faces For Font Lock,,,elisp}.
5169 The following faces are, however, used in a non-standard fashion in
5170 AWK mode:
5172 @table @asis
5173 @item @code{font-lock-variable-name-face}
5174 This face was intended for variable declarations.  Since variables are
5175 not declared in AWK, this face is used instead for AWK system
5176 variables (such as @code{NF}) and ``Special File Names'' (such as
5177 @code{"/dev/stderr"}).
5179 @item @code{font-lock-builtin-face} (Emacs)/@code{font-lock-preprocessor-face} (XEmacs)
5180 This face is normally used for preprocessor directives in @ccmode{}.
5181 There are no such things in AWK, so this face is used instead for
5182 standard functions (such as @code{match}).
5184 @item @code{font-lock-string-face}
5185 As well as being used for strings, including localizable strings,
5186 (delimited by @samp{"} and @samp{_"}), this face is also used for AWK
5187 regular expressions (delimited by @samp{/}).
5189 @item @code{font-lock-warning-face} (Emacs)/@code{c-invalid-face} (XEmacs)
5190 This face highlights the following syntactically invalid AWK
5191 constructs:
5193 @itemize @bullet
5194 @item
5195 An unterminated string or regular expression.  Here the opening
5196 delimiter (@samp{"} or @samp{/} or @samp{_"}) is displayed in
5197 @code{font-lock-warning-face}.  This is most noticeable when typing in a
5198 new string/regular expression into a buffer, when the warning-face
5199 serves as a continual reminder to terminate the construct.
5201 AWK mode fontifies unterminated strings/regular expressions
5202 differently from other modes: Only the text up to the end of the line
5203 is fontified as a string (escaped newlines being handled correctly),
5204 rather than the text up to the next string quote.
5206 @item
5207 A space between the function name and opening parenthesis when calling
5208 a user function.  The last character of the function name and the
5209 opening parenthesis are highlighted.  This font-locking rule will
5210 spuriously highlight a valid concatenation expression where an
5211 identifier precedes a parenthesised expression.  Unfortunately.
5213 @item
5214 Whitespace following the @samp{\} in what otherwise looks like an
5215 escaped newline.  The @samp{\} is highlighted.
5216 @end itemize
5217 @end table
5220 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5221 @node AWK Mode Defuns,  , AWK Mode Font Locking, AWK Mode
5222 @comment  node-name,  next,  previous,  up
5223 @section AWK Mode Defuns
5224 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5226 In AWK mode, @dfn{defun} means either a user-defined function or a
5227 pattern-action pair.  Either the pattern or the action may be
5228 implicit.
5230 The beginning of a defun is recognised heuristically as, more or less,
5231 code which begins in column zero.  Having the @samp{@{} in column zero,
5232 as is suggested for some modes, is neither necessary nor helpful in AWK
5233 mode.
5235 More precisely, the beginning of a defun is code which begins in
5236 column zero, and which isn't a closing brace, a comment, or a
5237 continuation of the previous line.  Code is the @dfn{continuation of
5238 the previous line} when that line is syntactically incomplete, for
5239 example when it ends with @samp{@{} or an escaped newline.
5241 The end of a defun is the @samp{@}} which matches the @samp{@{} (if
5242 any) at the beginning of the action or function body, or the EOL or
5243 @samp{;} which marks an implicit action.  Although this @samp{@}} is
5244 usually placed in column zero, AWK mode doesn't need it to be placed
5245 there.
5247 @table @asis
5248 @item @kbd{C-M-a} @code{c-awk-beginning-of-defun}
5249 @itemx @kbd{C-M-e} @code{c-awk-end-of-defun}
5250 @findex c-awk-beginning-of-defun
5251 @findex awk-beginning-of-defun (c-)
5252 @findex c-awk-end-of-defun
5253 @findex awk-end-of-defun (c-)
5254 Move point back to the beginning or forward to the end of the current
5255 AWK defun.  These functions can take prefix-arguments, their
5256 functionality being entirely equivalent to @code{beginning-of-defun}
5257 and @code{end-of-defun}.  @xref{Moving by Defuns,,,emacs}.
5259 @item @kbd{C-M-h} @code{c-mark-function}
5260 This works fine with AWK defuns.  @xref{Indentation Commands}.
5261 @end table
5264 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5265 @node    Odds and Ends, Performance Issues, AWK Mode, Top
5266 @comment node-name, next, previous, up
5267 @chapter Odds and Ends
5268 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5270 The stuff that didn't fit in anywhere else is documented here.
5272 @defopt c-require-final-newline
5273 @vindex require-final-newline (c-)
5274 Controls whether a final newline is ensured when the file is saved.  The
5275 value is an association list that for each language mode specifies the
5276 value to give to @code{require-final-newline} at mode initialization;
5277 see that variable for details about the value.  If a language isn't
5278 present on the association list, CC Mode won't touch
5279 @code{require-final-newline} in buffers for that language.
5281 The default is to set @code{require-final-newline} to @code{t} in the
5282 languages that mandates that source files should end with newlines,
5283 i.e., C, C++ and Objective-C.
5284 @end defopt
5286 @defopt c-echo-syntactic-information-p
5287 @vindex echo-syntactic-information-p (c-)
5288 If non-@code{nil}, the syntactic analysis for the current line is shown
5289 in the echo area when it's indented (unless
5290 @code{c-syntactic-indentation} is @code{nil}).  That's useful when
5291 finding out which syntactic symbols to modify to get the indentation you
5292 want.
5293 @end defopt
5295 @defopt c-report-syntactic-errors
5296 @vindex report-syntactic-errors (c-)
5297 If non-@code{nil}, certain syntactic errors are reported with a ding and
5298 a message, for example when an @code{else} is indented for which there
5299 is no corresponding @code{if}.
5301 Note however that @ccmode{} doesn't make any special effort to check for
5302 syntactic errors; that's the job of the compiler.  The reason it can
5303 report cases like the one above is that it can't find the correct
5304 anchoring position to indent the line in that case.
5305 @end defopt
5308 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5309 @node    Performance Issues, Limitations and Known Bugs, Odds and Ends, Top
5310 @comment node-name, next, previous, up
5311 @chapter Performance Issues
5312 @cindex performance
5313 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5315 @comment FIXME: (ACM, 2003/5/24).  Check whether AWK needs mentioning here.
5317 C and its derivative languages are highly complex creatures.  Often,
5318 ambiguous code situations arise that require @ccmode{} to scan large
5319 portions of the buffer to determine syntactic context.  Such
5320 pathological code can cause @ccmode{} to perform fairly badly.  This
5321 section gives some insight in how @ccmode{} operates, how that interacts
5322 with some coding styles, and what you can use to improve performance.
5324 The overall goal is that @ccmode{} shouldn't be overly slow (i.e., take
5325 more than a fraction of a second) in any interactive operation.
5326 i.e., it's tuned to limit the maximum response time in single operations,
5327 which sometimes is at the expense of batch-like operations like
5328 reindenting whole blocks.  If you find that @ccmode{} gradually gets
5329 slower and slower in certain situations, perhaps as the file grows in
5330 size or as the macro or comment you're editing gets bigger, then chances
5331 are that something isn't working right.  You should consider reporting
5332 it, unless it's something that's mentioned in this section.
5334 Because @ccmode{} has to scan the buffer backwards from the current
5335 insertion point, and because C's syntax is fairly difficult to parse in
5336 the backwards direction, @ccmode{} often tries to find the nearest
5337 position higher up in the buffer from which to begin a forward scan
5338 (it's typically an opening or closing parethesis of some kind).  The
5339 farther this position is from the current insertion point, the slower it
5340 gets.
5342 @findex beginning-of-defun
5343 @findex defun-prompt-regexp
5344 One of the simplest things you can do to reduce scan time, is make sure
5345 any brace that opens a top-level construct@footnote{e.g., a function in
5346 C, or outermost class definition in C++ or Java.} always appears in the
5347 leftmost column.  This is actually an Emacs constraint, as embodied in
5348 the @code{beginning-of-defun} function which @ccmode{} uses heavily.  If
5349 you hang top-level open braces on the right side of the line, then you
5350 might want to set the variable @code{defun-prompt-regexp} to something
5351 reasonable, however that ``something reasonable'' is difficult to
5352 define, so @ccmode{} doesn't do it for you.
5354 @vindex c-Java-defun-prompt-regexp
5355 @vindex Java-defun-prompt-regexp (c-)
5356 A special note about @code{defun-prompt-regexp} in Java mode: The common
5357 style is to hang the opening braces of functions and classes on the
5358 right side of the line, and that doesn't work well with the Emacs
5359 approach.  @ccmode{} comes with a variable
5360 @code{c-Java-defun-prompt-regexp} which tries to define a regular
5361 expression usable for this style, but there are problems with it.  In
5362 some cases it can cause @code{beginning-of-defun} to hang@footnote{This
5363 has been observed in Emacs 19.34 and XEmacs 19.15.}.  For this reason,
5364 it is not used by default, but if you feel adventurous, you can set
5365 @code{defun-prompt-regexp} to it in your mode hook.  In any event,
5366 setting and relying on @code{defun-prompt-regexp} will definitely slow
5367 things down because (X)Emacs will be doing regular expression searches a
5368 lot, so you'll probably be taking a hit either way!
5370 @ccmode{} maintains a cache of the opening parentheses of the blocks
5371 surrounding the point, and it adapts that cache as the point is moved
5372 around.  That means that in bad cases it can take noticeable time to
5373 indent a line in a new surrounding, but after that it gets fast as long
5374 as the point isn't moved far off.  The farther the point is moved, the
5375 less useful is the cache.  Since editing typically is done in ``chunks''
5376 rather than on single lines far apart from each other, the cache
5377 typically gives good performance even when the code doesn't fit the
5378 Emacs approach to finding the defun starts.
5380 @vindex c-enable-xemacs-performance-kludge-p
5381 @vindex enable-xemacs-performance-kludge-p (c-)
5382 XEmacs users can set the variable
5383 @code{c-enable-xemacs-performance-kludge-p} to non-@code{nil}.  This
5384 tells @ccmode{} to use XEmacs-specific built-in functions which, in some
5385 circumstances, can locate the top-most opening brace much more quickly than
5386 @code{beginning-of-defun}.  Preliminary testing has shown that for
5387 styles where these braces are hung (e.g., most JDK-derived Java styles),
5388 this hack can improve performance of the core syntax parsing routines
5389 from 3 to 60 times.  However, for styles which @emph{do} conform to
5390 Emacs' recommended style of putting top-level braces in column zero,
5391 this hack can degrade performance by about as much.  Thus this variable
5392 is set to @code{nil} by default, since the Emacs-friendly styles should
5393 be more common (and encouraged!).  Note that this variable has no effect
5394 in Emacs since the necessary built-in functions don't exist (in Emacs
5395 21.3 as of this writing in May 2003).
5397 Text properties are used to speed up skipping over syntactic whitespace,
5398 i.e., comments and preprocessor directives.  Indenting a line after a
5399 huge macro definition can be slow the first time, but after that the
5400 text properties are in place and it should be fast (even after you've
5401 edited other parts of the file and then moved back).
5403 Font locking can be a CPU hog, especially the font locking done on
5404 decoration level 3 which tries to be very accurate.  Note that that
5405 level is designed to be used with a font lock support mode that only
5406 fontifies the text that's actually shown, i.e., Lazy Lock or Just-in-time
5407 Lock mode, so make sure you use one of them.  Fontification of a whole
5408 buffer with some thousand lines can often take over a minute.  That is
5409 a known weakness; the idea is that it never should happen.
5411 The most effective way to speed up font locking is to reduce the
5412 decoration level to 2 by setting @code{font-lock-maximum-decoration}
5413 appropriately.  That level is designed to be as pretty as possible
5414 without sacrificing performance.  @xref{Font Locking Preliminaries}, for
5415 more info.
5418 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5419 @node    Limitations and Known Bugs, Frequently Asked Questions, Performance Issues, Top
5420 @comment node-name, next, previous, up
5421 @chapter Limitations and Known Bugs
5422 @cindex limitations
5423 @cindex bugs
5424 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5426 @itemize @bullet
5427 @item
5428 There is no way to apply auto newline settings (@pxref{Auto-newline
5429 Insertion}) on already typed lines.  That's only a feature to ease
5430 interactive editing.
5432 To generalize this issue a bit: @ccmode{} is not intended to be used as
5433 a reformatter for old code in some more or less batch-like way.  With
5434 the exception of some functions like @code{c-indent-region}, it's only
5435 geared to be used interactively to edit new code.  There's currently no
5436 intention to change this goal.
5438 If you want to reformat old code, you're probably better off using some
5439 other tool instead, e.g., @ref{Top, , GNU indent, indent, The `indent'
5440 Manual}, which has more powerful reformatting capabilities than
5441 @ccmode{}.
5443 @item
5444 @vindex signal-error-on-buffer-boundary
5445 XEmacs has a variable called @code{signal-error-on-buffer-boundary}.
5446 It's used as a solution to user interface problems associated with
5447 buffer movement and the @code{zmacs-region} deactivation on errors.
5448 However, setting this variable to a non-default value in XEmacs 19 and
5449 20 had the deleterious side effect of breaking many built-in primitive
5450 functions.  @strong{Do not set this variable to @code{nil} in XEmacs
5451 19 and 20}; you will cause serious problems in @ccmode{} and probably
5452 other XEmacs packages!  In XEmacs 21 the effects of the variable is
5453 limited to some functions that are only used interactively, so it's
5454 not a problem there.
5455 @end itemize
5458 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5459 @node    Frequently Asked Questions, Getting the Latest CC Mode Release, Limitations and Known Bugs, Top
5460 @comment node-name, next, previous, up
5461 @appendix Frequently Asked Questions
5462 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5464 @itemize @bullet
5465 @item
5466 @kindex C-x h
5467 @kindex C-M-\
5468 @emph{How do I reindent the whole file?}
5470 Visit the file and hit @kbd{C-x h} to mark the whole buffer. Then hit
5471 @kbd{C-M-\}.
5473 @item
5474 @kindex C-M-q
5475 @kindex C-M-u
5476 @emph{How do I reindent the current block?}
5478 First move to the brace which opens the block with @kbd{C-M-u}, then
5479 reindent that expression with @kbd{C-M-q}.
5481 @item
5482 @kindex RET
5483 @kindex C-j
5484 @emph{Why doesn't the @kbd{RET} key indent the new line?}
5486 Emacs' convention is that @kbd{RET} just adds a newline, and that
5487 @kbd{C-j} adds a newline and indents it.  You can make @kbd{RET} do this
5488 too by adding this to your @code{c-mode-common-hook}:
5490 @example
5491 (define-key c-mode-base-map "\C-m" 'c-context-line-break)
5492 @end example
5494 This is a very common question.  If you want this to be the default
5495 behavior, don't lobby me, lobby RMS!  @t{:-)}
5497 @item
5498 @emph{I put @code{(c-set-offset 'substatement-open 0)} in my
5499 @file{.emacs} file but I get an error saying that @code{c-set-offset}'s
5500 function definition is void.  What's wrong?}
5502 This means that @ccmode{} wasn't loaded into your Emacs session by the
5503 time the @code{c-set-offset} call was reached, most likely because
5504 @ccmode{} is being autoloaded.  Instead of putting the
5505 @code{c-set-offset} line in your top-level @file{.emacs} file, put it in
5506 your @code{c-mode-common-hook}, or simply modify @code{c-offsets-alist}
5507 directly:
5509 @example
5510 (setq c-offsets-alist '((substatement-open . 0)))
5511 @end example
5513 @item
5514 @kindex M-a
5515 @kindex M-e
5516 @emph{@kbd{M-a} and @kbd{M-e} used to move over entire balanced brace
5517 lists, but now they move into blocks.  How do I get the old behavior
5518 back?}
5520 Use @kbd{C-M-f} and @kbd{C-M-b} to move over balanced brace blocks.  Use
5521 @kbd{M-a} and @kbd{M-e} to move by statements, which will also move into
5522 blocks.
5524 @item
5525 @emph{Whenever I try to indent a line or type an ``electric'' key such
5526 as @kbd{;}, @kbd{@{}, or @kbd{@}}, I get an error that look like this:
5527 @code{Invalid function: (macro . #[...}. What gives?}
5529 This is a common error when @ccmode{} hasn't been compiled correctly,
5530 especially under Emacs 19.34@footnote{Technically, it's because some
5531 macro wasn't defined during the compilation, so the byte compiler put
5532 in function calls instead of the macro expansions. Later, when the
5533 interpreter tries to call the macro as a function, it shows this
5534 (somewhat cryptic) error message.}. If you are using the standalone
5535 @ccmode{} distribution, try recompiling it according to the instructions
5536 in the @file{README} file.
5538 @item
5539 @cindex open paren in column zero
5540 @emph{I have an open paren character at column zero inside a comment or
5541 multiline string literal, and it causes the fontification and/or
5542 indentation to go haywire.  What gives?}
5544 It's due to the ad-hoc rule in (X)Emacs that such open parens always
5545 start defuns (which translates to functions, classes, namespaces or any
5546 other top-level block constructs in the @ccmode{} languages).
5547 @xref{Left Margin Paren,,, emacs, The Emacs Editor}, for details
5548 (@xref{Defuns,,, emacs, The Emacs Editor}, in the Emacs 20 manual).
5550 This heuristic is built into the core syntax analysis routines in
5551 (X)Emacs, so it's not really a @ccmode{} issue.  However, in Emacs 21.4
5552 it has become possible to turn it off@footnote{Using the variable
5553 @code{open-paren-in-column-0-is-defun-start}.} and @ccmode{} does so
5554 there since it got its own system to keep track of blocks.
5556 @end itemize
5559 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5560 @node    Getting the Latest CC Mode Release, Mailing Lists and Submitting Bug Reports, Frequently Asked Questions, Top
5561 @comment node-name, next, previous, up
5562 @appendix Getting the Latest CC Mode Release
5563 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5565 @ccmode{} has been standard with all versions of Emacs since 19.34 and
5566 of XEmacs since 19.16.
5568 @cindex web site
5569 Due to release schedule skew, it is likely that all of these Emacsen
5570 have old versions of @ccmode{} and so should be upgraded.  Access to the
5571 @ccmode{} source code, as well as more detailed information on Emacsen
5572 compatibility, etc. are all available on the web site:
5574 @quotation
5575 @uref{http://cc-mode.sourceforge.net/}
5576 @end quotation
5579 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5580 @node    Mailing Lists and Submitting Bug Reports, Sample .emacs File, Getting the Latest CC Mode Release, Top
5581 @comment node-name, next, previous, up
5582 @appendix Mailing Lists and Submitting Bug Reports
5583 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5585 @kindex C-c C-b
5586 @findex c-submit-bug-report
5587 @findex submit-bug-report (c-)
5588 To report bugs, use the @kbd{C-c C-b} (bound to
5589 @code{c-submit-bug-report}) command.  This provides vital information
5590 we need to reproduce your problem.  Make sure you include a concise,
5591 but complete code example.  Please try to boil your example down to
5592 just the essential code needed to reproduce the problem, and include
5593 an exact recipe of steps needed to expose the bug.  Be especially sure
5594 to include any code that appears @emph{before} your bug example, if
5595 you think it might affect our ability to reproduce it.
5597 Please try to produce the problem in an Emacs instance without any
5598 customizations loaded (i.e., start it with the @samp{-q --no-site-file}
5599 arguments).  If it works correctly there, the problem might be caused by
5600 faulty customizations in either your own or your site configuration.  In
5601 that case, we'd appreciate if you isolate the Emacs Lisp code that trigs
5602 the bug and include it in your report.
5604 @cindex bug report mailing list
5605 Bug reports are sent to @email{bug-cc-mode@@gnu.org}.  You can also send
5606 other questions and suggestions (kudos? @t{;-)} to that address.  It's a
5607 mailing list which you can join or browse an archive of; see the web
5608 site at @uref{http://cc-mode.sourceforge.net/} for further details.
5610 @cindex announcement mailing list
5611 If you want to get announcements of new @ccmode{} releases, send the
5612 word @emph{subscribe} in the body of a message to
5613 @email{cc-mode-announce-request@@lists.sourceforge.net}.  It's possible
5614 to subscribe from the web site too.  Announcements will also be posted
5615 to the Usenet newsgroups @code{gnu.emacs.sources}, @code{comp.emacs} and
5616 @code{comp.emacs.xemacs}.
5619 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5620 @node    Sample .emacs File, Command and Function Index, Mailing Lists and Submitting Bug Reports, Top
5621 @comment node-name, next, previous, up
5622 @appendix Sample .emacs file
5623 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5625 @example
5626 ;; Here's a sample .emacs file that might help you along the way.
5627 ;; Just copy this region and paste it into your .emacs file.  You may
5628 ;; want to change some of the actual values.
5630 (defconst my-c-style
5631   '((c-tab-always-indent        . t)
5632     (c-comment-only-line-offset . 4)
5633     (c-hanging-braces-alist     . ((substatement-open after)
5634                                    (brace-list-open)))
5635     (c-hanging-colons-alist     . ((member-init-intro before)
5636                                    (inher-intro)
5637                                    (case-label after)
5638                                    (label after)
5639                                    (access-label after)))
5640     (c-cleanup-list             . (scope-operator
5641                                    empty-defun-braces
5642                                    defun-close-semi))
5643     (c-offsets-alist            . ((arglist-close . c-lineup-arglist)
5644                                    (substatement-open . 0)
5645                                    (case-label        . 4)
5646                                    (block-open        . 0)
5647                                    (knr-argdecl-intro . -)))
5648     (c-echo-syntactic-information-p . t))
5649   "My C Programming Style")
5651 ;; offset customizations not in my-c-style
5652 (setq c-offsets-alist '((member-init-intro . ++)))
5654 ;; Customizations for all modes in CC Mode.
5655 (defun my-c-mode-common-hook ()
5656   ;; add my personal style and set it for the current buffer
5657   (c-add-style "PERSONAL" my-c-style t)
5658   ;; other customizations
5659   (setq tab-width 8
5660         ;; this will make sure spaces are used instead of tabs
5661         indent-tabs-mode nil)
5662   ;; we like auto-newline and hungry-delete
5663   (c-toggle-auto-hungry-state 1)
5664   ;; key bindings for all supported languages.  We can put these in
5665   ;; c-mode-base-map because c-mode-map, c++-mode-map, objc-mode-map,
5666   ;; java-mode-map, idl-mode-map, and pike-mode-map inherit from it.
5667   (define-key c-mode-base-map "\C-m" 'c-context-line-break))
5669 (add-hook 'c-mode-common-hook 'my-c-mode-common-hook)
5670 @end example
5673 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5674 @node    Command and Function Index, Variable Index, Sample .emacs File, Top
5675 @comment node-name, next, previous, up
5676 @unnumbered Command and Function Index
5677 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5679 Since most @ccmode{} commands are prepended with the string
5680 @samp{c-}, each appears under its @code{c-@var{thing}} name and its
5681 @code{@var{thing} (c-)} name.
5682 @iftex
5683 @sp 2
5684 @end iftex
5685 @printindex fn
5688 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5689 @node    Variable Index, Concept Index, Command and Function Index, Top
5690 @comment node-name, next, previous, up
5691 @unnumbered Variable Index
5692 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5694 Since most @ccmode{} variables are prepended with the string
5695 @samp{c-}, each appears under its @code{c-@var{thing}} name and its
5696 @code{@var{thing} (c-)} name.
5697 @iftex
5698 @sp 2
5699 @end iftex
5700 @printindex vr
5703 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5704 @node    Concept Index, , Variable Index, Top
5705 @comment node-name, next, previous, up
5706 @unnumbered Concept Index
5707 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5709 @printindex cp
5712 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5713 @comment Epilogue.
5714 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5716 @iftex
5717 @page
5718 @summarycontents
5719 @contents
5720 @end iftex
5722 @bye
5724 @ignore
5725    arch-tag: c4cab162-5e57-4366-bdce-4a9db2fc97f0
5726 @end ignore