cc-mode.texi 203 KB
Newer Older
Dave Love's avatar
#  
Dave Love committed
1 2
\input texinfo

3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25
@c Notes to self regarding line handling:
@c
@c Empty lines are often significant before @end directives; avoid them.
@c
@c Empty lines before and after @example directives are significant in
@c info output but not in TeX.  Empty lines inside @example directives
@c are significant.

@c Conventions for formatting examples:
@c o  If the example contains empty lines then put the surrounding empty
@c    lines inside the @example directives.  Put them outside otherwise.
@c o  Use @group inside the example only if it shows indentation where
@c    the relation between lines inside is relevant.
@c o  Format line number columns like this:
@c     1: foo
@c     2: bar
@c       ^ one space
@c    ^^ two columns, right alignment
@c o  Check line lengths in TeX output; they can typically be no longer
@c    than 70 chars, 60 if the paragraph is indented.

@comment TBD: Document the finer details of statement anchoring?

Dave Love's avatar
#  
Dave Love committed
26 27 28 29
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@comment %**start of header (This is for running Texinfo on a region)
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

30 31
@comment No overfull hbox marks in the dvi file.
@finalout
Dave Love's avatar
#  
Dave Love committed
32

33
@setfilename  ../info/ccmode
Gerd Moellmann's avatar
Gerd Moellmann committed
34
@settitle     CC Mode Manual
35
@footnotestyle end
Dave Love's avatar
#  
Dave Love committed
36 37 38 39 40 41 42 43

@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@comment @setchapternewpage odd !! we don't want blank pages !!
@comment %**end of header (This is for running Texinfo on a region)
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!


@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
44
@comment 
Dave Love's avatar
#  
Dave Love committed
45 46 47
@comment Texinfo manual for CC Mode
@comment Generated from the original README file by Krishna Padmasola
@comment <krishna@earth-gw.njit.edu>
Gerd Moellmann's avatar
Gerd Moellmann committed
48 49 50 51 52
@comment
@comment Authors:
@comment Barry A. Warsaw
@comment Martin Stjernholm
@comment
53
@comment Maintained by Martin Stjernholm <bug-cc-mode@gnu.org>
54
@comment 
Dave Love's avatar
#  
Dave Love committed
55 56
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

57 58 59 60 61 62 63
@comment Define an index for syntactic symbols.
@defindex ss

@comment Combine key, syntactic symbol and concept indices into one.
@syncodeindex ss cp
@syncodeindex ky cp

Karl Berry's avatar
Karl Berry committed
64 65
@copying
This manual is for CC Mode in Emacs.
Gerd Moellmann's avatar
Gerd Moellmann committed
66

67 68
Copyright @copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
2003 Free Software Foundation, Inc.
69

Karl Berry's avatar
Karl Berry committed
70
@quotation
71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
Invariant Sections being ``The GNU Manifesto'', ``Distribution'' and
``GNU GENERAL PUBLIC LICENSE'', with the Front-Cover texts being ``A GNU
Manual'', and with the Back-Cover Texts as in (a) below.  A copy of the
license is included in the section entitled ``GNU Free Documentation
License'' in the Emacs manual.

(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
this GNU Manual, like GNU software.  Copies published by the Free
Software Foundation raise funds for GNU development.''

This document is part of a collection distributed under the GNU Free
Documentation License.  If you want to distribute this document
separately from the collection, you can do so by adding a copy of the
license to the document, as described in section 6 of the license.
Karl Berry's avatar
Karl Berry committed
88 89 90 91 92 93 94
@end quotation
@end copying

@comment Info directory entry for use by install-info. The indentation
@comment here is by request from the FSF folks.
@dircategory Emacs
@direntry
95 96
* CC Mode: (ccmode).    Emacs mode for editing C, C++, Objective-C,
                        Java, Pike, AWK, and CORBA IDL code.
Karl Berry's avatar
Karl Berry committed
97
@end direntry
Dave Love's avatar
#  
Dave Love committed
98 99

@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
Gerd Moellmann's avatar
Gerd Moellmann committed
100
@comment TeX title page
Dave Love's avatar
#  
Dave Love committed
101 102 103 104 105
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

@titlepage
@sp 10

106
@center @titlefont{CC Mode 5.30}
Dave Love's avatar
#  
Dave Love committed
107 108 109
@sp 2
@center @subtitlefont{A GNU Emacs mode for editing C and C-like languages}
@sp 2
110
@center Barry A. Warsaw, Martin Stjernholm, Alan Mackenzie (AWK support)
Dave Love's avatar
#  
Dave Love committed
111 112 113

@page
@vskip 0pt plus 1filll
Karl Berry's avatar
Karl Berry committed
114
@insertcopying
Dave Love's avatar
#  
Dave Love committed
115 116 117 118 119 120 121
@end titlepage

@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@comment The Top node contains the master menu for the Info file.
@comment This appears only in the Info file, not the printed manual.
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

122 123 124 125 126 127 128 129 130
@node    Top, Introduction, (dir), (dir)
@comment node-name, next, previous, up

@macro ccmode
CC Mode
@end macro

@ifinfo
@top @ccmode{}
Dave Love's avatar
#  
Dave Love committed
131

132
@ccmode{} is a GNU Emacs mode for editing files containing C, C++,
133 134 135 136 137 138
Objective-C, Java, CORBA IDL (and the variants PSDL and CIDL), Pike
code and to a certain extent, AWK code @xref{AWK Mode}.  It provides
syntax-based indentation, font locking, and has several handy commands
and some minor modes to make the editing easier.  It does not provide
tools to look up and navigate between functions, classes etc - there are
other packages for that.
139
@end ifinfo
Dave Love's avatar
#  
Dave Love committed
140 141 142 143 144

@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

@menu
145 146
* Introduction::
* Getting Connected::
147
* Indentation Engine::
Dave Love's avatar
#  
Dave Love committed
148
* Minor Modes::
149
* Text Filling and Line Breaking::
150 151
* Macro Handling::
* Font Locking::
Dave Love's avatar
#  
Dave Love committed
152 153 154
* Commands::
* Customizing Indentation::
* Syntactic Symbols::
155
* Indentation Functions::
156 157
* AWK Mode::
* Odds and Ends::
Dave Love's avatar
#  
Dave Love committed
158
* Performance Issues::
Gerd Moellmann's avatar
Gerd Moellmann committed
159
* Limitations and Known Bugs::
Dave Love's avatar
#  
Dave Love committed
160
* Frequently Asked Questions::
161 162
* Getting the Latest CC Mode Release::
* Mailing Lists and Submitting Bug Reports::
Gerd Moellmann's avatar
Gerd Moellmann committed
163
* Sample .emacs File::
164 165 166

 --- Indices ---

167
* Command and Function Index::
168
* Variable Index::
169
* Concept Index::
170

171
@detailmenu
172 173
 --- The Detailed Node Listing ---

174
Indentation Engine
175 176 177 178 179 180 181 182 183

* Syntactic Analysis::
* Indentation Calculation::

Minor Modes

* Auto-newline Insertion::
* Hungry-deletion of Whitespace::

184 185 186 187 188 189
Font Locking

* Font Locking Preliminaries::
* Faces::
* Documentation Comments::

190 191 192 193
Auto-newline Insertion

* Hanging Braces::
* Hanging Colons::
194
* Hanging Semicolons and Commas::
195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214
* Other Electric Commands::
* Clean-ups::

Commands

* Indentation Commands::
* Movement Commands::
* Other Commands::

Customizing Indentation

* Interactive Customization::
* Permanent Customization::
* Hooks::
* Styles::
* Advanced Customizations::

Styles

* Built-in Styles::
215
* Choosing a Style::
216 217 218 219 220 221 222
* Adding Styles::
* File Styles::

Advanced Customizations

* Custom Indentation Functions::
* Custom Brace and Colon Hanging::
223
* Customizing Semicolons and Commas::
224
* Other Special Indentations::
225 226 227 228 229 230 231

AWK Mode

* Initialising AWK Mode::
* AWK Mode Font Locking::
* AWK Mode Defuns::
@end detailmenu
Dave Love's avatar
#  
Dave Love committed
232 233
@end menu

234

Dave Love's avatar
#  
Dave Love committed
235
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
236 237
@node    Introduction, Getting Connected, Top, Top
@comment node-name, next, previous, up
238
@chapter Introduction
Dave Love's avatar
#  
Dave Love committed
239 240 241 242
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

@cindex BOCM

243
Welcome to @ccmode{}, a GNU Emacs mode for editing files containing C,
244 245 246 247 248
C++, Objective-C, Java, CORBA IDL (and the variants CORBA PSDL and
CIDL), Pike and to a certain extent, AWK code (@pxref{AWK Mode}).  This
incarnation of the mode is descended from @file{c-mode.el} (also called
``Boring Old C Mode'' or BOCM @t{:-)}, and @file{c++-mode.el} version 2,
which Barry has been maintaining since 1992.  Late in 1997, Martin
249
joined the @ccmode{} Maintainers Team, and implemented the Pike support.
250 251 252 253
As of 2000 Martin has taken over as the sole maintainer.  @ccmode{} did
not originally contain the font lock support for its languages --- that
was added in version 5.30.  AWK support was also added in 5.30 by Alan
Mackenzie.
254 255 256

This manual describes @ccmode{}
@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
Dave Love's avatar
#  
Dave Love committed
259

260 261 262 263 264 265 266
@ccmode{} supports the editing of K&R and ANSI C, C++, Objective-C,
Java, CORBA's Interface Definition Language, Pike@footnote{A C-like
scripting language with its roots in the LPC language used in some MUD
engines.  See @uref{http://pike.ida.liu.se/}.} and AWK files.  In this
way, you can easily set up consistent font locking and coding styles for
use in editing all of these languages, although AWK is not yet as
uniformly integrated as the other languages.
Dave Love's avatar
#  
Dave Love committed
267 268 269 270 271 272

@findex c-mode
@findex c++-mode
@findex objc-mode
@findex java-mode
@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
Dave Love's avatar
#  
Dave Love committed
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 280 281 282 283 284 285 286 287 288 289 290 291
@code{idl-mode}, @code{pike-mode}, and @code{awk-mode} entry points are
provided.  This package is intended to be a replacement for
@file{c-mode.el}, @file{c++-mode.el} and @file{awk-mode.el}.

@c @cindex @file{cc-compat.el} file
@c This distribution also contains a file
@c called @file{cc-compat.el} which should ease your transition from BOCM
@c to @ccmode{}.  If you have a BOCM configuration you are really happy
@c with, and want to postpone learning how to configure @ccmode{}, take a
@c look at that file.  It maps BOCM configuration variables to @ccmode{}'s
@c indentation model.  It is not actively supported so for the long run,
@c you should learn how to customize @ccmode{} to support your coding
@c style.
Dave Love's avatar
#  
Dave Love committed
292 293 294 295 296 297 298 299

A special word of thanks goes to Krishna Padmasola for his work in
converting the original @file{README} file to Texinfo format.  I'd also
like to thank all the @ccmode{} victims who help enormously during the
early beta stages of @ccmode{}'s development.


@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
300
@node    Getting Connected, Indentation Engine, Introduction, Top
301
@comment node-name, next, previous, up
302
@chapter Getting Connected
Dave Love's avatar
#  
Dave Love committed
303 304 305 306 307 308 309 310 311
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

If you got this version of @ccmode{} with Emacs or XEmacs, it should
work just fine right out of the box.  Note however that you may not have
the latest @ccmode{} release and may want to upgrade your copy.

If you are upgrading an existing @ccmode{} installation, please see the
@file{README} file for installation details.  @ccmode{} may not work
with older versions of Emacs or XEmacs.  See the @ccmode{} release notes
312 313 314
at @uref{http://cc-mode.sourceforge.net} for the latest information on
Emacs version and package compatibility (@pxref{Getting the Latest CC
Mode Release}).
Dave Love's avatar
#  
Dave Love committed
315

316
@deffn Command c-version
Dave Love's avatar
#  
Dave Love committed
317 318 319 320 321
@findex version (c-)
You can find out what version of @ccmode{} you are using by visiting a C
file and entering @kbd{M-x c-version RET}.  You should see this message in
the echo area:

322
@example
Dave Love's avatar
#  
Dave Love committed
323 324 325 326 327
Using CC Mode version 5.XX
@end example

@noindent
where @samp{XX} is the minor release number.
328
@end deffn
Dave Love's avatar
#  
Dave Love committed
329 330 331


@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
332
@node    Indentation Engine, Minor Modes, Getting Connected, Top
333
@comment node-name, next, previous, up
334
@chapter Indentation Engine
Dave Love's avatar
#  
Dave Love committed
335 336
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

337 338 339 340 341 342
@ccmode{} has an indentation engine that provides a flexible and general
mechanism for customizing indentation. It separates indentation
calculation into two steps: first, @ccmode{} analyzes the line of code
being indented to determine the kind of language construct it's looking
at, then it applies user defined offsets to the current line based on
this analysis.
Dave Love's avatar
#  
Dave Love committed
343 344

This section will briefly cover how indentation is calculated in
345 346 347 348 349 350 351 352 353 354 355 356
@ccmode{}. It is important to understand the indentation model being
used so that you will know how to customize @ccmode{} for your personal
coding style.  All the details are in @ref{Customizing Indentation}, and
later chapters.

@defopt c-syntactic-indentation
@vindex syntactic-indentation (c-)
Syntactic analysis for indentation is done when this is non-@code{nil}
(which is the default).  When it's @code{nil} every line is just
indented to the same level as the previous one, and @kbd{TAB}
(@code{c-indent-command}) adjusts the indentation in steps of
@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
Dave Love's avatar
#  
Dave Love committed
359 360 361 362 363 364 365 366

@menu
* Syntactic Analysis::
* Indentation Calculation::
@end menu


@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
367
@node    Syntactic Analysis, Indentation Calculation, , Indentation Engine
368
@comment node-name, next, previous, up
369
@section Syntactic Analysis
370
@cindex syntactic analysis
Dave Love's avatar
#  
Dave Love committed
371 372 373
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

@cindex relative buffer position
374
@cindex syntactic symbols
Dave Love's avatar
#  
Dave Love committed
375 376 377 378
@cindex syntactic component
@cindex syntactic component list
The first thing @ccmode{} does when indenting a line of code, is to
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 381
elements (in lisp parlance, a @emph{cons cell}), the first being
a @dfn{syntactic symbol}, the second being a @dfn{relative
Dave Love's avatar
#  
Dave Love committed
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 386 387 388
@code{class-open}, @code{class-close}, etc.  @xref{Syntactic Symbols},
for a complete list of currently recognized syntactic symbols and their
semantics.  The style variable @code{c-offsets-alist} also contains the
list of currently supported syntactic symbols.
Dave Love's avatar
#  
Dave Love committed
389 390 391 392 393 394

Conceptually, a line of C code is always indented relative to the
indentation of some line higher up in the buffer.  This is represented
by the relative buffer position in the syntactic component.

Here is an example.  Suppose we had the following code as the only thing
395 396
in a C++ buffer @footnote{The line numbers in this and future examples
don't actually appear in the buffer, of course!}:
Dave Love's avatar
#  
Dave Love committed
397

398 399 400 401 402 403 404
@example
 1: void swap( int& a, int& b )
 2: @{
 3:     int tmp = a;
 4:     a = b;
 5:     b = tmp;
 6: @}
Dave Love's avatar
#  
Dave Love committed
405 406 407 408 409
@end example

@kindex C-c C-s
@findex c-show-syntactic-information
@findex show-syntactic-information (c-)
410 411
We can use the command @kbd{C-c C-s} (bound to
@code{c-show-syntactic-information}) to simply report what the
Dave Love's avatar
#  
Dave Love committed
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.}:
Dave Love's avatar
#  
Dave Love committed
416

417 418
@example
((statement 35))
Dave Love's avatar
#  
Dave Love committed
419 420 421 422 423 424 425
@end example

This tells us that the line is a statement and it is indented relative
to buffer position 35, which happens to be the @samp{i} in @code{int} on
line 3.  If you were to move point to line 3 and hit @kbd{C-c C-s}, you
would see:

426 427
@example
((defun-block-intro 29))
Dave Love's avatar
#  
Dave Love committed
428 429 430 431 432 433 434 435
@end example

This indicates that the @samp{int} line is the first statement in a top
level function block, and is indented relative to buffer position 29,
which is the brace just after the function header.

Here's another example:

436 437 438 439 440 441 442 443 444
@example
 1: int add( int val, int incr, int doit )
 2: @{
 3:     if( doit )
 4:         @{
 5:             return( val + incr );
 6:         @}
 7:     return( val );
 8: @}
Dave Love's avatar
#  
Dave Love committed
445 446 447 448 449
@end example

@noindent
Hitting @kbd{C-c C-s} on line 4 gives us:

450 451
@example
((substatement-open 46))
Dave Love's avatar
#  
Dave Love committed
452 453 454
@end example

@cindex substatement
455
@cindex substatement block
Dave Love's avatar
#  
Dave Love committed
456 457 458 459 460 461 462 463 464 465 466 467 468
@noindent
which tells us that this is a brace that @emph{opens} a substatement
block. @footnote{A @dfn{substatement} is the line after a
conditional statement, such as @code{if}, @code{else}, @code{while},
@code{do}, @code{switch}, etc.  A @dfn{substatement
block} is a brace block following one of these conditional statements.}

@cindex comment-only line
Syntactic component lists can contain more than one component, and
individual syntactic components need not have relative buffer positions.
The most common example of this is a line that contains a @dfn{comment
only line}.

469 470 471 472 473 474 475 476 477
@example
 1: void draw_list( List<Drawables>& drawables )
 2: @{
 3:         // call the virtual draw() method on each element in list
 4:     for( int i=0; i < drawables.count(), ++i )
 5:     @{
 6:         drawables[i].draw();
 7:     @}
 8: @}
Dave Love's avatar
#  
Dave Love committed
478 479 480 481 482
@end example

@noindent
Hitting @kbd{C-c C-s} on line 3 of this example gives:

483 484
@example
((comment-intro) (defun-block-intro 46))
Dave Love's avatar
#  
Dave Love committed
485 486 487 488 489 490 491 492 493
@end example

@noindent
and you can see that the syntactic component list contains two syntactic
components.  Also notice that the first component,
@samp{(comment-intro)} has no relative buffer position.


@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
494
@node    Indentation Calculation, , Syntactic Analysis, Indentation Engine
495
@comment node-name, next, previous, up
496 497
@section Indentation Calculation
@cindex indentation
Dave Love's avatar
#  
Dave Love committed
498 499 500
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

Indentation for a line is calculated using the syntactic
501
component list derived in step 1 above (@pxref{Syntactic Analysis}).
Dave Love's avatar
#  
Dave Love committed
502 503 504 505
Each component contributes to the final total indentation of the line in
two ways.

First, the syntactic symbols are looked up in the @code{c-offsets-alist}
506 507
style variable, which is an association list of syntactic symbols and
the offsets to apply for those symbols.  These offsets are added to a
Dave Love's avatar
#  
Dave Love committed
508 509 510 511 512 513 514 515 516 517
running total.

Second, if the component has a relative buffer position, @ccmode{}
adds the column number of that position to the running total.  By adding
up the offsets and columns for every syntactic component on the list,
the final total indentation for the current line is computed.

Let's use our two code examples above to see how this works.  Here is
our first example again:

518 519 520 521 522 523 524
@example
 1: void swap( int& a, int& b )
 2: @{
 3:     int tmp = a;
 4:     a = b;
 5:     b = tmp;
 6: @}
Dave Love's avatar
#  
Dave Love committed
525 526
@end example

527
Let's say point is on line 3 and we hit the @kbd{TAB} key to reindent
Dave Love's avatar
#  
Dave Love committed
528 529 530
the line.  Remember that the syntactic component list for that
line is:

531 532
@example
((defun-block-intro 29))
Dave Love's avatar
#  
Dave Love committed
533 534 535 536
@end example

@noindent
@ccmode{} looks up @code{defun-block-intro} in the
537 538 539
@code{c-offsets-alist} style variable.  Let's say it finds the value
@samp{4}; it adds this to the running total (initialized to zero),
yielding a running total indentation of 4 spaces.
Dave Love's avatar
#  
Dave Love committed
540 541 542 543 544 545 546 547 548 549

Next @ccmode{} goes to buffer position 29 and asks for the current
column.  This brace is in column zero, so @ccmode{}
adds @samp{0} to the running total.  Since there is only one syntactic
component on the list for this line, indentation calculation is
complete, and the total indentation for the line
is 4 spaces.

Here's another example:

550 551 552 553 554 555 556 557 558
@example
 1: int add( int val, int incr, int doit )
 2: @{
 3:     if( doit )
 4:         @{
 5:             return( val + incr );
 6:         @}
 7:     return( val );
 8: @}
Dave Love's avatar
#  
Dave Love committed
559 560 561 562 563 564
@end example

If we were to hit @kbd{TAB} on line 4 in the above example, the same
basic process is performed, despite the differences in the syntactic
component list.  Remember that the list for this line is:

565 566
@example
((substatement-open 46))
Dave Love's avatar
#  
Dave Love committed
567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589
@end example

Here, @ccmode{} first looks up the @code{substatement-open} symbol
in @code{c-offsets-alist}. Let's say it finds the value @samp{4}.  This
yields a running total of 4.  @ccmode{} then goes to
buffer position 46, which is the @samp{i} in @code{if} on line 3.  This
character is in the fourth column on that line so adding this to the
running total yields an indentation for the line of 8 spaces.

Simple, huh?

Actually, the mode usually just does The Right Thing without you having
to think about it in this much detail.  But when customizing
indentation, it's helpful to understand the general indentation model
being used.

As you configure @ccmode{}, you might want to set the variable
@code{c-echo-syntactic-information-p} to non-@code{nil} so that the
syntactic component list and calculated offset will always be echoed in
the minibuffer when you hit @kbd{TAB}.


@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
590
@node    Minor Modes, Text Filling and Line Breaking, Indentation Engine, Top
591
@comment node-name, next, previous, up
592
@chapter Minor Modes
Dave Love's avatar
#  
Dave Love committed
593 594 595
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

@ccmode{} contains two minor-mode-like features that you should
596
find useful while entering new C code.  The first is called
Dave Love's avatar
#  
Dave Love committed
597 598 599 600 601 602 603 604
@dfn{auto-newline} mode, and the second is called @dfn{hungry-delete}
mode.  These minor modes can be toggled on and off independently, and
@ccmode{} can be configured so that it starts up with any
combination of these minor modes.  By default, both of these minor modes
are turned off.

The state of the minor modes is always reflected in the minor mode list
on the modeline of the @ccmode{} buffer.  When auto-newline mode is
605 606 607 608 609
enabled, you will see @samp{C/a} on the mode line@footnote{The @samp{C}
would be replaced with the name of the language in question for the
other languages @ccmode{} supports.}.  When hungry delete mode is
enabled you will see @samp{C/h} and if both modes were enabled, you'd
see @samp{C/ah}.
Dave Love's avatar
#  
Dave Love committed
610 611 612 613 614 615 616 617 618 619

@kindex C-c C-a
@kindex C-c C-d
@kindex C-c C-t
@findex c-toggle-hungry-state
@findex c-toggle-auto-state
@findex c-toggle-auto-hungry-state
@findex toggle-hungry-state (c-)
@findex toggle-auto-state (c-)
@findex toggle-auto-hungry-state (c-)
Richard M. Stallman's avatar
Richard M. Stallman committed
620
@ccmode{} provides key bindings which allow you to toggle the minor
Dave Love's avatar
#  
Dave Love committed
621
modes on the fly while editing code.  To toggle just the auto-newline
622 623 624 625 626 627
state, hit @kbd{C-c C-a} (bound to @code{c-toggle-auto-state}).  When
you do this, you should see the @samp{a} indicator either appear or
disappear on the modeline.  Similarly, to toggle just the
hungry-delete state, use @kbd{C-c C-d} (@code{c-toggle-hungry-state}),
and to toggle both states, use @kbd{C-c C-t}
(@code{c-toggle-auto-hungry-state}).
Dave Love's avatar
#  
Dave Love committed
628 629 630 631 632 633 634 635 636 637 638 639

To set up the auto-newline and hungry-delete states to your preferred
values, you would need to add some lisp to your @file{.emacs} file that
called one of the @code{c-toggle-*-state} functions directly.  When
called programmatically, each function takes a numeric value, where
a positive number enables the minor mode, a negative number disables the
mode, and zero toggles the current state of the mode.

So for example, if you wanted to enable both auto-newline and
hungry-delete for all your C file editing, you could add the following
to your @file{.emacs} file:

640
@example
Dave Love's avatar
#  
Dave Love committed
641
(add-hook 'c-mode-common-hook
642
          (lambda () (c-toggle-auto-hungry-state 1)))
Dave Love's avatar
#  
Dave Love committed
643 644 645
@end example

@menu
646 647
* Auto-newline Insertion::
* Hungry-deletion of Whitespace::
Dave Love's avatar
#  
Dave Love committed
648 649 650
@end menu


651 652 653
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@node    Auto-newline Insertion, Hungry-deletion of Whitespace, , Minor Modes
@comment node-name, next, previous, up
654 655
@section Auto-newline Insertion
@cindex auto-newline
Dave Love's avatar
#  
Dave Love committed
656 657
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

658
@cindex electric characters
Dave Love's avatar
#  
Dave Love committed
659
Auto-newline minor mode works by enabling certain @dfn{electric
660 661 662 663 664
characters}.  Special characters such as the left and right braces,
colons, semicolons, etc., have been made electric to perform some
magic formatting in addition to inserting the typed character.  As a
general rule, electric characters are only electric when the following
conditions apply:
Dave Love's avatar
#  
Dave Love committed
665 666 667 668 669 670

@itemize @bullet
@item
Auto-newline minor mode is enabled, as evidenced by a @samp{C/a} or
@samp{C/ah} indicator on the modeline.

671
@item
Dave Love's avatar
#  
Dave Love committed
672 673 674
@cindex literal
@cindex syntactic whitespace
The character was not typed inside of a literal @footnote{A
675
@dfn{literal} is defined as any comment, string, or preprocessor macro
Dave Love's avatar
#  
Dave Love committed
676 677 678 679
definition.  These constructs are also known as @dfn{syntactic
whitespace} since they are usually ignored when scanning C code.}.

@item
680
No numeric argument was supplied to the command (i.e., it was typed as
Dave Love's avatar
#  
Dave Love committed
681 682 683 684 685 686
normal, with no @kbd{C-u} prefix).
@end itemize

@menu
* Hanging Braces::
* Hanging Colons::
687
* Hanging Semicolons and Commas::
688
* Other Electric Commands::
Dave Love's avatar
#  
Dave Love committed
689 690 691 692
* Clean-ups::
@end menu


693 694 695 696 697
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@node    Hanging Braces, Hanging Colons, , Auto-newline Insertion
@comment node-name, next, previous, up
@subsection Hanging Braces
@cindex hanging braces
Dave Love's avatar
#  
Dave Love committed
698 699 700 701
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

@findex c-electric-brace
@findex electric-brace (c-)
702 703 704
@kindex @{
@kindex @}

705
When you type either an open or close brace (i.e., @kbd{@{} or @kbd{@}}),
Dave Love's avatar
#  
Dave Love committed
706 707
the electric command @code{c-electric-brace} gets run.  This command has
two electric formatting behaviors.  First, it will perform some
708
reindentation of the line the brace was typed on, and second, it will
Dave Love's avatar
#  
Dave Love committed
709
add various newlines before and/or after the typed brace.
710
Reindentation occurs automatically whenever the electric behavior is
Dave Love's avatar
#  
Dave Love committed
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.
713 714 715

The default in auto-newline mode is to insert newlines both before and
after a brace, but that can be controlled by the
716 717 718 719 720 721 722 723 724 725 726 727 728
@code{c-hanging-braces-alist} style variable.

@defopt c-hanging-braces-alist
@vindex hanging-braces-alist (c-)

This variable contains a mapping between syntactic symbols related to
braces, and a list of places to insert a newline.  The syntactic symbols
that are useful for this list are @code{brace-list-intro},
@code{statement-cont}, @code{inexpr-class-open},
@code{inexpr-class-close}, and all the @code{*-open} and @code{*-close}
symbols.  @xref{Syntactic Symbols}, for a more detailed description of
these syntactic symbols, except for @code{inexpr-class-open} and
@code{inexpr-class-close}, which aren't actual syntactic symbols.
729 730 731 732

The braces of anonymous inner classes in Java are given the special
symbols @code{inexpr-class-open} and @code{inexpr-class-close}, so that
they can be distinguished from the braces of normal classes@footnote{The
733
braces of anonymous classes produce a combination of
734 735 736
@code{inexpr-class}, and @code{class-open} or @code{class-close} in
normal indentation analysis.}.

737 738 739 740 741 742
Note that the aggregate constructs in Pike mode, @samp{(@{}, @samp{@})},
@samp{([}, @samp{])}, and @samp{(<}, @samp{>)}, do not count as brace
lists in this regard, even though they do for normal indentation
purposes.  It's currently not possible to set automatic newlines on
these constructs.

Dave Love's avatar
#  
Dave Love committed
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}.
Dave Love's avatar
#  
Dave Love committed
747

748
When the @var{action} is a list, it can contain any combination of the
Dave Love's avatar
#  
Dave Love committed
749 750 751 752 753
symbols @code{before} and @code{after}, directing @ccmode{} where to
put newlines in relationship to the brace being inserted.  Thus, if the
list contains only the symbol @code{after}, then the brace is said to
@dfn{hang} on the right side of the line, as in:

754
@example
Dave Love's avatar
#  
Dave Love committed
755 756 757 758 759 760 761 762 763 764 765 766 767
// here, open braces always `hang'
void spam( int i ) @{
    if( i == 7 ) @{
        dosomething(i);
    @}
@}
@end example

When the list contains both @code{after} and @code{before}, the braces
will appear on a line by themselves, as shown by the close braces in the
above example.  The list can also be empty, in which case no newlines
are added either before or after the brace.

768 769
If a syntactic symbol is missing entirely from
@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 772
that braces by default end up on their own line.

Dave Love's avatar
#  
Dave Love committed
773 774
For example, the default value of @code{c-hanging-braces-alist} is:

775 776 777 778 779 780 781 782 783
@example
((brace-list-open)
 (brace-entry-open)
 (statement-cont)
 (substatement-open after)
 (block-close . c-snug-do-while)
 (extern-lang-open after)
 (inexpr-class-open after)
 (inexpr-class-close before))
Dave Love's avatar
#  
Dave Love committed
784 785
@end example

786 787 788 789 790 791 792 793 794 795 796 797 798 799 800
@noindent which says that @code{brace-list-open},
@code{brace-entry-open} and @code{statement-cont}@footnote{Brace lists
inside statements, such as initializers for static array variables
inside functions in C, are recognized as @code{statement-cont}.  All
normal substatement blocks are recognized with other symbols.} braces
should both hang on the right side and allow subsequent text to follow
on the same line as the brace.  Also, @code{substatement-open},
@code{extern-lang-open}, and @code{inexpr-class-open} braces should hang
on the right side, but subsequent text should follow on the next line.
The opposite holds for @code{inexpr-class-close} braces; they won't
hang, but the following text continues on the same line.  Here, in the
@code{block-close} entry, you also see an example of using a function as
an @var{action}.  In all other cases, braces are put on a line by
themselves.
@end defopt
Dave Love's avatar
#  
Dave Love committed
801 802 803


@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
804
@node    Hanging Colons, Hanging Semicolons and Commas, Hanging Braces, Auto-newline Insertion
805 806 807
@comment node-name, next, previous, up
@subsection Hanging Colons
@cindex hanging colons
Dave Love's avatar
#  
Dave Love committed
808 809
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

810 811
Using a mechanism similar to brace hanging (@pxref{Hanging Braces}),
colons can also be made to hang using the style variable
812 813 814 815 816 817 818 819 820 821
@code{c-hanging-colons-alist}.

@defopt c-hanging-colons-alist
@vindex hanging-colons-alist (c-)

The syntactic symbols appropriate for this association list are:
@code{case-label}, @code{label}, @code{access-label},
@code{member-init-intro}, and @code{inher-intro}.  Note however that for
@code{c-hanging-colons-alist}, @var{action}s as functions are not
supported. See also @ref{Custom Brace and Colon Hanging} for details.
Dave Love's avatar
#  
Dave Love committed
822 823 824 825

In C++, double-colons are used as a scope operator but because these
colons always appear right next to each other, newlines before and after
them are controlled by a different mechanism, called @dfn{clean-ups} in
826
@ccmode{}.  @xref{Clean-ups}, for details.
827
@end defopt
Dave Love's avatar
#  
Dave Love committed
828 829 830


@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
831
@node    Hanging Semicolons and Commas, Other Electric Commands, Hanging Colons, Auto-newline Insertion
832
@comment node-name, next, previous, up
833 834
@subsection Hanging Semicolons and Commas
@cindex hanging semicolons
835
@cindex hanging commas
Dave Love's avatar
#  
Dave Love committed
836 837 838 839 840 841
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

Semicolons and commas are also electric in @ccmode{}, but since
these characters do not correspond directly to syntactic symbols, a
different mechanism is used to determine whether newlines should be
automatically inserted after these characters.  @xref{Customizing
842
Semicolons and Commas}, for details.
Dave Love's avatar
#  
Dave Love committed
843 844 845


@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
846
@node    Other Electric Commands, Clean-ups, Hanging Semicolons and Commas, Auto-newline Insertion
847 848
@comment node-name, next, previous, up
@subsection Other Electric Commands
Dave Love's avatar
#  
Dave Love committed
849 850
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

851 852 853 854 855 856 857
A few other keys also provide electric behavior, often only to reindent
the line.  Common to all of them is that they only reindent if used in
normal code (as opposed to in a string literal or comment), and
@code{c-syntactic-indentation} isn't @code{nil}.  They are:

@table @kbd
@item #
Dave Love's avatar
#  
Dave Love committed
858 859 860
@kindex #
@findex c-electric-pound
@findex electric-pound (c-)
861
@vindex c-electric-pound-behavior
Dave Love's avatar
#  
Dave Love committed
862
@vindex electric-pound-behavior (c-)
863 864 865 866 867 868 869 870 871 872 873
Pound (bound to @code{c-electric-pound}) is electric when typed as the
first non-whitespace character on a line and not within a macro
definition.  In this case, the variable @code{c-electric-pound-behavior}
is consulted for the electric behavior.  This variable takes a list
value, although the only element currently defined is @code{alignleft},
which tells this command to force the @samp{#} character into column
zero.  This is useful for entering preprocessor macro definitions.

Pound is not electric in AWK buffers, where @samp{#} starts a comment,
and is bound to @code{self-insert-command} like any typical printable
character.
Dave Love's avatar
#  
Dave Love committed
874

875 876 877 878
@item *
@kindex *
@itemx /
@kindex /
Dave Love's avatar
#  
Dave Love committed
879 880
@findex c-electric-star
@findex electric-star (c-)
881
@findex c-electric-slash
Dave Love's avatar
#  
Dave Love committed
882
@findex electric-slash (c-)
883 884 885 886 887 888 889
Stars and slashes (bound to @code{c-electric-star} and
@code{c-electric-slash} respectively) are also electric under certain
circumstances.  If a @samp{*} is inserted as the second character of a C
style block comment on a comment-only line, then the comment delimiter
is indented as defined by @code{c-offsets-alist}.  A comment-only line
is defined as a line which contains only a comment, as in:

Dave Love's avatar
#  
Dave Love committed
890 891
@example
@group
892
void spam( int i )
Dave Love's avatar
#  
Dave Love committed
893
@{
894 895
    // this is a comment-only line...
    if( i == 7 )                // but this is not
Dave Love's avatar
#  
Dave Love committed
896 897 898 899 900 901 902
    @{
        dosomething(i);
    @}
@}
@end group
@end example

903 904 905
Likewise, if a @samp{/} is inserted as the second slash in a C++ style
line comment (also only on a comment-only line), then the line is
indented as defined by @code{c-offsets-alist}.
Dave Love's avatar
#  
Dave Love committed
906

907 908 909 910
In AWK mode, @samp{*} and @samp{/} do not delimit comments and are
bound to @code{self-insert-command}.

@item <
Dave Love's avatar
#  
Dave Love committed
911
@kindex <
912
@itemx >
Dave Love's avatar
#  
Dave Love committed
913
@kindex >
914 915 916
@findex c-electric-lt-gt
@findex electric-lt-gt (c-)
Less-than and greater-than signs (bound to @code{c-electric-lt-gt}) are
Dave Love's avatar
#  
Dave Love committed
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.
Dave Love's avatar
#  
Dave Love committed
919

920
@item (
921
@kindex (
922
@itemx )
923
@kindex )
924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963
@findex c-electric-paren
@findex electric-paren (c-)
The normal parenthesis characters @samp{(} and @samp{)} reindent the
current line.  This is useful for getting the closing parenthesis of an
argument list aligned automatically.
@end table

@deffn Command c-electric-continued-statement
@findex electric-continued-statement (c-)

Certain keywords, depending on language, are electric to cause
reindentation when they are preceded only by whitespace on the line.
The keywords are those that continue an earlier statement instead of
starting a new one: @code{else}, @code{while}, @code{catch} (only in C++
and Java) and @code{finally} (only in Java).

An example:

@example
@group
for (i = 0; i < 17; i++)
  if (a[i])
    res += a[i]->offset;
else
@end group
@end example

Here, the @code{else} should be indented like the preceding @code{if},
since it continues that statement. @ccmode{} will automatically reindent
it after the @code{else} has been typed in full, since it's not until
then it's possible to decide whether it's a new statement or a
continuation of the preceding @code{if}.

@vindex abbrev-mode
@findex abbrev-mode
@cindex Abbrev mode
@ccmode{} uses Abbrev mode (@pxref{Abbrevs,,, emacs, The Emacs Editor})
to accomplish this. It's therefore turned on by default in all language
modes except IDL mode, since CORBA IDL doesn't have any statements.
@end deffn
Dave Love's avatar
#  
Dave Love committed
964 965


966 967 968 969 970
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@node    Clean-ups, , Other Electric Commands, Auto-newline Insertion
@comment node-name, next, previous, up
@subsection Clean-ups
@cindex clean-ups
Dave Love's avatar
#  
Dave Love committed
971 972
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

Gerd Moellmann's avatar
Gerd Moellmann committed
973 974 975
@dfn{Clean-ups} are mechanisms complementary to colon and brace hanging.
On the surface, it would seem that clean-ups overlap the functionality
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
Gerd Moellmann's avatar
Gerd Moellmann committed
977 978 979 980 981
whitespace in constructs after they are typed.

Most of the clean-ups are only applicable to counteract automatically
inserted newlines, and will therefore only have any effect if the
auto-newline minor mode is turned on.  Others will work all the time.
Dave Love's avatar
#  
Dave Love committed
982

983
@defopt c-cleanup-list
984
@vindex cleanup-list (c-)
Dave Love's avatar
#  
Dave Love committed
985
@cindex literal
986

987
You can configure @ccmode{}'s clean-ups by setting the style variable
Dave Love's avatar
#  
Dave Love committed
988
@code{c-cleanup-list}, which is a list of clean-up symbols.  By default,
989 990 991 992 993
@ccmode{} cleans up only the @code{scope-operator} construct, which is
necessary for proper C++ support.  Note that clean-ups are only
performed when the construct does not occur within a literal
(@pxref{Auto-newline Insertion}), and when there is nothing but
whitespace appearing between the individual components of the construct.
994
@end defopt
Dave Love's avatar
#  
Dave Love committed
995

996
These are the clean-ups that are only active in the auto-newline minor
Gerd Moellmann's avatar
Gerd Moellmann committed
997
mode:
Dave Love's avatar
#  
Dave Love committed
998

999 1000 1001 1002 1003 1004 1005 1006
@c TBD: Would like to use some sort of @deffoo here; @table indents a
@c bit too much in dvi output.
@table @code
@item brace-else-brace
Clean up @samp{@} else @{} constructs by placing the entire construct on
a single line.  Clean-up occurs when the open brace after the
@samp{else} is typed.  So for example, this:

Dave Love's avatar
#  
Dave Love committed
1007 1008 1009 1010
@example
@group
void spam(int i)
@{
1011
    if( i==7 ) @{
Dave Love's avatar
#  
Dave Love committed
1012 1013 1014 1015 1016 1017
        dosomething();
    @}
    else
    @{
@end group
@end example
1018

Dave Love's avatar
#  
Dave Love committed
1019
@noindent
1020 1021
appears like this after the last open brace is typed:

Dave Love's avatar
#  
Dave Love committed
1022 1023 1024 1025 1026 1027 1028 1029 1030 1031
@example
@group
void spam(int i)
@{
    if( i==7 ) @{
        dosomething();
    @} else @{
@end group
@end example

1032 1033 1034 1035
@item brace-elseif-brace
Similar to the @code{brace-else-brace} clean-up, but this cleans up
@samp{@} else if (...) @{} constructs.  For example:

Dave Love's avatar
#  
Dave Love committed
1036 1037 1038 1039
@example
@group
void spam(int i)
@{
1040
    if( i==7 ) @{
Dave Love's avatar
#  
Dave Love committed
1041 1042
        dosomething();
    @}
1043 1044
    else if( i==3 )
    @{
Dave Love's avatar
#  
Dave Love committed
1045 1046
@end group
@end example
1047

Dave Love's avatar
#  
Dave Love committed
1048
@noindent
1049 1050
appears like this after the last open parenthesis is typed:

1051 1052 1053 1054 1055 1056 1057 1058 1059 1060
@example
@group
void spam(int i)
@{
    if( i==7 ) @{
        dosomething();
    @} else if( i==3 )
    @{
@end group
@end example
1061

1062
@noindent
1063 1064
and like this after the last open brace is typed:

Dave Love's avatar
#  
Dave Love committed
1065 1066 1067 1068 1069 1070 1071 1072 1073 1074
@example
@group
void spam(int i)
@{
    if( i==7 ) @{
        dosomething();
    @} else if( i==3 ) @{
@end group
@end example

1075 1076 1077 1078 1079 1080 1081 1082
@item brace-catch-brace
Analogous to @code{brace-elseif-brace}, but cleans up @samp{@} catch
(...) @{} in C++ and Java mode.

@item empty-defun-braces
Clean up braces following a top-level function or class definition that
contains no body.  Clean up occurs when the closing brace is typed.
Thus the following:
1083

Dave Love's avatar
#  
Dave Love committed
1084 1085 1086 1087 1088 1089 1090
@example
@group
class Spam
@{
@}
@end group
@end example
1091

Dave Love's avatar
#  
Dave Love committed
1092 1093
@noindent
is transformed into this when the close brace is typed:
1094

Dave Love's avatar
#  
Dave Love committed
1095 1096 1097 1098 1099 1100 1101
@example
@group
class Spam
@{@}
@end group
@end example

1102 1103 1104 1105 1106
@item defun-close-semi
Clean up the terminating semicolon on top-level function or class
definitions when they follow a close brace.  Clean up occurs when the
semicolon is typed.  So for example, the following:

Dave Love's avatar
#  
Dave Love committed
1107 1108 1109 1110 1111 1112 1113 1114
@example
@group
class Spam
@{
@}
;
@end group
@end example
1115

Dave Love's avatar
#  
Dave Love committed
1116
@noindent
1117
is transformed into this when the semicolon is typed:
Dave Love's avatar
#  
Dave Love committed
1118 1119 1120 1121 1122 1123 1124 1125 1126

@example
@group
class Spam
@{
@};
@end group
@end example

1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139
@item list-close-comma
Clean up commas following braces in array and aggregate initializers.
Clean up occurs when the comma is typed.

@item scope-operator
Clean up double colons which may designate a C++ scope operator split
across multiple lines@footnote{Certain C++ constructs introduce
ambiguous situations, so @code{scope-operator} clean-ups may not always
be correct.  This usually only occurs when scoped identifiers appear in
switch label tags.}.  Clean up occurs when the second colon is typed.
You will always want @code{scope-operator} in the @code{c-cleanup-list}
when you are editing C++ code.
@end table
Dave Love's avatar
#  
Dave Love committed
1140

Gerd Moellmann's avatar
Gerd Moellmann committed
1141 1142 1143 1144
The following clean-ups are always active when they occur on
@code{c-cleanup-list}, and are thus not affected by the auto-newline
minor mode:

1145 1146 1147 1148
@table @code
@item space-before-funcall
Insert a space between the function name and the opening parenthesis of
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 1151 1152 1153 1154 1155 1156
@samp{abort ()}.  Clean up occurs when the opening parenthesis is typed.

@item compact-empty-funcall
Clean up any space between the function name and the opening parenthesis
of a function call that has no arguments.  This is typically used
together with @code{space-before-funcall} if you prefer the GNU function
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 1159 1160
(SIGINT, SIG_IGN)}, but @samp{abort()}.  Clean up occurs when the
closing parenthesis is typed.
@end table
Gerd Moellmann's avatar
Gerd Moellmann committed
1161

Dave Love's avatar
#  
Dave Love committed
1162 1163

@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1164 1165
@node    Hungry-deletion of Whitespace, , Auto-newline Insertion, Minor Modes
@comment node-name, next, previous, up
1166 1167
@section Hungry-deletion of Whitespace
@cindex hungry-deletion
Dave Love's avatar
#  
Dave Love committed
1168 1169 1170 1171 1172 1173 1174 1175
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

Hungry deletion of whitespace, or as it more commonly called,
@dfn{hungry-delete mode}, is a simple feature that some people find
extremely useful.  In fact, you might find yourself wanting
hungry-delete in @strong{all} your editing modes!

@kindex DEL
1176 1177 1178 1179 1180 1181
@kindex C-d

In a nutshell, when hungry-delete mode is enabled, hitting the @kbd{DEL}
or @kbd{C-d} keys will consume all preceding or following whitespace,
including newlines and tabs.  This can really cut down on the number of
times you have to hit these keys if, for example, you made a mistake on
Dave Love's avatar
#  
Dave Love committed
1182 1183
the preceding line.

1184
@deffn Command c-electric-backspace
Dave Love's avatar
#  
Dave Love committed
1185
@findex electric-backspace (c-)
1186 1187 1188 1189 1190 1191 1192 1193 1194
This command is run by default when you hit the @kbd{DEL} key.  It
deletes any amount of whitespace in the backwards direction if
hungry-delete mode is enabled.  When it's disabled, or when used with
a prefix argument or in a literal (@pxref{Auto-newline Insertion}),
the function contained in the @code{c-backspace-function} variable is
called with the prefix argument.
@end deffn

@defvar c-backspace-function
Dave Love's avatar
#  
Dave Love committed
1195
@vindex backspace-function (c-)
1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209