comparison doc/misc/cc-mode.texi @ 84286:926f8ad9f714

Move here from ../../man
author Glenn Morris <rgm@gnu.org>
date Thu, 06 Sep 2007 04:58:54 +0000
parents
children 3d431f1997d8
comparison
equal deleted inserted replaced
84285:1cad73086b92 84286:926f8ad9f714
1 \input texinfo
2 @c Notes to self regarding line handling:
3 @c
4 @c Empty lines are often significant before @end directives; avoid them.
5 @c
6 @c Empty lines before and after @example directives are significant in
7 @c info output but not in TeX. Empty lines inside @example directives
8 @c are significant.
9
10 @c Conventions for formatting examples:
11 @c o If the example contains empty lines then put the surrounding empty
12 @c lines inside the @example directives. Put them outside otherwise.
13 @c o Use @group inside the example only if it shows indentation where
14 @c the relation between lines inside is relevant.
15 @c o Format line number columns like this:
16 @c 1: foo
17 @c 2: bar
18 @c ^ one space
19 @c ^^ two columns, right alignment
20 @c o Check line lengths in TeX output; they can typically be no longer
21 @c than 70 chars, 60 if the paragraph is indented.
22
23 @comment TBD: Document the finer details of statement anchoring?
24
25 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
26 @comment %**start of header (This is for running Texinfo on a region)
27 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
28
29
30 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
31 @comment How to make the various output formats:
32 @comment (Thanks to Robert Chassell for supplying this information.)
33 @comment Note that Texinfo 4.7 (or later) is needed.
34 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
35 @ignore
36 In each of the following pairs of commands, the first generates a
37 version with cross references pointing to the GNU Emacs manuals,
38 the second with them pointing to the XEmacs manuals.
39 ## Info output
40 makeinfo cc-mode.texi
41 makeinfo -DXEMACS cc-mode.texi
42
43 ## DVI output
44 ## You may need to set up the environment variable TEXINPUTS so
45 ## that tex can find the file texinfo.tex - See the tex
46 ## manpage.
47 texi2dvi cc-mode.texi
48 texi2dvi -t "@set XEMACS " cc-mode.texi
49
50 ## HTML output. (The --no-split parameter is optional)
51 makeinfo --html --no-split cc-mode.texi
52 makeinfo --html --no-split -DXEMACS cc-mode.texi
53
54 ## Plain text output
55 makeinfo --fill-column=70 --no-split --paragraph-indent=0 \
56 --no-headers --output=cc-mode.txt cc-mode.texi
57 makeinfo --fill-column=70 --no-split --paragraph-indent=0 \
58 --no-headers --output=cc-mode.txt -DXEMACS cc-mode.texi
59
60 ## DocBook output
61 makeinfo --docbook --no-split --paragraph-indent=0 \
62 cc-mode.texi
63 makeinfo --docbook --no-split --paragraph-indent=0 \
64 -DXEMACS cc-mode.texi
65
66 ## XML output
67 makeinfo --xml --no-split --paragraph-indent=0 \
68 cc-mode.texi
69 makeinfo --xml --no-split --paragraph-indent=0 \
70 -DXEMACS cc-mode.texi
71
72 #### (You must be in the same directory as the viewed file.)
73
74 ## View DVI output
75 xdvi cc-mode.dvi &
76
77 ## View HTML output
78 mozilla cc-mode.html
79 @end ignore
80
81 @comment No overfull hbox marks in the dvi file.
82 @finalout
83
84 @setfilename ../info/ccmode
85 @settitle CC Mode Manual
86 @footnotestyle end
87
88 @c The following four macros generate the filenames and titles of the
89 @c main (X)Emacs manual and the Elisp/Lispref manual. Leave the
90 @c Texinfo variable `XEMACS' unset to generate a GNU Emacs version, set it
91 @c to generate an XEmacs version, e.g. with
92 @c "makeinfo -DXEMACS cc-mode.texi".
93 @ifset XEMACS
94 @macro emacsman
95 xemacs
96 @end macro
97 @macro emacsmantitle
98 XEmacs User's Manual
99 @end macro
100 @macro lispref
101 lispref
102 @end macro
103 @macro lispreftitle
104 XEmacs Lisp Reference Manual
105 @end macro
106 @end ifset
107
108 @ifclear XEMACS
109 @macro emacsman
110 emacs
111 @end macro
112 @macro emacsmantitle
113 GNU Emacs Manual
114 @end macro
115 @macro lispref
116 elisp
117 @end macro
118 @macro lispreftitle
119 GNU Emacs Lisp Reference Manual
120 @end macro
121 @end ifclear
122
123
124 @macro ccmode
125 CC Mode
126 @end macro
127
128 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
129 @comment @setchapternewpage odd !! we don't want blank pages !!
130 @comment %**end of header (This is for running Texinfo on a region)
131 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
132
133
134 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
135 @comment
136 @comment Texinfo manual for CC Mode
137 @comment Generated from the original README file by Krishna Padmasola
138 @comment <krishna@earth-gw.njit.edu>
139 @comment
140 @comment Authors:
141 @comment Barry A. Warsaw
142 @comment Martin Stjernholm
143 @comment Alan Mackenzie
144 @comment
145 @comment Maintained by Martin Stjernholm and Alan Mackenzie <bug-cc-mode@gnu.org>
146 @comment
147 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
148
149 @comment Define an index for syntactic symbols.
150 @ifnottex @c In texi2dvi, the @defindex would create an empty cc-mode.ss
151 @c For Info, unlike tex, @syncodeindex needs a matching @defindex.
152 @defindex ss
153 @end ifnottex
154
155 @comment Combine key, syntactic symbol and concept indices into one.
156 @syncodeindex ss cp
157 @syncodeindex ky cp
158
159 @copying
160 This manual is for CC Mode in Emacs.
161
162 Copyright @copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
163 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
164
165 @quotation
166 Permission is granted to copy, distribute and/or modify this document
167 under the terms of the GNU Free Documentation License, Version 1.2 or
168 any later version published by the Free Software Foundation; with the
169 Invariant Sections being ``The GNU Manifesto'', ``Distribution'' and
170 ``GNU GENERAL PUBLIC LICENSE'', with the Front-Cover texts being ``A GNU
171 Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
172 license is included in the section entitled ``GNU Free Documentation
173 License'' in the Emacs manual.
174
175 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
176 this GNU Manual, like GNU software. Copies published by the Free
177 Software Foundation raise funds for GNU development.''
178
179 This document is part of a collection distributed under the GNU Free
180 Documentation License. If you want to distribute this document
181 separately from the collection, you can do so by adding a copy of the
182 license to the document, as described in section 6 of the license.
183 @end quotation
184 @end copying
185
186 @comment Info directory entry for use by install-info. The indentation
187 @comment here is by request from the FSF folks.
188 @dircategory Emacs
189 @direntry
190 * CC Mode: (ccmode). Emacs mode for editing C, C++, Objective-C,
191 Java, Pike, AWK, and CORBA IDL code.
192 @end direntry
193
194 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
195 @comment TeX title page
196 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
197
198 @titlepage
199 @sp 10
200
201 @center @titlefont{CC Mode 5.31}
202 @sp 2
203 @center @subtitlefont{A GNU Emacs mode for editing C and C-like languages}
204 @sp 2
205 @center Barry A. Warsaw, Martin Stjernholm, Alan Mackenzie
206
207 @page
208 @vskip 0pt plus 1filll
209 @insertcopying
210
211 This manual was generated from $Revision$ of $RCSfile$, which can be
212 downloaded from
213 @url{http://cvs.savannah.gnu.org/viewcvs/emacs/emacs/man/cc-mode.texi}.
214 @end titlepage
215
216 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
217 @comment The Top node contains the master menu for the Info file.
218 @comment This appears only in the Info file, not the printed manual.
219 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
220
221 @node Top, Introduction, (dir), (dir)
222 @comment node-name, next, previous, up
223
224 @ifinfo
225 @top @ccmode{}
226
227 @ccmode{} is a GNU Emacs mode for editing files containing C, C++,
228 Objective-C, Java, CORBA IDL (and the variants PSDL and CIDL), Pike
229 and AWK code. It provides syntax-based indentation, font locking, and
230 has several handy commands and some minor modes to make the editing
231 easier. It does not provide tools to look up and navigate between
232 functions, classes etc - there are other packages for that.
233 @end ifinfo
234
235 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
236 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
237
238 @menu
239 * Introduction::
240 * Overview::
241 * Getting Started::
242 * Commands::
243 * Font Locking::
244 * Config Basics::
245 * Custom Filling and Breaking::
246 * Custom Auto-newlines::
247 * Clean-ups::
248 * Indentation Engine Basics::
249 * Customizing Indentation::
250 * Custom Macros::
251 * Odds and Ends::
252 * Sample .emacs File::
253 * Performance Issues::
254 * Limitations and Known Bugs::
255 * FAQ::
256 * Updating CC Mode::
257 * Mailing Lists and Bug Reports::
258 * GNU Free Documentation License::
259 * Command and Function Index::
260 * Variable Index::
261 * Concept and Key Index::
262
263 @detailmenu
264 --- The Detailed Node Listing ---
265
266 Commands
267
268 * Indentation Commands::
269 * Comment Commands::
270 * Movement Commands::
271 * Filling and Breaking::
272 * Minor Modes::
273 * Electric Keys::
274 * Auto-newlines::
275 * Hungry WS Deletion::
276 * Subword Movement::
277 * Other Commands::
278
279 Font Locking
280
281 * Font Locking Preliminaries::
282 * Faces::
283 * Doc Comments::
284 * AWK Mode Font Locking::
285
286 Configuration Basics
287
288 * CC Hooks::
289 * Style Variables::
290 * Styles::
291
292 Styles
293
294 * Built-in Styles::
295 * Choosing a Style::
296 * Adding Styles::
297 * File Styles::
298
299 Customizing Auto-newlines
300
301 * Hanging Braces::
302 * Hanging Colons::
303 * Hanging Semicolons and Commas::
304
305 Hanging Braces
306
307 * Custom Braces::
308
309 Indentation Engine Basics
310
311 * Syntactic Analysis::
312 * Syntactic Symbols::
313 * Indentation Calculation::
314
315 Syntactic Symbols
316
317 * Function Symbols::
318 * Class Symbols::
319 * Conditional Construct Symbols::
320 * Switch Statement Symbols::
321 * Brace List Symbols::
322 * External Scope Symbols::
323 * Paren List Symbols::
324 * Literal Symbols::
325 * Multiline Macro Symbols::
326 * Objective-C Method Symbols::
327 * Anonymous Class Symbol::
328 * Statement Block Symbols::
329 * K&R Symbols::
330
331 Customizing Indentation
332
333 * c-offsets-alist::
334 * Interactive Customization::
335 * Line-Up Functions::
336 * Custom Line-Up::
337 * Other Indentation::
338
339 Line-Up Functions
340
341 * Brace/Paren Line-Up::
342 * List Line-Up::
343 * Operator Line-Up::
344 * Comment Line-Up::
345 * Misc Line-Up::
346
347 @end detailmenu
348 @end menu
349
350 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
351 @node Introduction, Overview, Top, Top
352 @comment node-name, next, previous, up
353 @chapter Introduction
354 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
355
356 @cindex BOCM
357 @cindex history
358 @cindex awk-mode.el
359 @cindex c-mode.el
360 @cindex c++-mode.el
361
362 Welcome to @ccmode{}, a GNU Emacs mode for editing files containing C,
363 C++, Objective-C, Java, CORBA IDL (and the variants CORBA PSDL and
364 CIDL), Pike and AWK code. This incarnation of the mode is descended
365 from @file{c-mode.el} (also called ``Boring Old C Mode'' or BOCM
366 @t{:-)}, @file{c++-mode.el} version 2, which Barry Warsaw had been
367 maintaining since 1992, and @file{awk-mode.el}, a long neglected mode
368 in the (X)Emacs base.
369
370 Late in 1997, Martin Stjernholm joined Barry on the @ccmode{}
371 Maintainers Team, and implemented the Pike support. In 2000 Martin
372 took over as the sole maintainer. In 2001 Alan Mackenzie joined the
373 team, implementing AWK support in version 5.30. @ccmode{} did not
374 originally contain the font lock support for its languages --- that
375 was added in version 5.30.
376
377 This manual describes @ccmode{}
378 @comment The following line must appear on its own, so that the
379 version 5.31.
380 @comment Release.py script can update the version number automatically
381
382 @ccmode{} supports the editing of K&R and ANSI C, C++, Objective-C,
383 Java, CORBA's Interface Definition Language, Pike@footnote{A C-like
384 scripting language with its roots in the LPC language used in some MUD
385 engines. See @uref{http://pike.ida.liu.se/}.} and AWK files. In this
386 way, you can easily set up consistent font locking and coding styles for
387 use in editing all of these languages, although AWK is not yet as
388 uniformly integrated as the other languages.
389
390 @findex c-mode
391 @findex c++-mode
392 @findex objc-mode
393 @findex java-mode
394 @findex idl-mode
395 @findex pike-mode
396 @findex awk-mode
397 Note that the name of this package is ``@ccmode{}'', but there is no top
398 level @code{cc-mode} entry point. All of the variables, commands, and
399 functions in @ccmode{} are prefixed with @code{c-@var{thing}}, and
400 @code{c-mode}, @code{c++-mode}, @code{objc-mode}, @code{java-mode},
401 @code{idl-mode}, @code{pike-mode}, and @code{awk-mode} entry points are
402 provided. This package is intended to be a replacement for
403 @file{c-mode.el}, @file{c++-mode.el} and @file{awk-mode.el}.
404
405 A special word of thanks goes to Krishna Padmasola for his work in
406 converting the original @file{README} file to Texinfo format. I'd
407 also like to thank all the @ccmode{} victims who help enormously
408 during the early beta stages of @ccmode{}'s development.
409
410 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
411 @node Overview, Getting Started, Introduction, Top
412 @comment node-name, next, previous, up@cindex organization of the manual
413 @chapter Overview of the Manual
414 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
415
416 @noindent
417 The manual starts with several introductory chapters (including this
418 one).
419
420 @noindent
421 The next chunk of the manual describes the day to day @emph{use} of
422 @ccmode{} (as contrasted with how to customize it).
423
424 @itemize @bullet
425 @item
426 The chapter ``Commands'' describes in detail how to use (nearly) all
427 of @ccmode{}'s features. There are extensive cross-references from
428 here to the corresponding sections later in the manual which tell you
429 how to customize these features.
430
431 @item
432 ``Font Locking'' describes how ``syntax highlighting'' is applied to
433 your buffers. It is mainly background information and can be skipped
434 over at a first reading.
435 @end itemize
436
437 @noindent
438 The next chunk of the manual describes how to @emph{customize}
439 @ccmode{}. Typically, an overview of a topic is given at the chapter
440 level, then the sections and subsections describe the material in
441 increasing detail.
442
443 @itemize @bullet
444 @item
445 The chapter ``Configuration Basics'' tells you @emph{how} to write
446 customizations - whether in hooks, in styles, in both, or in neither,
447 depending on your needs. It describes the @ccmode{} style system and
448 lists the standard styles that @ccmode{} supplies.
449
450 @item
451 The next few chapters describe in detail how to customize the various
452 features of @ccmode{}.
453
454 @item
455 Finally, there is a sample @file{.emacs} fragment, which might help you
456 in creating your own customization.
457 @end itemize
458
459 @noindent
460 The manual ends with ``this and that'', things that don't fit cleanly
461 into any of the previous chunks.
462
463 @itemize @bullet
464 @item
465 Two chapters discuss the performance of @ccmode{} and known
466 bugs/limitations.
467
468 @item
469 The FAQ contains a list of common problems and questions.
470
471 @item
472 The next two chapters tell you how to get in touch with the @ccmode{}
473 project - whether for updating @ccmode{} or submitting bug reports.
474 @end itemize
475
476 @noindent
477 Finally, there are the customary indices.
478
479 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
480 @node Getting Started, Commands, Overview, Top
481 @comment node-name, next, previous, up
482 @chapter Getting Started
483 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
484
485 If you got this version of @ccmode{} with Emacs or XEmacs, it should
486 work just fine right out of the box. Note however that you might not
487 have the latest @ccmode{} release and might want to upgrade your copy
488 (see below).
489
490 You should probably start by skimming through the entire chapter
491 @ref{Commands} to get an overview of @ccmode{}'s capabilities.
492
493 After trying out some commands, you may dislike some aspects of
494 @ccmode{}'s default configuration. Here is an outline of how to
495 change some of the settings that newcomers to @ccmode{} most often
496 want to change:
497
498 @table @asis
499 @item c-basic-offset
500 This Lisp variable holds an integer, the number of columns @ccmode{}
501 indents nested code. To set this value to 6, customize
502 @code{c-basic-offset} or put this into your @file{.emacs}:
503
504 @example
505 (setq c-basic-offset 6)
506 @end example
507
508 @item The (indentation) style
509 The basic ``shape'' of indentation created by @ccmode{}---by default,
510 this is @code{gnu} style (except for Java and AWK buffers). A list of
511 the available styles and their descriptions can be found in
512 @ref{Built-in Styles}. A complete specification of the @ccmode{}
513 style system, including how to create your own style, can be found in
514 the chapter @ref{Styles}. To set your style to @code{linux}, either
515 customize @code{c-default-style} or put this into your @file{.emacs}:
516
517 @example
518 (setq c-default-style '((java-mode . "java")
519 (awk-mode . "awk")
520 (other . "linux")))
521 @end example
522
523 @item Electric Indentation
524 Normally, when you type ``punctuation'' characters such as @samp{;} or
525 @samp{@{}, @ccmode{} instantly reindents the current line. This can
526 be disconcerting until you get used to it. To disable @dfn{electric
527 indentation} in the current buffer, type @kbd{C-c C-l}. Type the same
528 thing to enable it again. To have electric indentation disabled by
529 default, put the following into your @file{.emacs} file@footnote{There
530 is no ``easy customization'' facility for making this change.}:
531
532 @example
533 (setq-default c-electric-flag nil)
534 @end example
535
536 @noindent
537 Details of this and other similar ``Minor Modes'' appear in the
538 section @ref{Minor Modes}.
539
540 @item Making the @key{RET} key indent the new line
541 The standard Emacs binding for @key{RET} just adds a new line. If you
542 want it to reindent the new line as well, rebind the key. Note that
543 the action of rebinding would fail if the pertinent keymap didn't yet
544 exist---we thus need to delay the action until after @ccmode{} has
545 been loaded. Put the following code into your @file{.emacs}:
546
547 @example
548 (defun my-make-CR-do-indent ()
549 (define-key c-mode-base-map "\C-m" 'c-context-line-break))
550 (add-hook 'c-initialization-hook 'my-make-CR-do-indent)
551 @end example
552
553 @noindent
554 This example demonstrates the use of a very powerful @ccmode{} (and
555 Emacs) facility, the hook. The use of @ccmode{}'s hooks is described
556 in @ref{CC Hooks}.
557 @end table
558
559 All these settings should occur in your @file{.emacs} @emph{before}
560 any @ccmode{} buffers get loaded---in particular, before any call of
561 @code{desktop-read}.
562
563 As you get to know the mode better, you may want to make more
564 ambitious changes to your configuration. For this, you should start
565 reading the chapter @ref{Config Basics}.
566
567 If you are upgrading an existing @ccmode{} installation, please see
568 the @file{README} file for installation details. In particular, if
569 you are going to be editing AWK files, @file{README} describes how to
570 configure your (X)Emacs so that @ccmode{} will supersede the obsolete
571 @code{awk-mode.el} which might have been supplied with your (X)Emacs.
572 @ccmode{} might not work with older versions of Emacs or XEmacs. See
573 the @ccmode{} release notes at @uref{http://cc-mode.sourceforge.net}
574 for the latest information on Emacs version and package compatibility
575 (@pxref{Updating CC Mode}).
576
577 @deffn Command c-version
578 @findex version (c-)
579 You can find out what version of @ccmode{} you are using by visiting a C
580 file and entering @kbd{M-x c-version RET}. You should see this message in
581 the echo area:
582
583 @example
584 Using CC Mode version 5.XX
585 @end example
586
587 @noindent
588 where @samp{XX} is the minor release number.
589 @end deffn
590
591 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
592 @node Commands, Font Locking, Getting Started, Top
593 @comment node-name, next, previous, up
594 @chapter Commands
595 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
596
597 This chapter specifies all of CC Mode's commands, and thus contains
598 nearly everything you need to know to @emph{use} @ccmode{} (as
599 contrasted with configuring it). @dfn{Commands} here means both
600 control key sequences and @dfn{electric keys}, these being characters
601 such as @samp{;} which, as well as inserting themselves into the
602 buffer, also do other things.
603
604 You might well want to review
605 @ifset XEMACS
606 @ref{Lists,,,@emacsman{}, @emacsmantitle{}},
607 @end ifset
608 @ifclear XEMACS
609 @ref{Moving by Parens,,,@emacsman{}, @emacsmantitle{}},
610 @end ifclear
611 which describes commands for moving around brace and parenthesis
612 structures.
613
614
615 @menu
616 * Indentation Commands::
617 * Comment Commands::
618 * Movement Commands::
619 * Filling and Breaking::
620 * Minor Modes::
621 * Electric Keys::
622 * Auto-newlines::
623 * Hungry WS Deletion::
624 * Subword Movement::
625 * Other Commands::
626 @end menu
627
628 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
629 @node Indentation Commands, Comment Commands, Commands, Commands
630 @comment node-name, next, previous,up
631 @section Indentation Commands
632 @cindex indentation
633 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
634
635 The following commands reindent C constructs. Note that when you
636 change your coding style, either interactively or through some other
637 means, your file does @emph{not} automatically get reindented. You
638 will need to execute one of the following commands to see the effects
639 of your changes.
640
641 @cindex GNU indent program
642 Also, variables like @code{c-hanging-*} and @code{c-cleanup-list}
643 (@pxref{Custom Auto-newlines}) only affect how on-the-fly code is
644 formatted. Changing the ``hanginess'' of a brace and then
645 reindenting, will not move the brace to a different line. For this,
646 you're better off getting an external program like GNU @code{indent},
647 which will rearrange brace location, amongst other things.
648
649 Preprocessor directives are handled as syntactic whitespace from other
650 code, i.e. they can be interspersed anywhere without affecting the
651 indentation of the surrounding code, just like comments.
652
653 The code inside macro definitions is, by default, still analyzed
654 syntactically so that you get relative indentation there just as you'd
655 get if the same code was outside a macro. However, since there is no
656 hint about the syntactic context, i.e. whether the macro expands to an
657 expression, to some statements, or perhaps to whole functions, the
658 syntactic recognition can be wrong. @ccmode{} manages to figure it
659 out correctly most of the time, though.
660
661 Reindenting large sections of code can take a long time. When
662 @ccmode{} reindents a region of code, it is essentially equivalent to
663 hitting @key{TAB} on every line of the region.
664
665 These commands indent code:
666
667 @table @asis
668 @item @kbd{@key{TAB}} (@code{c-indent-command})
669 @kindex TAB
670 @findex c-indent-command
671 @findex indent-command (c-)
672 This command indents the current line. That is all you need to know
673 about it for normal use.
674
675 @code{c-indent-command} does different things, depending on the
676 setting of @code{c-syntactic-indentation} (@pxref{Indentation Engine
677 Basics}):
678
679 @itemize @bullet
680 @item
681 When it's non-@code{nil} (which it normally is), the command indents
682 the line according to its syntactic context. With a prefix argument
683 (@kbd{C-u @key{TAB}}), it will re-indent the entire
684 expression@footnote{this is only useful for a line starting with a
685 comment opener or an opening brace, parenthesis, or string quote.}
686 that begins at the line's left margin.
687
688 @item
689 When it's @code{nil}, the command indents the line by an extra
690 @code{c-basic-offset} columns. A prefix argument acts as a
691 multiplier. A bare prefix (@kbd{C-u @key{TAB}}) is equivalent to -1,
692 removing @code{c-basic-offset} columns from the indentation.
693 @end itemize
694
695 The precise behavior is modified by several variables: With
696 @code{c-tab-always-indent}, you can make @key{TAB} insert whitespace
697 in some circumstances---@code{c-insert-tab-function} then defines
698 precisely what sort of ``whitespace'' this will be. Set the standard
699 Emacs variable @code{indent-tabs-mode} to @code{t} if you want real
700 @samp{tab} characters to be used in the indentation, to @code{nil} if
701 you want only spaces. @xref{Just Spaces,,, @emacsman{},
702 @emacsmantitle{}}.
703
704 @defopt c-tab-always-indent
705 @vindex tab-always-indent (c-)
706 @cindex literal
707 This variable modifies how @key{TAB} operates.
708 @itemize @bullet
709 @item
710 When it is @code{t} (the default), @key{TAB} simply indents the
711 current line.
712 @item
713 When it is @code{nil}, @key{TAB} (re)indents the line only if point is
714 to the left of the first non-whitespace character on the line.
715 Otherwise it inserts some whitespace (a tab or an equivalent number of
716 spaces - see below) at point.
717 @item
718 With some other value, the line is reindented. Additionally, if point
719 is within a string or comment, some whitespace is inserted.
720 @end itemize
721 @end defopt
722
723 @defopt c-insert-tab-function
724 @vindex insert-tab-function (c-)
725 @findex tab-to-tab-stop
726 When ``some whitespace'' is inserted as described above, what actually
727 happens is that the function stored in @code{c-insert-tab-function} is
728 called. Normally, this is @code{insert-tab}, which inserts a real tab
729 character or the equivalent number of spaces (depending on
730 @code{indent-tabs-mode}). Some people, however, set
731 @code{c-insert-tab-function} to @code{tab-to-tab-stop} so as to get
732 hard tab stops when indenting.
733 @end defopt
734 @end table
735
736 @noindent
737 The kind of indentation the next five commands do depends on the
738 setting of @code{c-syntactic-indentation} (@pxref{Indentation Engine
739 Basics}):
740 @itemize @bullet
741 @item
742 when it is non-@code{nil} (the default), the commands indent lines
743 according to their syntactic context;
744 @item
745 when it is @code{nil}, they just indent each line the same amount as
746 the previous non-blank line. The commands that indent a region aren't
747 very useful in this case.
748 @end itemize
749
750 @table @asis
751 @item @kbd{C-j} (@code{newline-and-indent})
752 @kindex C-j
753 @findex newline-and-indent
754 Inserts a newline and indents the new blank line, ready to start
755 typing. This is a standard (X)Emacs command.
756
757 @item @kbd{C-M-q} (@code{c-indent-exp})
758 @kindex C-M-q
759 @findex c-indent-exp
760 @findex indent-exp (c-)
761 Indents an entire balanced brace or parenthesis expression. Note that
762 point must be on the opening brace or parenthesis of the expression
763 you want to indent.
764
765 @item @kbd{C-c C-q} (@code{c-indent-defun})
766 @kindex C-c C-q
767 @findex c-indent-defun
768 @findex indent-defun (c-)
769 Indents the entire top-level function, class or macro definition
770 encompassing point. It leaves point unchanged. This function can't be
771 used to reindent a nested brace construct, such as a nested class or
772 function, or a Java method. The top-level construct being reindented
773 must be complete, i.e. it must have both a beginning brace and an ending
774 brace.
775
776 @item @kbd{C-M-\} (@code{indent-region})
777 @kindex C-M-\
778 @findex indent-region
779 Indents an arbitrary region of code. This is a standard Emacs command,
780 tailored for C code in a @ccmode{} buffer. Note, of course, that point
781 and mark must delineate the region you want to indent.
782
783 @item @kbd{C-M-h} (@code{c-mark-function})
784 @kindex C-M-h
785 @findex c-mark-function
786 @findex mark-function (c-)
787 While not strictly an indentation command, this is useful for marking
788 the current top-level function or class definition as the current
789 region. As with @code{c-indent-defun}, this command operates on
790 top-level constructs, and can't be used to mark say, a Java method.
791 @end table
792
793 These variables are also useful when indenting code:
794
795 @defopt indent-tabs-mode
796 This is a standard Emacs variable that controls how line indentation
797 is composed. When it's non-@code{nil}, tabs can be used in a line's
798 indentation, otherwise only spaces are used.
799 @end defopt
800
801 @defopt c-progress-interval
802 @vindex progress-interval (c-)
803 When indenting large regions of code, this variable controls how often a
804 progress message is displayed. Set this variable to @code{nil} to
805 inhibit the progress messages, or set it to an integer which is how
806 often (in seconds) progress messages are to be displayed.
807 @end defopt
808
809 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
810 @node Comment Commands, Movement Commands, Indentation Commands, Commands
811 @comment node-name, next, previous, up
812 @section Comment Commands
813 @cindex comments (insertion of)
814 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
815
816 @table @asis
817 @item @kbd{C-c C-c} (@code{comment-region})
818 @kindex C-c C-c
819 @findex comment-region
820 This command comments out the lines that start in the region. With a
821 negative argument, it does the opposite - it deletes the comment
822 delimiters from these lines. @xref{Multi-Line Comments,,, emacs, GNU
823 Emacs Manual}, for fuller details. @code{comment-region} isn't
824 actually part of @ccmode{} - it is given a @ccmode{} binding for
825 convenience.
826
827 @item @kbd{M-;} (@code{comment-dwim} or @code{indent-for-comment} @footnote{The name of this command varies between (X)Emacs versions.})
828 @kindex M-;
829 @findex comment-dwim
830 @findex indent-for-comment
831 Insert a comment at the end of the current line, if none is there
832 already. Then reindent the comment according to @code{comment-column}
833 @ifclear XEMACS
834 (@pxref{Options for Comments,,, emacs, GNU Emacs Manual})
835 @end ifclear
836 @ifset XEMACS
837 (@pxref{Comments,,, xemacs, XEmacs User's Manual})
838 @end ifset
839 and the variables below. Finally, position the point after the
840 comment starter. @kbd{C-u M-;} kills any comment on the current line,
841 together with any whitespace before it. This is a standard Emacs
842 command, but @ccmode{} enhances it a bit with two variables:
843
844 @defopt c-indent-comment-alist
845 @vindex indent-comment-alist (c-)
846 @vindex comment-column
847 This style variable allows you to vary the column that @kbd{M-;} puts
848 the comment at, depending on what sort of code is on the line, and
849 possibly the indentation of any similar comment on the preceding line.
850 It is an association list that maps different types of lines to
851 actions describing how they should be handled. If a certain line type
852 isn't present on the list then the line is indented to the column
853 specified by @code{comment-column}.
854
855 See the documentation string for a full description of this
856 variable (use @kbd{C-h v c-indent-comment-alist}).
857 @end defopt
858
859 @defopt c-indent-comments-syntactically-p
860 @vindex indent-comments-syntactically-p (c-)
861 Normally, when this style variable is @code{nil}, @kbd{M-;} will
862 indent comment-only lines according to @code{c-indent-comment-alist},
863 just as it does with lines where other code precede the comments.
864 However, if you want it to act just like @key{TAB} for comment-only
865 lines you can get that by setting
866 @code{c-indent-comments-syntactically-p} to non-@code{nil}.
867
868 If @code{c-indent-comments-syntactically-p} is non-@code{nil} then
869 @code{c-indent-comment-alist} won't be consulted at all for comment-only
870 lines.
871 @end defopt
872 @end table
873
874 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
875 @node Movement Commands, Filling and Breaking, Comment Commands, Commands
876 @comment node-name, next, previous, up
877 @section Movement Commands
878 @cindex movement
879 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
880
881 @ccmode{} contains some useful commands for moving around in C code.
882
883 @table @asis
884 @item @kbd{C-M-a} (@code{c-beginning-of-defun})
885 @itemx @kbd{C-M-e} (@code{c-end-of-defun})
886 @findex c-beginning-of-defun
887 @findex c-end-of-defun
888
889 Move to the beginning or end of the current or next function. Other
890 constructs (such as a structs or classes) which have a brace block
891 also count as ``functions'' here. To move over several functions, you
892 can give these commands a repeat count.
893
894 The start of a function is at its header. The end of the function is
895 after its closing brace, or after the semicolon of a construct (such
896 as a @code{struct}) which doesn't end at the brace. These two
897 commands try to leave point at the beginning of a line near the actual
898 start or end of the function. This occasionally causes point not to
899 move at all.
900
901 These functions are analogous to the Emacs built-in commands
902 @code{beginning-of-defun} and @code{end-of-defun}, except they
903 eliminate the constraint that the top-level opening brace of the defun
904 must be in column zero. See @ref{Defuns,,,@emacsman{},
905 @emacsmantitle{}}, for more information.
906
907 @item @kbd{C-M-a} (AWK Mode) (@code{c-awk-beginning-of-defun})
908 @itemx @kbd{C-M-e} (AWK Mode) (@code{c-awk-end-of-defun})
909 @kindex C-M-a (AWK Mode)
910 @kindex C-M-e (AWK Mode)
911 @findex c-awk-beginning-of-defun
912 @findex awk-beginning-of-defun (c-)
913 @findex c-awk-end-of-defun
914 @findex awk-end-of-defun (c-)
915 Move to the beginning or end of the current or next AWK defun. These
916 commands can take prefix-arguments, their functionality being entirely
917 equivalent to @code{beginning-of-defun} and @code{end-of-defun}.
918
919 AWK Mode @dfn{defuns} are either pattern/action pairs (either of which
920 might be implicit) or user defined functions. Having the @samp{@{} and
921 @samp{@}} (if there are any) in column zero, as is suggested for some
922 modes, is neither necessary nor helpful in AWK mode.
923
924 @item @kbd{M-a} (@code{c-beginning-of-statement})
925 @itemx @kbd{M-e} (@code{c-end-of-statement})
926 @kindex M-a
927 @kindex M-e
928 @findex c-beginning-of-statement
929 @findex c-end-of-statement
930 @findex beginning-of-statement (c-)
931 @findex end-of-statement (c-)
932 Move to the beginning or end of the innermost C statement. If point
933 is already there, move to the next beginning or end of a statement,
934 even if that means moving into a block. (Use @kbd{C-M-b} or
935 @kbd{C-M-f} to move over a balanced block.) A prefix argument @var{n}
936 means move over @var{n} statements.
937
938 If point is within or next to a comment or a string which spans more
939 than one line, these commands move by sentences instead of statements.
940
941 When called from a program, these functions take three optional
942 arguments: the repetition count, a buffer position limit which is the
943 farthest back to search for the syntactic context, and a flag saying
944 whether to do sentence motion in or near comments and multiline
945 strings.
946
947 @item @kbd{C-c C-u} (@code{c-up-conditional})
948 @kindex C-c C-u
949 @findex c-up-conditional
950 @findex up-conditional (c-)
951 Move back to the containing preprocessor conditional, leaving the mark
952 behind. A prefix argument acts as a repeat count. With a negative
953 argument, move forward to the end of the containing preprocessor
954 conditional.
955
956 @samp{#elif} is treated like @samp{#else} followed by @samp{#if}, so the
957 function stops at them when going backward, but not when going
958 forward.
959
960 This key sequence is not bound in AWK Mode, which doesn't have
961 preprocessor statements.
962
963 @item @kbd{M-x c-up-conditional-with-else}
964 @findex c-up-conditional-with-else
965 @findex up-conditional-with-else (c-)
966 A variety of @code{c-up-conditional} that also stops at @samp{#else}
967 lines. Normally those lines are ignored.
968
969 @item @kbd{M-x c-down-conditional}
970 @findex c-down-conditional
971 @findex down-conditional (c-)
972 Move forward into the next nested preprocessor conditional, leaving
973 the mark behind. A prefix argument acts as a repeat count. With a
974 negative argument, move backward into the previous nested preprocessor
975 conditional.
976
977 @samp{#elif} is treated like @samp{#else} followed by @samp{#if}, so the
978 function stops at them when going forward, but not when going backward.
979
980 @item @kbd{M-x c-down-conditional-with-else}
981 @findex c-down-conditional-with-else
982 @findex down-conditional-with-else (c-)
983 A variety of @code{c-down-conditional} that also stops at @samp{#else}
984 lines. Normally those lines are ignored.
985
986 @item @kbd{C-c C-p} (@code{c-backward-conditional})
987 @itemx @kbd{C-c C-n} (@code{c-forward-conditional})
988 @kindex C-c C-p
989 @kindex C-c C-n
990 @findex c-backward-conditional
991 @findex c-forward-conditional
992 @findex backward-conditional (c-)
993 @findex forward-conditional (c-)
994 Move backward or forward across a preprocessor conditional, leaving
995 the mark behind. A prefix argument acts as a repeat count. With a
996 negative argument, move in the opposite direction.
997
998 These key sequences are not bound in AWK Mode, which doesn't have
999 preprocessor statements.
1000
1001 @item @kbd{M-x c-backward-into-nomenclature}
1002 @itemx @kbd{M-x c-forward-into-nomenclature}
1003 @findex c-backward-into-nomenclature
1004 @findex c-forward-into-nomenclature
1005 @findex backward-into-nomenclature (c-)
1006 @findex forward-into-nomenclature (c-)
1007 A popular programming style, especially for object-oriented languages
1008 such as C++ is to write symbols in a mixed case format, where the
1009 first letter of each word is capitalized, and not separated by
1010 underscores. E.g. @samp{SymbolsWithMixedCaseAndNoUnderlines}.
1011
1012 These commands move backward or forward to the beginning of the next
1013 capitalized word. With prefix argument @var{n}, move @var{n} times.
1014 If @var{n} is negative, move in the opposite direction.
1015
1016 Note that these two commands have been superseded by
1017 @code{c-subword-mode}, which you should use instead. @xref{Subword
1018 Movement}. They might be removed from a future release of @ccmode{}.
1019 @end table
1020
1021 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1022 @node Filling and Breaking, Minor Modes, Movement Commands, Commands
1023 @comment node-name, next, previous, up
1024 @section Filling and Line Breaking Commands
1025 @cindex text filling
1026 @cindex line breaking
1027 @cindex comment handling
1028 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1029
1030 Since there's a lot of normal text in comments and string literals,
1031 @ccmode{} provides features to edit these like in text mode. The goal
1032 is to do it seamlessly, i.e. you can use auto fill mode, sentence and
1033 paragraph movement, paragraph filling, adaptive filling etc. wherever
1034 there's a piece of normal text without having to think much about it.
1035 @ccmode{} keeps the indentation, fixes suitable comment line prefixes,
1036 and so on.
1037
1038 You can configure the exact way comments get filled and broken, and
1039 where Emacs does auto-filling (see @pxref{Custom Filling and
1040 Breaking}). Typically, the style system (@pxref{Styles}) will have
1041 set this up for you, so you probably won't have to bother.
1042
1043 @findex auto-fill-mode
1044 @cindex Auto Fill mode
1045 @cindex paragraph filling
1046 Line breaks are by default handled (almost) the same regardless of
1047 whether they are made by auto fill mode (@pxref{Auto Fill,,,
1048 @emacsman{}, @emacsmantitle{}}), by paragraph filling (e.g. with
1049 @kbd{M-q}), or explicitly with @kbd{M-j} or similar methods. In
1050 string literals, the new line gets the same indentation as the
1051 previous nonempty line.@footnote{You can change this default by
1052 setting the @code{string} syntactic symbol (@pxref{Syntactic Symbols}
1053 and @pxref{Customizing Indentation})}.
1054
1055 @table @asis
1056 @item @kbd{M-q} (@code{c-fill-paragraph})
1057 @kindex M-q
1058 @findex c-fill-paragraph
1059 @findex fill-paragraph (c-)
1060 @cindex Javadoc markup
1061 @cindex Pike autodoc markup
1062 This command fills multiline string literals and both block
1063 and line style comments. In Java buffers, the Javadoc markup words
1064 are recognized as paragraph starters. The line oriented Pike autodoc
1065 markup words are recognized in the same way in Pike mode.
1066
1067 The formatting of the starters (@code{/*}) and enders (@code{*/}) of
1068 block comments are kept as they were before the filling. I.e., if
1069 either the starter or ender were on a line of its own, then it stays
1070 on its own line; conversely, if the delimiter has comment text on its
1071 line, it keeps at least one word of that text with it on the line.
1072
1073 This command is the replacement for @code{fill-paragraph} in @ccmode{}
1074 buffers.
1075
1076 @item @kbd{M-j} (@code{c-indent-new-comment-line})
1077 @kindex M-j
1078 @findex c-indent-new-comment-line
1079 @findex indent-new-comment-line (c-)
1080 This breaks the current line at point and indents the new line. If
1081 point was in a comment, the new line gets the proper comment line
1082 prefix. If point was inside a macro, a backslash is inserted before
1083 the line break. It is the replacement for
1084 @code{indent-new-comment-line}.
1085
1086 @item @kbd{M-x c-context-line-break}
1087 @findex c-context-line-break
1088 @findex context-line-break (c-)
1089 Insert a line break suitable to the context: If the point is inside a
1090 comment, the new line gets the suitable indentation and comment line
1091 prefix like @code{c-indent-new-comment-line}. In normal code it's
1092 indented like @code{newline-and-indent} would do. In macros it acts
1093 like @code{newline-and-indent} but additionally inserts and optionally
1094 aligns the line ending backslash so that the macro remains unbroken.
1095 @xref{Custom Macros}, for details about the backslash alignment. In a
1096 string, a backslash is inserted only if the string is within a
1097 macro@footnote{In GCC, unescaped line breaks within strings are
1098 valid.}.
1099
1100 This function is not bound to a key by default, but it's intended to be
1101 used on the @kbd{RET} key. If you like the behavior of
1102 @code{newline-and-indent} on @kbd{RET}, you should consider switching to
1103 this function. @xref{Sample .emacs File}.
1104
1105 @item @kbd{M-x c-context-open-line}
1106 @findex c-context-open-line
1107 @findex context-open-line (c-)
1108 This is to @kbd{C-o} (@kbd{M-x open-line}) as
1109 @code{c-context-line-break} is to @kbd{RET}. I.e. it works just like
1110 @code{c-context-line-break} but leaves the point before the inserted
1111 line break.
1112 @end table
1113
1114
1115 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1116 @node Minor Modes, Electric Keys, Filling and Breaking, Commands
1117 @comment node-name, next, previous, up
1118 @section Minor Modes
1119 @cindex Minor Modes
1120 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1121
1122 @ccmode{} contains several minor-mode-like features that you might
1123 find useful while writing new code or editing old code:
1124
1125 @table @asis
1126 @item electric mode
1127 When this is enabled, certain visible characters cause reformatting as
1128 they are typed. This is normally helpful, but can be a nuisance when
1129 editing chaotically formatted code. It can also be disconcerting,
1130 especially for users who are new to @ccmode{}.
1131 @item auto-newline mode
1132 This automatically inserts newlines where you'd probably want to type
1133 them yourself, e.g. after typing @samp{@}}s. Its action is suppressed
1134 when electric mode is disabled.
1135 @item hungry-delete mode
1136 This lets you delete a contiguous block of whitespace with a single
1137 key - for example, the newline and indentation just inserted by
1138 auto-newline when you want to back up and write a comment after the
1139 last statement.
1140 @item subword mode
1141 This mode makes basic word movement commands like @kbd{M-f}
1142 (@code{forward-word}) and @kbd{M-b} (@code{backward-word}) treat the
1143 parts of sillycapsed symbols as different words.
1144 E.g. @samp{NSGraphicsContext} is treated as three words @samp{NS},
1145 @samp{Graphics}, and @samp{Context}.
1146 @item syntactic-indentation mode
1147 When this is enabled (which it normally is), indentation commands such
1148 as @kbd{C-j} indent lines of code according to their syntactic
1149 structure. Otherwise, a line is simply indented to the same level as
1150 the previous one and @kbd{@key{TAB}} adjusts the indentation in steps
1151 of `c-basic-offset'.
1152 @end table
1153
1154 Full details on how these minor modes work are at @ref{Electric Keys},
1155 @ref{Auto-newlines}, @ref{Hungry WS Deletion}, @ref{Subword Movement},
1156 and @ref{Indentation Engine Basics}.
1157
1158 You can toggle each of these minor modes on and off, and you can
1159 configure @ccmode{} so that it starts up with your favourite
1160 combination of them (@pxref{Sample .emacs File}). By default, when
1161 you initialize a buffer, electric mode and syntactic-indentation mode
1162 are enabled but the other two modes are disabled.
1163
1164 @ccmode{} displays the current state of the first four of these minor
1165 modes on the modeline by appending letters to the major mode's name,
1166 one letter for each enabled minor mode - @samp{l} for electric mode,
1167 @samp{a} for auto-newline mode, @samp{h} for hungry delete mode, and
1168 @samp{w} for subword mode. If all these modes were enabled, you'd see
1169 @samp{C/lahw}@footnote{The @samp{C} would be replaced with the name of
1170 the language in question for the other languages @ccmode{} supports.}.
1171
1172 Here are the commands to toggle these modes:
1173
1174 @table @asis
1175 @item @kbd{C-c C-l} (@code{c-toggle-electric-state})
1176 @kindex C-c C-l
1177 @findex c-toggle-electric-state
1178 @findex toggle-electric-state (c-)
1179 Toggle electric minor mode. When the command turns the mode off, it
1180 also suppresses auto-newline mode.
1181
1182 @item @kbd{C-c C-a} (@code{c-toggle-auto-newline})
1183 @kindex C-c C-a
1184 @findex c-toggle-auto-newline
1185 @findex toggle-auto-newline (c-)
1186 Toggle auto-newline minor mode. When the command turns the mode on,
1187 it also enables electric minor mode.
1188
1189 @item @kbd{M-x c-toggle-hungry-state}@footnote{Prior to @ccmode{} 5.31, this command was bound to @kbd{C-c C-d}.}
1190 @findex c-toggle-hungry-state
1191 @findex toggle-hungry-state (c-)
1192 Toggle hungry-delete minor mode.
1193
1194 @item @kbd{M-x c-toggle-auto-hungry-state}@footnote{Prior to @ccmode{} 5.31, this command was bound to @kbd{C-c C-t}.}
1195 @findex c-toggle-auto-hungry-state
1196 @findex toggle-auto-hungry-state (c-)
1197 Toggle both auto-newline and hungry delete minor modes.
1198
1199 @item @kbd{C-c C-w} (@code{M-x c-subword-mode})
1200 @kindex C-c C-w
1201 @findex c-subword-mode
1202 @findex subword-mode (c-)
1203 Toggle subword mode.
1204
1205 @item @kbd{M-x c-toggle-syntactic-indentation}
1206 @findex c-toggle-syntactic-indentation
1207 @findex toggle-syntactic-indentation (c-)
1208 Toggle syntactic-indentation mode.
1209 @end table
1210
1211 Common to all the toggle functions above is that if they are called
1212 programmatically, they take an optional numerical argument. A
1213 positive value will turn on the minor mode (or both of them in the
1214 case of @code{c-toggle-auto-hungry-state}) and a negative value will
1215 turn it (or them) off.
1216
1217
1218 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1219 @node Electric Keys, Auto-newlines, Minor Modes, Commands
1220 @comment node-name, next, previous, up
1221 @section Electric Keys and Keywords
1222 @cindex electric characters
1223 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1224
1225 Most punctuation keys provide @dfn{electric} behavior - as well as
1226 inserting themselves they perform some other action, such as
1227 reindenting the line. This reindentation saves you from having to
1228 reindent a line manually after typing, say, a @samp{@}}. A few
1229 keywords, such as @code{else}, also trigger electric action.
1230
1231 You can inhibit the electric behaviour described here by disabling
1232 electric minor mode (@pxref{Minor Modes}).
1233
1234 Common to all these keys is that they only behave electrically when
1235 used in normal code (as contrasted with getting typed in a string
1236 literal or comment). Those which cause re-indentation do so only when
1237 @code{c-syntactic-indentation} has a non-@code{nil} value (which it
1238 does by default).
1239
1240 These keys and keywords are:
1241 @c ACM, 2004/8/24: c-electric-pound doesn't check c-s-i: this is more
1242 @c like a bug in the code than a bug in this document. It'll get
1243 @c fixed in the code sometime.
1244
1245 @table @kbd
1246 @item #
1247 @kindex #
1248 @findex c-electric-pound
1249 @findex electric-pound (c-)
1250 @vindex c-electric-pound-behavior
1251 @vindex electric-pound-behavior (c-)
1252 Pound (bound to @code{c-electric-pound}) is electric when typed as the
1253 first non-whitespace character on a line and not within a macro
1254 definition. In this case, the variable @code{c-electric-pound-behavior}
1255 is consulted for the electric behavior. This variable takes a list
1256 value, although the only element currently defined is @code{alignleft},
1257 which tells this command to force the @samp{#} character into column
1258 zero. This is useful for entering preprocessor macro definitions.
1259
1260 Pound is not electric in AWK buffers, where @samp{#} starts a comment,
1261 and is bound to @code{self-insert-command} like any typical printable
1262 character.
1263 @c ACM, 2004/8/24: Change this (and the code) to do AWK comment
1264 @c reindentation.
1265
1266 @item *
1267 @kindex *
1268 @itemx /
1269 @kindex /
1270 @findex c-electric-star
1271 @findex electric-star (c-)
1272 @findex c-electric-slash
1273 @findex electric-slash (c-)
1274 A star (bound to @code{c-electric-star}) or a slash
1275 (@code{c-electric-slash}) causes reindentation when you type it as the
1276 second component of a C style block comment opener (@samp{/*}) or a
1277 C++ line comment opener (@samp{//}) respectively, but only if the
1278 comment opener is the first thing on the line (i.e. there's only
1279 whitespace before it).
1280
1281 Additionally, you can configure @ccmode{} so that typing a slash at
1282 the start of a line within a block comment will terminate the
1283 comment. You don't need to have electric minor mode enabled to get
1284 this behaviour. @xref{Clean-ups}.
1285
1286 In AWK mode, @samp{*} and @samp{/} do not delimit comments and are not
1287 electric.
1288
1289 @item <
1290 @kindex <
1291 @itemx >
1292 @kindex >
1293 @findex c-electric-lt-gt
1294 @findex electric-lt-gt (c-)
1295 A less-than or greater-than sign (bound to @code{c-electric-lt-gt}) is
1296 electric in two circumstances: when it is an angle bracket in a C++
1297 @samp{template} declaration (and similar constructs in other
1298 languages) and when it is the second of two @kbd{<} or @kbd{>}
1299 characters in a C++ style stream operator. In either case, the line
1300 is reindented. Angle brackets in C @samp{#include} directives are not
1301 electric.
1302
1303 @item (
1304 @kindex (
1305 @itemx )
1306 @kindex )
1307 @findex c-electric-paren
1308 @findex electric-paren (c-)
1309 The normal parenthesis characters @samp{(} and @samp{)} (bound to
1310 @code{c-electric-paren}) reindent the current line. This is useful
1311 for getting the closing parenthesis of an argument list aligned
1312 automatically.
1313
1314 You can also configure @ccmode{} to insert a space automatically
1315 between a function name and the @samp{(} you've just typed, and to
1316 remove it automatically after typing @samp{)}, should the argument
1317 list be empty. You don't need to have electric minor mode enabled to
1318 get these actions. @xref{Clean-ups}.
1319
1320 @item @{
1321 @kindex @{
1322 @itemx @}
1323 @kindex @}
1324 @findex c-electric-brace
1325 @findex electric-brace (c-)
1326 Typing a brace (bound to @code{c-electric-brace}) reindents the
1327 current line. Also, one or more newlines might be inserted if
1328 auto-newline minor mode is enabled. @xref{Auto-newlines}.
1329 Additionally, you can configure @ccmode{} to compact excess whitespace
1330 inserted by auto-newline mode in certain circumstances.
1331 @xref{Clean-ups}.
1332
1333 @item :
1334 @kindex :
1335 @findex c-electric-colon
1336 @findex electric-colon (c-)
1337 Typing a colon (bound to @code{c-electric-colon}) reindents the
1338 current line. Additionally, one or more newlines might be inserted if
1339 auto-newline minor mode is enabled. @xref{Auto-newlines}. If you
1340 type a second colon immediately after such an auto-newline, by default
1341 the whitespace between the two colons is removed, leaving a C++ scope
1342 operator. @xref{Clean-ups}.
1343
1344 If you prefer, you can insert @samp{::} in a single operation,
1345 avoiding all these spurious reindentations, newlines, and clean-ups.
1346 @xref{Other Commands}.
1347
1348 @item ;
1349 @kindex ;
1350 @itemx ,
1351 @kindex ,
1352 @findex c-electric-semi&comma
1353 @findex electric-semi&comma (c-)
1354 Typing a semicolon or comma (bound to @code{c-electric-semi&comma})
1355 reindents the current line. Also, a newline might be inserted if
1356 auto-newline minor mode is enabled. @xref{Auto-newlines}.
1357 Additionally, you can configure @ccmode{} so that when auto-newline
1358 has inserted whitespace after a @samp{@}}, it will be removed again
1359 when you type a semicolon or comma just after it. @xref{Clean-ups}.
1360
1361 @end table
1362
1363 @deffn Command c-electric-continued-statement
1364 @findex electric-continued-statement (c-)
1365
1366 Certain keywords are electric, causing reindentation when they are
1367 preceded only by whitespace on the line. The keywords are those that
1368 continue an earlier statement instead of starting a new one:
1369 @code{else}, @code{while}, @code{catch} (only in C++ and Java) and
1370 @code{finally} (only in Java).
1371
1372 An example:
1373
1374 @example
1375 @group
1376 for (i = 0; i < 17; i++)
1377 if (a[i])
1378 res += a[i]->offset;
1379 else
1380 @end group
1381 @end example
1382
1383 Here, the @code{else} should be indented like the preceding @code{if},
1384 since it continues that statement. @ccmode{} will automatically
1385 reindent it after the @code{else} has been typed in full, since only
1386 then is it possible to decide whether it's a new statement or a
1387 continuation of the preceding @code{if}.
1388
1389 @vindex abbrev-mode
1390 @findex abbrev-mode
1391 @cindex Abbrev mode
1392 @ccmode{} uses Abbrev mode (@pxref{Abbrevs,,, @emacsman{}, @emacsmantitle{}})
1393 to accomplish this. It's therefore turned on by default in all language
1394 modes except IDL mode, since CORBA IDL doesn't have any statements.
1395 @end deffn
1396
1397
1398 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1399 @node Auto-newlines, Hungry WS Deletion, Electric Keys, Commands
1400 @comment node-name, next, previous, up
1401 @section Auto-newline Insertion
1402 @cindex auto-newline
1403 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1404
1405 When you have @dfn{Auto-newline minor mode} enabled (@pxref{Minor
1406 Modes}), @ccmode{} inserts newlines for you automatically (in certain
1407 syntactic contexts) when you type a left or right brace, a colon, a
1408 semicolon, or a comma. Sometimes a newline appears before the
1409 character you type, sometimes after it, sometimes both.
1410
1411 Auto-newline only triggers when the following conditions hold:
1412
1413 @itemize @bullet
1414 @item
1415 Auto-newline minor mode is enabled, as evidenced by the indicator
1416 @samp{a} after the mode name on the modeline (e.g. @samp{C/a} or
1417 @samp{C/la}).
1418
1419 @item
1420 The character was typed at the end of a line, or with only whitespace
1421 after it, and possibly a @samp{\} escaping the newline.
1422
1423 @item
1424 The character is not on its own line already. (This applies only to
1425 insertion of a newline @emph{before} the character.)
1426
1427 @item
1428 @cindex literal
1429 @cindex syntactic whitespace
1430 The character was not typed inside of a literal @footnote{A
1431 @dfn{literal} is defined as any comment, string, or preprocessor macro
1432 definition. These constructs are also known as @dfn{syntactic
1433 whitespace} since they are usually ignored when scanning C code.}.
1434
1435 @item
1436 No numeric argument was supplied to the command (i.e. it was typed as
1437 normal, with no @kbd{C-u} prefix).
1438 @end itemize
1439
1440 You can configure the precise circumstances in which newlines get
1441 inserted (see @pxref{Custom Auto-newlines}). Typically, the style
1442 system (@pxref{Styles}) will have set this up for you, so you probably
1443 won't have to bother.
1444
1445 Sometimes @ccmode{} inserts an auto-newline where you don't want one,
1446 such as after a @samp{@}} when you're about to type a @samp{;}.
1447 Hungry deletion can help here (@pxref{Hungry WS Deletion}), or you can
1448 activate an appropriate @dfn{clean-up}, which will remove the excess
1449 whitespace after you've typed the @samp{;}. See @ref{Clean-ups} for a
1450 full description. See also @ref{Electric Keys} for a summary of
1451 clean-ups listed by key.
1452
1453
1454 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1455 @node Hungry WS Deletion, Subword Movement, Auto-newlines, Commands
1456 @comment node-name, next, previous, up
1457 @section Hungry Deletion of Whitespace
1458 @cindex hungry-deletion
1459 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1460
1461 If you want to delete an entire block of whitespace at point, you can
1462 use @dfn{hungry deletion}. This deletes all the contiguous whitespace
1463 either before point or after point in a single operation.
1464 ``Whitespace'' here includes tabs and newlines, but not comments or
1465 preprocessor commands. Hungry deletion can markedly cut down on the
1466 number of times you have to hit deletion keys when, for example,
1467 you've made a mistake on the preceding line and have already pressed
1468 @kbd{C-j}.
1469
1470 Hungry deletion is a simple feature that some people find extremely
1471 useful. In fact, you might find yourself wanting it in @strong{all}
1472 your editing modes!
1473
1474 Loosely speaking, in what follows, @dfn{@key{DEL}} means ``the
1475 backspace key'' and @dfn{@key{DELETE}} means ``the forward delete
1476 key''. This is discussed in more detail below.
1477
1478 There are two different ways you can use hungry deletion:
1479
1480 @table @asis
1481 @item Using @dfn{Hungry Delete Mode} with @kbd{@key{DEL}} and @kbd{C-d}
1482 Here you toggle Hungry Delete minor mode with @kbd{M-x
1483 c-toggle-hungry-state}@footnote{Prior to @ccmode{} 5.31, this command
1484 was bound to @kbd{C-c C-d}. @kbd{C-c C-d} is now the default binding
1485 for @code{c-hungry-delete-forward}.} (@pxref{Minor Modes}.) This
1486 makes @kbd{@key{DEL}} and @kbd{C-d} do backwards and forward hungry
1487 deletion.
1488
1489 @table @asis
1490 @item @kbd{@key{DEL}} (@code{c-electric-backspace})
1491 @kindex DEL
1492 @findex c-electric-backspace
1493 @findex electric-backspace (c-)
1494 This command is run by default when you hit the @kbd{DEL} key. When
1495 hungry delete mode is enabled, it deletes any amount of whitespace in
1496 the backwards direction. Otherwise, or when used with a prefix
1497 argument or in a literal (@pxref{Auto-newlines}), the command just
1498 deletes backwards in the usual way. (More precisely, it calls the
1499 function contained in the variable @code{c-backspace-function},
1500 passing it the prefix argument, if any.)
1501
1502 @item @code{c-backspace-function}
1503 @vindex c-backspace-function
1504 @vindex backspace-function (c-)
1505 @findex backward-delete-char-untabify
1506 Hook that gets called by @code{c-electric-backspace} when it doesn't
1507 do an ``electric'' deletion of the preceding whitespace. The default
1508 value is @code{backward-delete-char-untabify}
1509 (@pxref{Deletion,,,@lispref{}, @lispreftitle{}}, the function which
1510 deletes a single character.
1511
1512 @item @kbd{C-d} (@code{c-electric-delete-forward})
1513 @kindex C-d
1514 @findex c-electric-delete-forward
1515 @findex electric-delete-forward (c-)
1516 This function, which is bound to @kbd{C-d} by default, works just like
1517 @code{c-electric-backspace} but in the forward direction. When it
1518 doesn't do an ``electric'' deletion of the following whitespace, it
1519 just does @code{delete-char}, more or less. (Strictly speaking, it
1520 calls the function in @code{c-delete-function} with the prefix
1521 argument.)
1522
1523 @item @code{c-delete-function}
1524 @vindex c-delete-function
1525 @vindex delete-function (c-)
1526 @findex delete-char
1527 Hook that gets called by @code{c-electric-delete-forward} when it
1528 doesn't do an ``electric'' deletion of the following whitespace. The
1529 default value is @code{delete-char}.
1530 @end table
1531
1532 @item Using Distinct Bindings
1533 The other (newer and recommended) way to use hungry deletion is to
1534 perform @code{c-hungry-delete-backwards} and
1535 @code{c-hungry-delete-forward} directly through their key sequences
1536 rather than using the minor mode toggling.
1537
1538 @table @asis
1539 @item @kbd{C-c C-@key{DEL}}, or @kbd{C-c @key{DEL}} (@code{c-hungry-delete-backwards})@footnote{This command was formerly known as @code{c-hungry-backspace}.}
1540 @kindex C-c C-<backspace>
1541 @kindex C-c <backspace>
1542 @kindex C-c C-DEL
1543 @kindex C-c DEL
1544 @findex c-hungry-delete-backwards
1545 @findex hungry-delete-backwards (c-)
1546 Delete any amount of whitespace in the backwards direction (regardless
1547 whether hungry-delete mode is enabled or not). This command is bound
1548 to both @kbd{C-c C-@key{DEL}} and @kbd{C-c @key{DEL}}, since the more
1549 natural one, @kbd{C-c C-@key{DEL}}, is sometimes difficult to type at
1550 a character terminal.
1551
1552 @item @kbd{C-c C-d}, @kbd{C-c C-@key{DELETE}}, or @kbd{C-c @key{DELETE}} (@code{c-hungry-delete-forward})
1553 @kindex C-c C-d
1554 @kindex C-c C-<DELETE>
1555 @kindex C-c <DELETE>
1556 @findex c-hungry-delete-forward
1557 @findex hungry-delete-forward (c-)
1558 Delete any amount of whitespace in the forward direction (regardless
1559 whether hungry-delete mode is enabled or not). This command is bound
1560 to both @kbd{C-c C-@key{DELETE}} and @kbd{C-c @key{DELETE}} for the
1561 same reason as for @key{DEL} above.
1562 @end table
1563 @end table
1564
1565 @kindex <delete>
1566 @kindex <backspace>
1567
1568 When we talk about @kbd{@key{DEL}}, and @kbd{@key{DELETE}} above, we
1569 actually do so without connecting them to the physical keys commonly
1570 known as @key{Backspace} and @key{Delete}. The default bindings to
1571 those two keys depends on the flavor of (X)Emacs you are using.
1572
1573 @findex c-electric-delete
1574 @findex electric-delete (c-)
1575 @findex c-hungry-delete
1576 @findex hungry-delete (c-)
1577 @vindex delete-key-deletes-forward
1578 In XEmacs 20.3 and beyond, the @key{Backspace} key is bound to
1579 @code{c-electric-backspace} and the @key{Delete} key is bound to
1580 @code{c-electric-delete}. You control the direction it deletes in by
1581 setting the variable @code{delete-key-deletes-forward}, a standard
1582 XEmacs variable.
1583 @c This variable is encapsulated by XEmacs's (defsubst delete-forward-p ...).
1584 When this variable is non-@code{nil}, @code{c-electric-delete} will do
1585 forward deletion with @code{c-electric-delete-forward}, otherwise it
1586 does backward deletion with @code{c-electric-backspace}. Similarly,
1587 @kbd{C-c @key{Delete}} and @kbd{C-c C-@key{Delete}} are bound to
1588 @code{c-hungry-delete} which is controlled in the same way by
1589 @code{delete-key-deletes-forward}.
1590
1591 @findex normal-erase-is-backspace-mode
1592
1593 Emacs 21 and later automatically binds @key{Backspace} and
1594 @key{Delete} to @kbd{DEL} and @kbd{C-d} according to your environment,
1595 and @ccmode{} extends those bindings to @kbd{C-c C-@key{Backspace}}
1596 etc. If you need to change the bindings through
1597 @code{normal-erase-is-backspace-mode} then @ccmode{} will also adapt
1598 its extended bindings accordingly.
1599
1600 In earlier (X)Emacs versions, @ccmode{} doesn't bind either
1601 @key{Backspace} or @key{Delete} directly. Only the key codes
1602 @kbd{DEL} and @kbd{C-d} are bound, and it's up to the default bindings
1603 to map the physical keys to them. You might need to modify this
1604 yourself if the defaults are unsuitable.
1605
1606 Getting your @key{Backspace} and @key{Delete} keys properly set up can
1607 sometimes be tricky. The information in @ref{DEL Does Not
1608 Delete,,,emacs, GNU Emacs Manual}, might be helpful if you're having
1609 trouble with this in GNU Emacs.
1610
1611
1612 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1613 @node Subword Movement, Other Commands, Hungry WS Deletion, Commands
1614 @comment node-name, next, previous, up
1615 @section Subword Movement and Editing
1616 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1617
1618 @cindex nomenclature
1619 @cindex subword
1620 In spite of the GNU Coding Standards, it is popular to name a symbol
1621 by mixing uppercase and lowercase letters, e.g. @samp{GtkWidget},
1622 @samp{EmacsFrameClass}, or @samp{NSGraphicsContext}. Here we call
1623 these mixed case symbols @dfn{nomenclatures}. Also, each capitalized
1624 (or completely uppercase) part of a nomenclature is called a
1625 @dfn{subword}. Here are some examples:
1626
1627 @multitable {@samp{NSGraphicsContext}} {@samp{NS}, @samp{Graphics}, and @samp{Context}}
1628 @c This could be converted to @headitem when we require Texinfo 4.7
1629 @iftex
1630 @item @b{Nomenclature}
1631 @tab @b{Subwords}
1632 @end iftex
1633 @ifnottex
1634 @item Nomenclature
1635 @tab Subwords
1636 @item ---------------------------------------------------------
1637 @end ifnottex
1638 @item @samp{GtkWindow}
1639 @tab @samp{Gtk} and @samp{Window}
1640 @item @samp{EmacsFrameClass}
1641 @tab @samp{Emacs}, @samp{Frame}, and @samp{Class}
1642 @item @samp{NSGraphicsContext}
1643 @tab @samp{NS}, @samp{Graphics}, and @samp{Context}
1644 @end multitable
1645
1646 The subword minor mode replaces the basic word oriented movement and
1647 editing commands with variants that recognize subwords in a
1648 nomenclature and treat them as separate words:
1649
1650 @findex c-forward-subword
1651 @findex forward-subword (c-)
1652 @findex c-backward-subword
1653 @findex backward-subword (c-)
1654 @findex c-mark-subword
1655 @findex mark-subword (c-)
1656 @findex c-kill-subword
1657 @findex kill-subword (c-)
1658 @findex c-backward-kill-subword
1659 @findex backward-kill-subword (c-)
1660 @findex c-transpose-subwords
1661 @findex transpose-subwords (c-)
1662 @findex c-capitalize-subword
1663 @findex capitalize-subword (c-)
1664 @findex c-upcase-subword
1665 @findex upcase-subword (c-)
1666 @findex c-downcase-subword
1667 @findex downcase-subword (c-)
1668 @multitable @columnfractions .20 .40 .40
1669 @c This could be converted to @headitem when we require Texinfo 4.7
1670 @iftex
1671 @item @b{Key} @tab @b{Word oriented command} @tab @b{Subword oriented command}
1672 @end iftex
1673 @ifnottex
1674 @item Key @tab Word oriented command @tab Subword oriented command
1675 @item ----------------------------------------------------------------------------
1676 @end ifnottex
1677 @item @kbd{M-f} @tab @code{forward-word} @tab @code{c-forward-subword}
1678 @item @kbd{M-b} @tab @code{backward-word} @tab @code{c-backward-subword}
1679 @item @kbd{M-@@} @tab @code{mark-word} @tab @code{c-mark-subword}
1680 @item @kbd{M-d} @tab @code{kill-word} @tab @code{c-kill-subword}
1681 @item @kbd{M-DEL} @tab @code{backward-kill-word} @tab @code{c-backward-kill-subword}
1682 @item @kbd{M-t} @tab @code{transpose-words} @tab @code{c-transpose-subwords}
1683 @item @kbd{M-c} @tab @code{capitalize-word} @tab @code{c-capitalize-subword}
1684 @item @kbd{M-u} @tab @code{upcase-word} @tab @code{c-upcase-subword}
1685 @item @kbd{M-l} @tab @code{downcase-word} @tab @code{c-downcase-subword}
1686 @end multitable
1687
1688 Note that if you have changed the key bindings for the word oriented
1689 commands in your @file{.emacs} or a similar place, the keys you have
1690 configured are also used for the corresponding subword oriented
1691 commands.
1692
1693 Type @kbd{C-c C-w} to toggle subword mode on and off. To make the
1694 mode turn on automatically, put the following code in your
1695 @file{.emacs}:
1696
1697 @example
1698 (add-hook 'c-mode-common-hook
1699 (lambda () (c-subword-mode 1)))
1700 @end example
1701
1702 As a bonus, you can also use @code{c-subword-mode} in non-@ccmode{}
1703 buffers by typing @kbd{M-x c-subword-mode}.
1704
1705 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1706 @node Other Commands, , Subword Movement, Commands
1707 @comment node-name, next, previous, up
1708 @section Other Commands
1709 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1710
1711 Here are the various other commands that didn't fit anywhere else:
1712
1713 @table @asis
1714 @item @kbd{C-c .} (@code{c-set-style})
1715 @kindex C-c .
1716 @findex c-set-style
1717 @findex set-style (c-)
1718 Switch to the specified style in the current buffer. Use like this:
1719
1720 @example
1721 @kbd{C-c . @var{style-name} @key{RET}}
1722 @end example
1723
1724 You can use the @key{TAB} in the normal way to do completion on the
1725 style name. Note that all style names are case insensitive, even the
1726 ones you define yourself.
1727
1728 Setting a style in this way does @emph{not} automatically reindent your
1729 file. For commands that you can use to view the effect of your changes,
1730 see @ref{Indentation Commands} and @ref{Filling and Breaking}.
1731
1732 For details of the @ccmode{} style system, see @ref{Styles}.
1733 @item @kbd{C-c :} (@code{c-scope-operator})
1734 @kindex C-c :
1735 @findex c-scope-operator
1736 @findex scope-operator (c-)
1737 In C++, it is also sometimes desirable to insert the double-colon scope
1738 operator without performing the electric behavior of colon insertion.
1739 @kbd{C-c :} does just this.
1740
1741 @item @kbd{C-c C-\} (@code{c-backslash-region})
1742 @kindex C-c C-\
1743 @findex c-backslash-region
1744 @findex backslash-region (c-)
1745 This function inserts and aligns or deletes end-of-line backslashes in
1746 the current region. These are typically used in multi-line macros.
1747
1748 With no prefix argument, it inserts any missing backslashes and aligns
1749 them according to the @code{c-backslash-column} and
1750 @code{c-backslash-max-column} variables. With a prefix argument, it
1751 deletes any backslashes.
1752
1753 The function does not modify blank lines at the start of the region. If
1754 the region ends at the start of a line, it always deletes the backslash
1755 (if any) at the end of the previous line.
1756
1757 To customize the precise workings of this command, @ref{Custom Macros}.
1758 @end table
1759
1760 @noindent
1761 The recommended line breaking function, @code{c-context-line-break}
1762 (@pxref{Filling and Breaking}), is especially nice if you edit
1763 multiline macros frequently. When used inside a macro, it
1764 automatically inserts and adjusts the mandatory backslash at the end
1765 of the line to keep the macro together, and it leaves the point at the
1766 right indentation column for the code. Thus you can write code inside
1767 macros almost exactly as you can elsewhere, without having to bother
1768 with the trailing backslashes.
1769
1770 @table @asis
1771 @item @kbd{C-c C-e} (@code{c-macro-expand})
1772 @kindex C-c C-e
1773 @findex c-macro-expand
1774 @findex macro-expand (c-)
1775 This command expands C, C++, Objective C or Pike macros in the region,
1776 using an appropriate external preprocessor program. Normally it
1777 displays its output in a temporary buffer, but if you give it a prefix
1778 arg (with @kbd{C-u C-c C-e}) it will overwrite the original region
1779 with the expansion.
1780
1781 The command does not work in any of the other modes, and the key
1782 sequence is not bound in these other modes.
1783
1784 @code{c-macro-expand} isn't actually part of @ccmode{}, even though it
1785 is bound to a @ccmode{} key sequence. If you need help setting it up
1786 or have other problems with it, you can either read its source code or
1787 ask for help in the standard (X)Emacs forums.
1788 @end table
1789
1790 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1791 @node Font Locking, Config Basics, Commands, Top
1792 @comment node-name, next, previous, up
1793 @chapter Font Locking
1794 @cindex font locking
1795 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1796
1797 @cindex Font Lock mode
1798
1799 @ccmode{} provides font locking for its supported languages by
1800 supplying patterns for use with Font Lock mode. This means that you
1801 get distinct faces on the various syntactic parts such as comments,
1802 strings, keywords and types, which is very helpful in telling them
1803 apart at a glance and discovering syntactic errors. @xref{Font
1804 Lock,,, emacs, GNU Emacs Manual}, for ways to enable font locking in
1805 @ccmode{} buffers.
1806
1807 @strong{Please note:} The font locking in AWK mode is currently not
1808 integrated with the rest of @ccmode{}. Only the last section of this
1809 chapter, @ref{AWK Mode Font Locking}, applies to AWK. The other
1810 sections apply to the other languages.
1811
1812 @menu
1813 * Font Locking Preliminaries::
1814 * Faces::
1815 * Doc Comments::
1816 * AWK Mode Font Locking::
1817 @end menu
1818
1819
1820 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1821 @node Font Locking Preliminaries, Faces, Font Locking, Font Locking
1822 @comment node-name, next, previous, up
1823 @section Font Locking Preliminaries
1824 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1825
1826 The font locking for most of the @ccmode{} languages were provided
1827 directly by the Font Lock package prior to version 5.30 of @ccmode{}.
1828 In the transition to @ccmode{} the patterns have been reworked
1829 completely and are applied uniformly across all the languages except AWK
1830 mode, just like the indentation rules (although each language still has
1831 some peculiarities of its own, of course). Since the languages
1832 previously had completely separate font locking patterns, this means
1833 that it's a bit different in most languages now.
1834
1835 The main goal for the font locking in @ccmode{} is accuracy, to provide
1836 a dependable aid in recognizing the various constructs. Some, like
1837 strings and comments, are easy to recognize while others, like
1838 declarations and types, can be very tricky. @ccmode{} can go to great
1839 lengths to recognize declarations and casts correctly, especially when
1840 the types aren't recognized by standard patterns. This is a fairly
1841 demanding analysis which can be slow on older hardware, and it can
1842 therefore be disabled by choosing a lower decoration level with the
1843 variable @code{font-lock-maximum-decoration} (@pxref{Font Lock,,,
1844 emacs, GNU Emacs Manual}).
1845
1846 @vindex font-lock-maximum-decoration
1847
1848 The decoration levels are used as follows:
1849
1850 @enumerate
1851 @comment 1
1852 @item
1853 Minimal font locking: Fontify only comments, strings and preprocessor
1854 directives (in the languages that use cpp).
1855
1856 @comment 2
1857 @item
1858 Fast font locking: In addition to level 1, fontify keywords, simple
1859 types and declarations that are easy to recognize. The variables
1860 @code{*-font-lock-extra-types} (where @samp{*} is the name of the
1861 language) are used to recognize types (see below). Documentation
1862 comments like Javadoc are fontified according to
1863 @code{c-doc-comment-style} (@pxref{Doc Comments}).
1864
1865 Use this if you think the font locking is too slow. It's the closest
1866 corresponding level to level 3 in the old font lock patterns.
1867
1868 @comment 3
1869 @item
1870 Accurate font locking: Like level 2 but uses a different approach that
1871 can recognize types and declarations much more accurately. The
1872 @code{*-font-lock-extra-types} variables are still used, but user
1873 defined types are recognized correctly anyway in most cases. Therefore
1874 those variables should be fairly restrictive and not contain patterns
1875 that are uncertain.
1876
1877 @cindex Lazy Lock mode
1878 @cindex Just-in-time Lock mode
1879
1880 This level is designed for fairly modern hardware and a font lock
1881 support mode like Lazy Lock or Just-in-time Lock mode that only
1882 fontifies the parts that are actually shown. Fontifying the whole
1883 buffer at once can easily get bothersomely slow even on contemporary
1884 hardware. @xref{Font Lock,,,@emacsman{}, @emacsmantitle{}}.
1885 @end enumerate
1886
1887 @cindex user defined types
1888 @cindex types, user defined
1889
1890 Since user defined types are hard to recognize you can provide
1891 additional regexps to match those you use:
1892
1893 @defopt c-font-lock-extra-types
1894 @defoptx c++-font-lock-extra-types
1895 @defoptx objc-font-lock-extra-types
1896 @defoptx java-font-lock-extra-types
1897 @defoptx idl-font-lock-extra-types
1898 @defoptx pike-font-lock-extra-types
1899 For each language there's a variable @code{*-font-lock-extra-types},
1900 where @samp{*} stands for the language in question. It contains a list
1901 of regexps that matches identifiers that should be recognized as types,
1902 e.g. @samp{\\sw+_t} to recognize all identifiers ending with @samp{_t}
1903 as is customary in C code. Each regexp should not match more than a
1904 single identifier.
1905
1906 The default values contain regexps for many types in standard runtime
1907 libraries that are otherwise difficult to recognize, and patterns for
1908 standard type naming conventions like the @samp{_t} suffix in C and C++.
1909 Java, Objective-C and Pike have as a convention to start class names
1910 with capitals, so there are patterns for that in those languages.
1911
1912 Despite the names of these variables, they are not only used for
1913 fontification but in other places as well where @ccmode{} needs to
1914 recognize types.
1915 @end defopt
1916
1917
1918 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1919 @node Faces, Doc Comments, Font Locking Preliminaries, Font Locking
1920 @comment node-name, next, previous, up
1921 @section Faces
1922 @cindex faces
1923 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1924
1925 @ccmode{} attempts to use the standard faces for programming languages
1926 in accordance with their intended purposes as far as possible. No extra
1927 faces are currently provided, with the exception of a replacement face
1928 @code{c-invalid-face} for emacsen that don't provide
1929 @code{font-lock-warning-face}.
1930
1931 @itemize @bullet
1932 @item
1933 @vindex font-lock-comment-face
1934 Normal comments are fontified in @code{font-lock-comment-face}.
1935
1936 @item
1937 @vindex font-lock-doc-face
1938 @vindex font-lock-doc-string-face
1939 @vindex font-lock-comment-face
1940 Comments that are recognized as documentation (@pxref{Doc Comments})
1941 get @code{font-lock-doc-face} (Emacs) or
1942 @code{font-lock-doc-string-face} (XEmacs) if those faces exist. If
1943 they don't then @code{font-lock-comment-face} is used.
1944
1945 @item
1946 @vindex font-lock-string-face
1947 String and character literals are fontified in
1948 @code{font-lock-string-face}.
1949
1950 @item
1951 @vindex font-lock-keyword-face
1952 Keywords are fontified with @code{font-lock-keyword-face}.
1953
1954 @item
1955 @vindex font-lock-function-name-face
1956 @code{font-lock-function-name-face} is used for function names in
1957 declarations and definitions, and classes in those contexts. It's also
1958 used for preprocessor defines with arguments.
1959
1960 @item
1961 @vindex font-lock-variable-name-face
1962 Variables in declarations and definitions, and other identifiers in such
1963 variable contexts, get @code{font-lock-variable-name-face}. It's also
1964 used for preprocessor defines without arguments.
1965
1966 @item
1967 @vindex font-lock-constant-face
1968 @vindex font-lock-reference-face
1969 Builtin constants are fontified in @code{font-lock-constant-face} if it
1970 exists, @code{font-lock-reference-face} otherwise. As opposed to the
1971 preceding two faces, this is used on the names in expressions, and it's
1972 not used in declarations, even if there happen to be a @samp{const} in
1973 them somewhere.
1974
1975 @item
1976 @vindex font-lock-type-face
1977 @code{font-lock-type-face} is put on types (both predefined and user
1978 defined) and classes in type contexts.
1979
1980 @item
1981 @vindex font-lock-constant-face
1982 @vindex font-lock-reference-face
1983 Label identifiers get @code{font-lock-constant-face} if it exists,
1984 @code{font-lock-reference-face} otherwise.
1985
1986 @item
1987 Name qualifiers and identifiers for scope constructs are fontified like
1988 labels.
1989
1990 @item
1991 Special markup inside documentation comments are also fontified like
1992 labels.
1993
1994 @item
1995 @vindex font-lock-preprocessor-face
1996 @vindex font-lock-builtin-face
1997 @vindex font-lock-reference-face
1998 Preprocessor directives get @code{font-lock-preprocessor-face} if it
1999 exists (i.e. XEmacs). In Emacs they get @code{font-lock-builtin-face}
2000 or @code{font-lock-reference-face}, for lack of a closer equivalent.
2001
2002 @item
2003 @vindex font-lock-warning-face
2004 @vindex c-invalid-face
2005 @vindex invalid-face (c-)
2006 Some kinds of syntactic errors are fontified with
2007 @code{font-lock-warning-face} in Emacs. In older XEmacs versions
2008 there's no corresponding standard face, so there a special
2009 @code{c-invalid-face} is used, which is defined to stand out sharply by
2010 default.
2011
2012 Note that it's not used for @samp{#error} or @samp{#warning} directives,
2013 since those aren't syntactic errors in themselves.
2014 @end itemize
2015
2016
2017 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2018 @node Doc Comments, AWK Mode Font Locking, Faces, Font Locking
2019 @comment node-name, next, previous, up
2020 @section Documentation Comments
2021 @cindex documentation comments
2022 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2023
2024 There are various tools to supply documentation in the source as
2025 specially structured comments, e.g. the standard Javadoc tool in Java.
2026 @ccmode{} provides an extensible mechanism to fontify such comments and
2027 the special markup inside them.
2028
2029 @defopt c-doc-comment-style
2030 @vindex doc-comment-style (c-)
2031 This is a style variable that specifies which documentation comment
2032 style to recognize, e.g. @code{javadoc} for Javadoc comments.
2033
2034 The value may also be a list of styles, in which case all of them are
2035 recognized simultaneously (presumably with markup cues that don't
2036 conflict).
2037
2038 The value may also be an association list to specify different comment
2039 styles for different languages. The symbol for the major mode is then
2040 looked up in the alist, and the value of that element is interpreted as
2041 above if found. If it isn't found then the symbol `other' is looked up
2042 and its value is used instead.
2043
2044 The default value for @code{c-doc-comment-style} is
2045 @w{@code{((java-mode . javadoc) (pike-mode . autodoc) (c-mode . gtkdoc))}}.
2046
2047 Note that @ccmode{} uses this variable to set other variables that
2048 handle fontification etc. That's done at mode initialization or when
2049 you switch to a style which sets this variable. Thus, if you change it
2050 in some other way, e.g. interactively in a CC Mode buffer, you will need
2051 to do @kbd{M-x java-mode} (or whatever mode you're currently using) to
2052 reinitialize.
2053
2054 @findex c-setup-doc-comment-style
2055 @findex setup-doc-comment-style (c-)
2056 Note also that when @ccmode{} starts up, the other variables are
2057 modified before the mode hooks are run. If you change this variable in
2058 a mode hook, you'll have to call @code{c-setup-doc-comment-style}
2059 afterwards to redo that work.
2060 @end defopt
2061
2062 @ccmode{} currently provides handing of the following doc comment
2063 styles:
2064
2065 @table @code
2066 @item javadoc
2067 @cindex Javadoc markup
2068 Javadoc comments, the standard tool in Java.
2069
2070 @item autodoc
2071 @cindex Pike autodoc markup
2072 For Pike autodoc markup, the standard in Pike.
2073
2074 @item gtkdoc
2075 @cindex GtkDoc markup
2076 For GtkDoc markup, widely used in the Gnome community.
2077 @end table
2078
2079 The above is by no means complete. If you'd like to see support for
2080 other doc comment styles, please let us know (@pxref{Mailing Lists and
2081 Bug Reports}).
2082
2083 You can also write your own doc comment fontification support to use
2084 with @code{c-doc-comment-style}: Supply a variable or function
2085 @code{*-font-lock-keywords} where @samp{*} is the name you want to use
2086 in @code{c-doc-comment-style}. If it's a variable, it's prepended to
2087 @code{font-lock-keywords}. If it's a function, it's called at mode
2088 initialization and the result is prepended. For an example, see
2089 @code{javadoc-font-lock-keywords} in @file{cc-fonts.el}.
2090
2091 If you add support for another doc comment style, please consider
2092 contributing it - send a note to @email{bug-cc-mode@@gnu.org}.
2093
2094
2095 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2096 @node AWK Mode Font Locking, , Doc Comments, Font Locking
2097 @comment node-name, next, previous, up
2098 @section AWK Mode Font Locking
2099 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2100
2101 The general appearance of font-locking in AWK mode is much like in any
2102 other programming mode. @xref{Faces For Font Lock,,,elisp, GNU Emacs
2103 Lisp Reference Manual}.
2104
2105 The following faces are, however, used in a non-standard fashion in
2106 AWK mode:
2107
2108 @table @asis
2109 @item @code{font-lock-variable-name-face}
2110 This face was intended for variable declarations. Since variables are
2111 not declared in AWK, this face is used instead for AWK system
2112 variables (such as @code{NF}) and ``Special File Names'' (such as
2113 @code{"/dev/stderr"}).
2114
2115 @item @code{font-lock-builtin-face} (Emacs)/@code{font-lock-preprocessor-face} (XEmacs)
2116 This face is normally used for preprocessor directives in @ccmode{}.
2117 There are no such things in AWK, so this face is used instead for
2118 standard functions (such as @code{match}).
2119
2120 @item @code{font-lock-string-face}
2121 As well as being used for strings, including localizable strings,
2122 (delimited by @samp{"} and @samp{_"}), this face is also used for AWK
2123 regular expressions (delimited by @samp{/}).
2124
2125 @item @code{font-lock-warning-face} (Emacs)/@code{c-invalid-face} (XEmacs)
2126 This face highlights the following syntactically invalid AWK
2127 constructs:
2128
2129 @itemize @bullet
2130 @item
2131 An unterminated string or regular expression. Here the opening
2132 delimiter (@samp{"} or @samp{/} or @samp{_"}) is displayed in
2133 @code{font-lock-warning-face}. This is most noticeable when typing in a
2134 new string/regular expression into a buffer, when the warning-face
2135 serves as a continual reminder to terminate the construct.
2136
2137 AWK mode fontifies unterminated strings/regular expressions
2138 differently from other modes: Only the text up to the end of the line
2139 is fontified as a string (escaped newlines being handled correctly),
2140 rather than the text up to the next string quote.
2141
2142 @item
2143 A space between the function name and opening parenthesis when calling
2144 a user function. The last character of the function name and the
2145 opening parenthesis are highlighted. This font-locking rule will
2146 spuriously highlight a valid concatenation expression where an
2147 identifier precedes a parenthesised expression. Unfortunately.
2148
2149 @item
2150 Whitespace following the @samp{\} in what otherwise looks like an
2151 escaped newline. The @samp{\} is highlighted.
2152 @end itemize
2153 @end table
2154
2155
2156 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2157 @node Config Basics, Custom Filling and Breaking, Font Locking, Top
2158 @comment node-name, next, previous, up
2159 @chapter Configuration Basics
2160 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2161
2162 @cindex Emacs Initialization File
2163 @cindex Configuration
2164 You configure @ccmode{} by setting Lisp variables and calling (and
2165 perhaps writing) Lisp functions@footnote{DON'T PANIC!!! This isn't
2166 difficult.}, which is usually done by adding code to an Emacs
2167 initialization file. This file might be @file{site-start.el} or
2168 @file{.emacs} or @file{init.el} or @file{default.el} or perhaps some
2169 other file. @xref{Init File,,,@emacsman{}, @emacsmantitle{}}. For
2170 the sake of conciseness, we just call this file ``your @file{.emacs}''
2171 throughout the rest of the manual.
2172
2173 Several of these variables (currently 16), are known collectively as
2174 @dfn{style variables}. @ccmode{} provides a special mechanism, known
2175 as @dfn{styles} to make it easier to set these variables as a group,
2176 to ``inherit'' settings from one style into another, and so on. Style
2177 variables remain ordinary Lisp variables, whose values can be read and
2178 changed independently of the style system. @xref{Style Variables}.
2179
2180 There are several ways you can write the code, depending on the
2181 precise effect you want---they are described further down on this page.
2182 If you are new to @ccmode{}, we suggest you begin with the simplest
2183 method, ``Top-level commands or the customization interface''.
2184
2185 If you make conflicting settings in several of these ways, the way
2186 that takes precedence is the one that appears latest in this list:
2187 @itemize @asis
2188 @item
2189 @table @asis
2190 @item Style
2191 @itemx Top-level command or ``customization interface''
2192 @itemx Hook
2193 @itemx File Style
2194 @end table
2195 @end itemize
2196
2197 Here is a summary of the different ways of writing your configuration
2198 settings:
2199
2200 @table @asis
2201 @item Top-level commands or the ``customization interface''
2202 Most simply, you can write @code{setq} and similar commands at the top
2203 level of your @file{.emacs} file. When you load a @ccmode{} buffer,
2204 it initializes its configuration from these global values (at least,
2205 for those settings you have given values to), so it makes sense to
2206 have these @code{setq} commands run @emph{before} @ccmode{} is first
2207 initialized---in particular, before any call to @code{desktop-read}
2208 (@pxref{Saving Emacs Sessions,,, emacs, GNU Emacs Manual}). For
2209 example, you might set c-basic-offset thus:
2210
2211 @example
2212 (setq c-basic-offset 4)
2213 @end example
2214
2215 You can use the more user friendly Customization interface instead,
2216 but this manual does not cover in detail how that works. To do this,
2217 start by typing @kbd{M-x customize-group @key{RET} c @key{RET}}.
2218 @xref{Easy Customization,,,@emacsman{}, @emacsmantitle{}}.
2219 @c The following note really belongs in the Emacs manual.
2220 Emacs normally writes the customizations at the end of your
2221 @file{.emacs} file. If you use @code{desktop-read}, you should edit
2222 your @file{.emacs} to place the call to @code{desktop-read} @emph{after}
2223 the customizations.
2224
2225 The first initialization of @ccmode{} puts a snapshot of the
2226 configuration settings into the special style @code{user}.
2227 @xref{Built-in Styles}.
2228
2229 For basic use of Emacs, either of these ways of configuring is
2230 adequate. However, the settings are then the same in all @ccmode{}
2231 buffers and it can be clumsy to communicate them between programmers.
2232 For more flexibility, you'll want to use one (or both) of @ccmode{}'s
2233 more sophisticated facilities, hooks and styles.
2234
2235 @item Hooks
2236 An Emacs @dfn{hook} is a place to put Lisp functions that you want
2237 Emacs to execute later in specific circumstances.
2238 @xref{Hooks,,,@lispref{}, @lispreftitle{}}. @ccmode{} supplies a main
2239 hook and a language-specific hook for each language it supports - any
2240 functions you put onto these hooks get executed as the last part of a
2241 buffer's initialization. Typically you put most of your customization
2242 within the main hook, and use the language-specific hooks to vary the
2243 customization settings between language modes. For example, if you
2244 wanted different (non-standard) values of @code{c-basic-offset} in C
2245 Mode and Java Mode buffers, you could do it like this:
2246
2247 @example
2248 @group
2249 (defun my-c-mode-hook ()
2250 (setq c-basic-offset 3))
2251 (add-hook 'c-mode-hook 'my-c-mode-hook)
2252
2253 (defun my-java-mode-hook ()
2254 (setq c-basic-offset 6))
2255 (add-hook 'java-mode-hook 'my-java-mode-hook)
2256 @end group
2257 @end example
2258
2259 See @ref{CC Hooks} for more details on the use of @ccmode{} hooks.
2260
2261 @item Styles
2262 A @ccmode{} @dfn{style} is a coherent collection of customizations
2263 with a name. At any time, exactly one style is active in each
2264 @ccmode{} buffer, either the one you have selected or a default.
2265 @ccmode{} is delivered with several existing styles. Additionally,
2266 you can create your own styles, possibly based on these existing
2267 styles. If you worked in a programming team called the ``Free
2268 Group'', which had its own coding standards, you might well have this
2269 in your @file{.emacs} file:
2270
2271 @example
2272 (setq c-default-style '((java-mode . "java")
2273 (awk-mode . "awk")
2274 (other . "free-group-style")))
2275 @end example
2276
2277 See @ref{Styles} for fuller details on using @ccmode{} styles and how
2278 to create them.
2279
2280 @item File Styles
2281 A @dfn{file style} is a rarely used variant of the ``style'' mechanism
2282 described above, which applies to an individual source file. To use
2283 it, you set certain Emacs local variables in a special block at the
2284 end of the source file. @xref{File Styles}.
2285
2286 @item Hooks with Styles
2287 For ultimate flexibility, you can use hooks and styles together. For
2288 example, if your team were developing a product which required a
2289 Linux driver, you'd probably want to use the ``linux'' style for the
2290 driver, and your own team's style for the rest of the code. You
2291 could achieve this with code like this in your @file{.emacs}:
2292
2293 @example
2294 @group
2295 (defun my-c-mode-hook ()
2296 (c-set-style
2297 (if (and (buffer-file-name)
2298 (string-match "/usr/src/linux" (buffer-file-name)))
2299 "linux"
2300 "free-group-style")))
2301 (add-hook 'c-mode-hook 'my-c-mode-hook)
2302 @end group
2303 @end example
2304
2305 In a programming team, a hook is a also a good place for each member
2306 to put his own personal preferences. For example, you might be the
2307 only person in your team who likes Auto-newline minor mode. You could
2308 have it enabled by default by placing the following in your
2309 @file{.emacs}:
2310
2311 @example
2312 @group
2313 (defun my-turn-on-auto-newline ()
2314 (c-toggle-auto-newline 1))
2315 (add-hook 'c-mode-common-hook 'my-turn-on-auto-newline)
2316 @end group
2317 @end example
2318 @end table
2319
2320 @menu
2321 * CC Hooks::
2322 * Style Variables::
2323 * Styles::
2324 @end menu
2325
2326 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2327 @node CC Hooks, Style Variables, Config Basics, Config Basics
2328 @comment node-name, next, previous, up
2329 @section Hooks
2330 @cindex mode hooks
2331 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2332 @c The node name is "CC Hooks" rather than "Hooks" because of a bug in
2333 @c some older versions of Info, e.g. the info.el in GNU Emacs 21.3.
2334 @c If you go to "Config Basics" and hit <CR> on the xref to "CC
2335 @c Hooks" the function Info-follow-reference searches for "*Note: CC
2336 @c Hooks" from the beginning of the page. If this node were instead
2337 @c named "Hooks", that search would spuriously find "*Note:
2338 @c Hooks(elisp)" and go to the wrong node.
2339
2340 @ccmode{} provides several hooks that you can use to customize the
2341 mode for your coding style. The main hook is
2342 @code{c-mode-common-hook}; typically, you'll put the bulk of your
2343 customizations here. In addition, each language mode has its own
2344 hook, allowing you to fine tune your settings individually for the
2345 different @ccmode{} languages, and there is a package initialization
2346 hook. Finally, there is @code{c-special-indent-hook}, which enables
2347 you to solve anomalous indentation problems. It is described in
2348 @ref{Other Indentation}, not here. All these hooks adhere to the
2349 standard Emacs conventions.
2350
2351 When you open a buffer, @ccmode{} first initializes it with the
2352 currently active style (@pxref{Styles}). Then it calls
2353 @code{c-mode-common-hook}, and finally it calls the language-specific
2354 hook. Thus, any style settings done in these hooks will override
2355 those set by @code{c-default-style}.
2356
2357 @defvar c-initialization-hook
2358 @vindex initialization-hook (c-)
2359 Hook run only once per Emacs session, when @ccmode{} is initialized.
2360 This is a good place to change key bindings (or add new ones) in any
2361 of the @ccmode{} key maps. @xref{Sample .emacs File}.
2362 @end defvar
2363
2364 @defvar c-mode-common-hook
2365 @vindex mode-common-hook (c-)
2366 Common hook across all languages. It's run immediately before the
2367 language specific hook.
2368 @end defvar
2369
2370 @defvar c-mode-hook
2371 @defvarx c++-mode-hook
2372 @defvarx objc-mode-hook
2373 @defvarx java-mode-hook
2374 @defvarx idl-mode-hook
2375 @defvarx pike-mode-hook
2376 @defvarx awk-mode-hook
2377 The language specific mode hooks. The appropriate one is run as the
2378 last thing when you enter that language mode.
2379 @end defvar
2380
2381 Although these hooks are variables defined in @ccmode{}, you can give
2382 them values before @ccmode{}'s code is loaded---indeed, this is the
2383 only way to use @code{c-initialization-hook}. Their values aren't
2384 overwritten when @ccmode{} gets loaded.
2385
2386 Here's a simplified example of what you can add to your @file{.emacs}
2387 file to do things whenever any @ccmode{} language is edited. See the
2388 Emacs manuals for more information on customizing Emacs via hooks.
2389 @xref{Sample .emacs File}, for a more complete sample @file{.emacs}
2390 file.
2391
2392 @example
2393 (defun my-c-mode-common-hook ()
2394 ;; my customizations for all of c-mode and related modes
2395 (no-case-fold-search)
2396 )
2397 (add-hook 'c-mode-common-hook 'my-c-mode-common-hook)
2398 @end example
2399
2400 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2401 @node Style Variables, Styles, CC Hooks, Config Basics
2402 @comment node-name, next, previous, up
2403 @section Style Variables
2404 @cindex styles
2405 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2406
2407 @cindex style variables
2408 The variables that @ccmode{}'s style system control are called
2409 @dfn{style variables}. Note that style variables are ordinary Lisp
2410 variables, which the style system initializes; you can change their
2411 values at any time (e.g. in a hook function). The style system can
2412 also set other variables, to some extent. @xref{Styles}.
2413
2414 @dfn{Style variables} are handled specially in several ways:
2415
2416 @itemize @bullet
2417 @item
2418 Style variables are by default buffer-local variables. However, they
2419 can instead be made global by setting
2420 @code{c-style-variables-are-local-p} to @code{nil} before @ccmode{} is
2421 initialized.
2422
2423 @item
2424 @vindex c-old-style-variable-behavior
2425 @vindex old-style-variable-behavior (c-)
2426 The default global binding of any style variable (with two exceptions
2427 - see below) is the special symbol @code{set-from-style}. When the
2428 style system initializes a buffer-local copy of a style variable for a
2429 @ccmode{} buffer, if its global binding is still that symbol then it
2430 will be set from the current style. Otherwise it will retain its
2431 global default@footnote{This is a big change from versions of
2432 @ccmode{} earlier than 5.26, where such settings would get overridden
2433 by the style system unless special precautions were taken. That was
2434 changed since it was counterintuitive and confusing, especially to
2435 novice users. If your configuration depends on the old overriding
2436 behavior, you can set the variable
2437 @code{c-old-style-variable-behavior} to non-@code{nil}.}. This
2438 ``otherwise'' happens, for example, when you've set the variable with
2439 @code{setq} at the top level of your @file{.emacs} (@pxref{Config
2440 Basics}).
2441
2442 @item
2443 The style variable @code{c-offsets-alist} (@pxref{c-offsets-alist}) is
2444 an association list with an element for each syntactic symbol. It's
2445 handled a little differently from the other style variables. It's
2446 default global binding is the empty list @code{nil}, rather than
2447 @code{set-from-style}. Before the style system is initialized, you
2448 can add individual elements to @code{c-offsets-alist} by calling
2449 @code{c-set-offset}(@pxref{c-offsets-alist}) just like you would set
2450 other style variables with @code{setq}. Those elements will then
2451 prevail when the style system later initializes a buffer-local copy of
2452 @code{c-offsets-alist}.
2453
2454 @item
2455 The style variable @code{c-special-indent-hook} is also handled in a
2456 special way. Styles can only add functions to this hook, not remove
2457 them, so any global settings you put on it are always
2458 preserved@footnote{This did not change in version 5.26.}. The value
2459 you give this variable in a style definition can be either a function
2460 or a list of functions.
2461
2462 @item
2463 The global bindings of the style variables get captured in the special
2464 @code{user} style when the style system is first initialized.
2465 @xref{Built-in Styles}, for details.
2466 @end itemize
2467
2468 The style variables are:@*
2469 @code{c-indent-comment-alist},
2470 @code{c-indent-comments-syntactically-p} (@pxref{Indentation
2471 Commands});@*
2472 @code{c-doc-comment-style} (@pxref{Doc Comments});@*
2473 @code{c-block-comment-prefix}, @code{c-comment-prefix-regexp}
2474 (@pxref{Custom Filling and Breaking});@*
2475 @code{c-hanging-braces-alist} (@pxref{Hanging Braces});@*
2476 @code{c-hanging-colons-alist} (@pxref{Hanging Colons});@*
2477 @code{c-hanging-semi&comma-criteria} (@pxref{Hanging Semicolons and
2478 Commas});@*
2479 @code{c-cleanup-list} (@pxref{Clean-ups});@*
2480 @code{c-basic-offset} (@pxref{Customizing Indentation});@*
2481 @code{c-offsets-alist} (@pxref{c-offsets-alist});@*
2482 @code{c-comment-only-line-offset} (@pxref{Comment Line-Up});@*
2483 @code{c-special-indent-hook}, @code{c-label-minimum-indentation}
2484 (@pxref{Other Indentation});@*
2485 @code{c-backslash-column}, @code{c-backslash-max-column}
2486 (@pxref{Custom Macros}).
2487
2488 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2489 @node Styles, , Style Variables, Config Basics
2490 @comment node-name, next, previous, up
2491 @section Styles
2492 @cindex styles
2493 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2494
2495 By @dfn{style} we mean the layout of the code---things like how many
2496 columns to indent a block of code, whether an opening brace gets
2497 indented to the level of the code it encloses, or of the construct
2498 that introduces it, or ``hangs'' at the end of a line.
2499
2500 Most people only need to edit code formatted in just a few well-defined
2501 and consistent styles. For example, their organization might impose a
2502 ``blessed'' style that all its programmers must conform to. Similarly,
2503 people who work on GNU software will have to use the GNU coding style.
2504 Some shops are more lenient, allowing a variety of coding styles, and as
2505 programmers come and go, there could be a number of styles in use. For
2506 this reason, @ccmode{} makes it convenient for you to set up logical
2507 groupings of customizations called @dfn{styles}, associate a single name
2508 for any particular style, and pretty easily start editing new or
2509 existing code using these styles.
2510
2511 @menu
2512 * Built-in Styles::
2513 * Choosing a Style::
2514 * Adding Styles::
2515 * File Styles::
2516 @end menu
2517
2518
2519 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2520 @node Built-in Styles, Choosing a Style, Styles, Styles
2521 @comment node-name, next, previous, up
2522 @subsection Built-in Styles
2523 @cindex styles, built-in
2524 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2525
2526 If you're lucky, one of @ccmode{}'s built-in styles might be just
2527 what you're looking for. These are:
2528
2529 @table @code
2530 @item gnu
2531 @cindex GNU style
2532 Coding style blessed by the Free Software Foundation
2533 for C code in GNU programs.
2534
2535 @item k&r
2536 @cindex K&R style
2537 The classic Kernighan and Ritchie style for C code.
2538
2539 @item bsd
2540 @cindex BSD style
2541 Also known as ``Allman style'' after Eric Allman.
2542
2543 @item whitesmith
2544 @cindex Whitesmith style
2545 Popularized by the examples that came with Whitesmiths C, an early
2546 commercial C compiler.
2547
2548 @item stroustrup
2549 @cindex Stroustrup style
2550 The classic Stroustrup style for C++ code.
2551
2552 @item ellemtel
2553 @cindex Ellemtel style
2554 Popular C++ coding standards as defined by ``Programming in C++, Rules
2555 and Recommendations,'' Erik Nyquist and Mats Henricson,
2556 Ellemtel@footnote{This document is available at
2557 @uref{http://www.doc.ic.ac.uk/lab/cplus/c++.rules/} among other
2558 places.}.
2559 @c N.B. This URL was still valid at 2005/8/28 (ACM).
2560
2561 @item linux
2562 @cindex Linux style
2563 C coding standard for Linux (the kernel).
2564
2565 @item python
2566 @cindex Python style
2567 C coding standard for Python extension modules@footnote{Python is a
2568 high level scripting language with a C/C++ foreign function interface.
2569 For more information, see @uref{http://www.python.org/}.}.
2570
2571 @item java
2572 @cindex Java style
2573 The style for editing Java code. Note that the default
2574 value for @code{c-default-style} installs this style when you enter
2575 @code{java-mode}.
2576
2577 @item awk
2578 @cindex AWK style
2579 The style for editing AWK code. Note that the default value for
2580 @code{c-default-style} installs this style when you enter
2581 @code{awk-mode}.
2582
2583 @item user
2584 @cindex User style
2585 This is a special style created by you. It consists of the factory
2586 defaults for all the style variables as modified by the customizations
2587 you do either with the Customization interface or by writing
2588 @code{setq}s and @code{c-set-offset}s at the top level of your
2589 @file{.emacs} file (@pxref{Config Basics}). The style system creates
2590 this style as part of its initialization and doesn't modify it
2591 afterwards.
2592 @end table
2593
2594
2595 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2596 @node Choosing a Style, Adding Styles, Built-in Styles, Styles
2597 @comment node-name, next, previous, up
2598 @subsection Choosing a Style
2599 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2600
2601 When you create a new buffer, its style will be set from
2602 @code{c-default-style}. The factory default is the style @code{gnu},
2603 except in Java and AWK modes where it's @code{java} and @code{awk}.
2604
2605 Remember that if you set a style variable with the Customization
2606 interface or at the top level of your @file{.emacs} file before the
2607 style system is initialised (@pxref{Config Basics}), this setting will
2608 override the one that the style system would have given the variable.
2609
2610 To set a buffer's style interactively, use the command @kbd{C-c .}
2611 (@pxref{Other Commands}). To set it from a file's local variable
2612 list, @ref{File Styles}.
2613
2614 @defopt c-default-style
2615 @vindex default-style (c-)
2616 This variable specifies which style to install by default in new
2617 buffers. It takes either a style name string, or an association list
2618 of major mode symbols to style names:
2619
2620 @enumerate
2621 @item
2622 When @code{c-default-style} is a string, it must be an existing style
2623 name. This style is then used for all modes.
2624
2625 @item
2626 When @code{c-default-style} is an association list, the mode language
2627 is looked up to find a style name string.
2628
2629 @item
2630 If @code{c-default-style} is an association list where the mode
2631 language mode isn't found then the special symbol @samp{other} is
2632 looked up. If it's found then the associated style is used.
2633
2634 @item
2635 If @samp{other} is not found then the @samp{gnu} style is used.
2636 @end enumerate
2637
2638 In all cases, the style described in @code{c-default-style} is installed
2639 @emph{before} the language hooks are run, so you can always override
2640 this setting by including an explicit call to @code{c-set-style} in your
2641 language mode hook, or in @code{c-mode-common-hook}.
2642
2643 The standard value of @code{c-default-style} is @w{@code{((java-mode
2644 . "java") (awk-mode . "awk") (other . "gnu"))}}.
2645 @end defopt
2646
2647 @defvar c-indentation-style
2648 @vindex indentation-style (c-)
2649 This variable always contains the buffer's current style name, as a
2650 string.
2651 @end defvar
2652
2653
2654 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2655 @node Adding Styles, File Styles, Choosing a Style, Styles
2656 @comment node-name, next, previous, up
2657 @subsection Adding and Amending Styles
2658 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2659
2660 If none of the built-in styles is appropriate, you'll probably want to
2661 create a new @dfn{style definition}, possibly based on an existing
2662 style. To do this, put the new style's settings into a list with the
2663 following format - the list can then be passed as an argument to the
2664 function @code{c-add-style}. You can see an example of a style
2665 definition in @ref{Sample .emacs File}.
2666
2667 @cindex style definition
2668 @c @defvr {List} style definition
2669 @table @asis
2670 @item Structure of a Style Definition List
2671 ([@var{base-style}] [(@var{variable} . @var{value}) @dots{}])
2672
2673 Optional @var{base-style}, if present, must be a string which is the
2674 name of the @dfn{base style} from which this style inherits. At most
2675 one @var{base-style} is allowed in a style definition. If
2676 @var{base-style} is not specified, the style inherits from the table
2677 of factory default values@footnote{This table is stored internally in
2678 the variable c-fallback-style.} instead. All styles eventually
2679 inherit from this internal table. Style loops generate errors. The
2680 list of pre-existing styles can be seen in @ref{Built-in Styles}.
2681
2682 The dotted pairs (@var{variable} . @var{value}) each consist of a
2683 variable and the value it is to be set to when the style is later
2684 activated.@footnote{Note that if the variable has been given a value
2685 by the Customization interface or a @code{setq} at the top level of
2686 your @file{.emacs}, this value will override the one the style system
2687 tries to give it. @xref{Config Basics}.} The variable can be either a
2688 @ccmode{} style variable or an arbitrary Emacs variable. In the
2689 latter case, it is @emph{not} made buffer-local by the @ccmode{} style
2690 system.
2691 @c @end defvr
2692
2693 Two variables are treated specially in the dotted pair list:
2694
2695 @table @code
2696 @item c-offsets-alist
2697 The value is in turn a list of dotted pairs of the form
2698
2699 @example
2700 (@r{@var{syntactic-symbol}} . @r{@var{offset}})
2701 @end example
2702
2703 as described in @ref{c-offsets-alist}. These are passed to
2704 @code{c-set-offset} so there is no need to set every syntactic symbol
2705 in your style, only those that are different from the inherited style.
2706
2707 @item c-special-indent-hook
2708 The value is added to @code{c-special-indent-hook} using
2709 @code{add-hook}, so any functions already on it are kept. If the value
2710 is a list, each element of the list is added with @code{add-hook}.
2711 @end table
2712 @end table
2713
2714 Styles are kept in the @code{c-style-alist} variable, but you
2715 should never modify this variable directly. Instead, @ccmode{}
2716 provides the function @code{c-add-style} for this purpose.
2717
2718 @defun c-add-style stylename description &optional set-p
2719 @findex add-style (c-)
2720 Add or update a style called @var{stylename}, a string.
2721 @var{description} is the new style definition in the form described
2722 above. If @var{stylename} already exists in @code{c-style-alist} then
2723 it is replaced by @var{description}. (Note, this replacement is
2724 total. The old style is @emph{not} merged into the new one.)
2725 Otherwise, a new style is added.
2726
2727 If the optional @var{set-p} is non-@code{nil} then the new style is
2728 applied to the current buffer as well. The use of this facility is
2729 deprecated and it might be removed from @ccmode{} in a future release.
2730 You should use @code{c-set-style} instead.
2731
2732 The sample @file{.emacs} file provides a concrete example of how a new
2733 style can be added and automatically set. @xref{Sample .emacs File}.
2734 @end defun
2735
2736 @defvar c-style-alist
2737 @vindex style-alist (c-)
2738 This is the variable that holds the definitions for the styles. It
2739 should not be changed directly; use @code{c-add-style} instead.
2740 @end defvar
2741
2742
2743 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2744 @node File Styles, , Adding Styles, Styles
2745 @comment node-name, next, previous, up
2746 @subsection File Styles
2747 @cindex styles, file local
2748 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2749
2750 @cindex file local variables
2751
2752 The Emacs manual describes how you can customize certain variables on a
2753 per-file basis by including a @dfn{file local variable} block at the end
2754 of the file (@pxref{File Variables,, Local Variables in Files, @emacsman{},
2755 @emacsmantitle{}}).
2756
2757 So far, you've only seen a functional interface for setting styles in
2758 @ccmode{}, and this can't be used here. @ccmode{} fills the gap by
2759 providing two variables for use in a file's local variable list.
2760 Don't use them anywhere else! These allow you to customize the style
2761 on a per-file basis:
2762
2763 @defvar c-file-style
2764 @vindex file-style (c-)
2765 Set this variable to a style name string in the Local Variables list.
2766 From now on, when you visit the file, @ccmode{} will automatically set
2767 the file's style to this one using @code{c-set-style}.
2768 @end defvar
2769
2770 @defvar c-file-offsets
2771 @vindex file-offsets (c-)
2772 Set this variable (in the Local Variables list) to an association list
2773 of the same format as @code{c-offsets-alist}. From now on, when you
2774 visit the file, @ccmode{} will automatically institute these offsets
2775 using @code{c-set-offset}.
2776 @end defvar
2777
2778 Note that file style settings (i.e. @code{c-file-style}) are applied
2779 before file offset settings
2780 (i.e. @code{c-file-offsets})@footnote{Also, if either of these are set
2781 in a file's local variable section, all the style variable values are
2782 made local to that buffer, even if
2783 @code{c-style-variables-are-local-p} is @code{nil}. Since this
2784 variable is virtually always non-@code{nil} anyhow, you're unlikely to
2785 notice this effect.}.
2786
2787 If you set any variables, including style variables, by the file local
2788 variables mechanism, these settings take priority over all other
2789 settings, even those in your mode hooks (@pxref{CC Hooks}). If you
2790 use @code{c-file-style} or @code{c-file-offsets} and also explicitly
2791 set a style variable in a local variable block, the explicit setting
2792 will take priority.
2793
2794 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2795 @node Custom Filling and Breaking, Custom Auto-newlines, Config Basics, Top
2796 @comment node-name, next, previous, up
2797 @chapter Customizing Filling and Line Breaking
2798 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2799
2800 Since there's a lot of normal text in comments and string literals,
2801 @ccmode{} provides features to edit these like in text mode. It does
2802 this by hooking in on the different line breaking functions and tuning
2803 relevant variables as necessary.
2804
2805 @vindex c-comment-prefix-regexp
2806 @vindex comment-prefix-regexp (c-)
2807 @cindex comment line prefix
2808 @vindex comment-start
2809 @vindex comment-end
2810 @vindex comment-start-skip
2811 @vindex paragraph-start
2812 @vindex paragraph-separate
2813 @vindex paragraph-ignore-fill-prefix
2814 @vindex adaptive-fill-mode
2815 @vindex adaptive-fill-regexp
2816 @vindex adaptive-fill-first-line-regexp
2817 To make Emacs recognize comments and treat text in them as normal
2818 paragraphs, @ccmode{} makes several standard
2819 variables@footnote{@code{comment-start}, @code{comment-end},
2820 @code{comment-start-skip}, @code{paragraph-start},
2821 @code{paragraph-separate}, @code{paragraph-ignore-fill-prefix},
2822 @code{adaptive-fill-mode}, @code{adaptive-fill-regexp}, and
2823 @code{adaptive-fill-first-line-regexp}.} buffer-local and modifies them
2824 according to the language syntax and the comment line prefix.
2825
2826 @defopt c-comment-prefix-regexp
2827 @vindex comment-prefix-regexp (c-)
2828 This style variable contains the regexp used to recognize the
2829 @dfn{comment line prefix}, which is the line decoration that starts
2830 every line in a comment. The variable is either the comment line
2831 prefix itself, or (more usually) an association list with different
2832 values for different languages. The symbol for the major mode is
2833 looked up in the alist to get the regexp for the language, and if it
2834 isn't found then the special symbol @samp{other} is looked up instead.
2835
2836 When a comment line gets divided by @kbd{M-j} or the like, @ccmode{}
2837 inserts the comment line prefix from a neighbouring line at the start
2838 of the new line. The default value of c-comment-prefix-regexp is
2839 @samp{//+\\|\\**}, which matches C++ style line comments like
2840
2841 @example
2842 // blah blah
2843 @end example
2844
2845 @noindent
2846 with two or more slashes in front of them, and the second and
2847 subsequent lines of C style block comments like
2848
2849 @example
2850 @group
2851 /*
2852 * blah blah
2853 */
2854 @end group
2855 @end example
2856
2857 @noindent
2858 with zero or more stars at the beginning of every line. If you change
2859 this variable, please make sure it still matches the comment starter
2860 (i.e. @code{//}) of line comments @emph{and} the line prefix inside
2861 block comments.
2862
2863 @findex c-setup-paragraph-variables
2864 @findex setup-paragraph-variables (c-)
2865 Also note that since @ccmode{} uses the value of
2866 @code{c-comment-prefix-regexp} to set up several other variables at
2867 mode initialization, there won't be any effect if you just change it
2868 inside a @ccmode{} buffer. You need to call the command
2869 @code{c-setup-paragraph-variables} too, to update those other
2870 variables. That's also the case if you modify
2871 @code{c-comment-prefix-regexp} in a mode hook, since @ccmode{} will
2872 already have set up these variables before calling the hook.
2873 @end defopt
2874
2875 In comments, @ccmode{} uses @code{c-comment-prefix-regexp} to adapt
2876 the line prefix from the other lines in the comment.
2877
2878 @vindex adaptive-fill-mode
2879 @cindex Adaptive Fill mode
2880 @ccmode{} uses adaptive fill mode (@pxref{Adaptive Fill,,, emacs, GNU
2881 Emacs Manual}) to make Emacs correctly keep the line prefix when
2882 filling paragraphs. That also makes Emacs preserve the text
2883 indentation @emph{inside} the comment line prefix. E.g. in the
2884 following comment, both paragraphs will be filled with the left
2885 margins of the texts kept intact:
2886
2887 @example
2888 @group
2889 /* Make a balanced b-tree of the nodes in the incoming
2890 * stream. But, to quote the famous words of Donald E.
2891 * Knuth,
2892 *
2893 * Beware of bugs in the above code; I have only
2894 * proved it correct, not tried it.
2895 */
2896 @end group
2897 @end example
2898
2899 @findex c-setup-filladapt
2900 @findex setup-filladapt (c-)
2901 @findex filladapt-mode
2902 @vindex filladapt-mode
2903 @cindex Filladapt mode
2904 It's also possible to use other adaptive filling packages, notably Kyle
2905 E. Jones' Filladapt package@footnote{It's available from
2906 @uref{http://www.wonderworks.com/}. As of version 2.12, it does however
2907 lack a feature that makes it work suboptimally when
2908 @code{c-comment-prefix-regexp} matches the empty string (which it does
2909 by default). A patch for that is available from
2910 @uref{http://cc-mode.sourceforge.net/,, the CC Mode web site}.},
2911 @c 2005/11/22: The above is still believed to be the case.
2912 which handles things like bulleted lists nicely. There's a convenience
2913 function @code{c-setup-filladapt} that tunes the relevant variables in
2914 Filladapt for use in @ccmode{}. Call it from a mode hook, e.g. with
2915 something like this in your @file{.emacs}:
2916
2917 @example
2918 (defun my-c-mode-common-hook ()
2919 (c-setup-filladapt)
2920 (filladapt-mode 1))
2921 (add-hook 'c-mode-common-hook 'my-c-mode-common-hook)
2922 @end example
2923
2924 @defopt c-block-comment-prefix
2925 @vindex block-comment-prefix (c-)
2926 @vindex c-comment-continuation-stars
2927 @vindex comment-continuation-stars (c-)
2928 Normally the comment line prefix inserted for a new line inside a
2929 comment is deduced from other lines in it. However there's one
2930 situation when there's no hint about what the prefix should look like,
2931 namely when a block comment is broken for the first time. This style
2932 variable@footnote{In versions before 5.26, this variable was called
2933 @code{c-comment-continuation-stars}. As a compatibility measure,
2934 @ccmode{} still uses the value on that variable if it's set.} is used
2935 then as the comment prefix. It defaults to @samp{*
2936 }@footnote{Actually, this default setting of
2937 @code{c-block-comment-prefix} typically gets overridden by the default
2938 style @code{gnu}, which sets it to blank. You can see the line
2939 splitting effect described here by setting a different style,
2940 e.g. @code{k&r} @xref{Choosing a Style}.}, which makes a comment
2941
2942 @example
2943 /* Got O(n^2) here, which is a Bad Thing. */
2944 @end example
2945
2946 @noindent
2947 break into
2948
2949 @example
2950 @group
2951 /* Got O(n^2) here, which
2952 * is a Bad Thing. */
2953 @end group
2954 @end example
2955
2956 Note that it won't work to adjust the indentation by putting leading
2957 spaces in @code{c-block-comment-prefix}, since @ccmode{} still uses the
2958 normal indentation engine to indent the line. Thus, the right way to
2959 fix the indentation is by customizing the @code{c} syntactic symbol. It
2960 defaults to @code{c-lineup-C-comments}, which handles the indentation of
2961 most common comment styles, see @ref{Line-Up Functions}.
2962 @end defopt
2963
2964 @defopt c-ignore-auto-fill
2965 @vindex ignore-auto-fill (c-)
2966 When auto fill mode is enabled, @ccmode{} can selectively ignore it
2967 depending on the context the line break would occur in, e.g. to never
2968 break a line automatically inside a string literal. This variable
2969 takes a list of symbols for the different contexts where auto-filling
2970 never should occur:
2971
2972 @table @code
2973 @item string
2974 Inside a string or character literal.
2975 @item c
2976 Inside a C style block comment.
2977 @item c++
2978 Inside a C++ style line comment.
2979 @item cpp
2980 Inside a preprocessor directive.
2981 @item code
2982 Anywhere else, i.e. in normal code.
2983 @end table
2984
2985 By default, @code{c-ignore-auto-fill} is set to @code{(string cpp
2986 code)}, which means that when auto-fill mode is activated,
2987 auto-filling only occurs in comments. In literals, it's often
2988 desirable to have explicit control over newlines. In preprocessor
2989 directives, the necessary @samp{\} escape character before the newline
2990 is not automatically inserted, so an automatic line break would
2991 produce invalid code. In normal code, line breaks are normally
2992 dictated by some logical structure in the code rather than the last
2993 whitespace character, so automatic line breaks there will produce poor
2994 results in the current implementation.
2995 @end defopt
2996
2997 @vindex comment-multi-line
2998 If inside a comment and @code{comment-multi-line} (@pxref{Auto Fill,,,
2999 @emacsman{}, @emacsmantitle{}} is non-@code{nil}, the indentation and
3000 line prefix are preserved. If inside a comment and
3001 @code{comment-multi-line} is @code{nil}, a new comment of the same
3002 type is started on the next line and indented as appropriate for
3003 comments.
3004
3005 Note that @ccmode{} sets @code{comment-multi-line} to @code{t} at
3006 startup. The reason is that @kbd{M-j} could otherwise produce sequences
3007 of single line block comments for texts that should logically be treated
3008 as one comment, and the rest of the paragraph handling code
3009 (e.g. @kbd{M-q} and @kbd{M-a}) can't cope with that, which would lead to
3010 inconsistent behavior.
3011
3012 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3013 @node Custom Auto-newlines, Clean-ups, Custom Filling and Breaking, Top
3014 @comment node-name, next, previous, up
3015 @chapter Customizing Auto-newlines
3016 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3017
3018 @ccmode{} determines whether to insert auto-newlines in two basically
3019 different ways, depending on the character just typed:
3020
3021 @table @asis
3022 @item Braces and Colons
3023 @ccmode{} first determines the syntactic context of the brace or colon
3024 (@pxref{Syntactic Symbols}), then looks for a corresponding element in
3025 an alist. This element specifies where to put newlines - this is any
3026 combination of before and after the brace or colon. If no alist
3027 element is found, newlines are inserted both before and after a brace,
3028 but none are inserted around a colon. See @ref{Hanging Braces} and
3029 @ref{Hanging Colons}.
3030
3031 @item Semicolons and Commas
3032 The variable @code{c-hanging-semi&comma-criteria} contains a list of
3033 functions which determine whether to insert a newline after a newly
3034 typed semicolon or comma. @xref{Hanging Semicolons and Commas}.
3035 @end table
3036
3037 The names of these configuration variables contain @samp{hanging}
3038 because they let you @dfn{hang} the pertinent characters. A character
3039 which introduces a C construct is said to @dfn{hang on the right} when
3040 it appears at the end of a line after other code, being separated by a
3041 line break from the construct it introduces, like the opening brace in:
3042
3043 @example
3044 @group
3045 while (i < MAX) @{
3046 total += entry[i];
3047 entry [i++] = 0;
3048 @}
3049 @end group
3050 @end example
3051
3052 @noindent
3053 A character @dfn{hangs on the left} when it appears at the start of
3054 the line after the construct it closes off, like the above closing
3055 brace.
3056
3057 The next chapter, ``Clean-ups'', describes how to configure @ccmode{}
3058 to remove these automatically added newlines in certain specific
3059 circumstances. @xref{Clean-ups}.
3060
3061 @menu
3062 * Hanging Braces::
3063 * Hanging Colons::
3064 * Hanging Semicolons and Commas::
3065 @end menu
3066
3067
3068 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3069 @node Hanging Braces, Hanging Colons, Custom Auto-newlines, Custom Auto-newlines
3070 @comment node-name, next, previous, up
3071 @section Hanging Braces
3072 @cindex hanging braces
3073 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3074
3075 To specify which kinds of braces you want auto-newlines put around,
3076 you set the style variable @code{c-hanging-braces-alist}. Its
3077 structure and semantics are described in this section. Details of how
3078 to set it up, and its relationship to CC Mode's style system are given
3079 in @ref{Style Variables}.
3080
3081 Say you wanted an auto-newline after (but not before) the following
3082 @samp{@{}:
3083
3084 @example
3085 if (foo < 17) @{
3086 @end example
3087
3088 @noindent
3089 First you need to find the @dfn{syntactic context} of the brace---type
3090 a @key{RET} before the brace to get it on a line of its
3091 own@footnote{Also insert a @samp{\} at the end of the previous line if
3092 you're in AWK Mode.}, then type @kbd{C-c C-s}. That will tell you
3093 something like:
3094
3095 @example
3096 ((substatement-open 1061))
3097 @end example
3098
3099 @noindent
3100 So here you need to put the entry @code{(substatement-open . (after))}
3101 into @code{c-hanging-braces-alist}.
3102
3103 If you don't want any auto-newlines for a particular syntactic symbol,
3104 put this into @code{c-hanging-braces-alist}:
3105
3106 @example
3107 (brace-entry-open)
3108 @end example
3109
3110 If some brace syntactic symbol is not in @code{c-hanging-brace-alist},
3111 its entry is taken by default as @code{(before after)}---insert a
3112 newline both before and after the brace. In place of a
3113 ``before/after'' list you can specify a function in this alist---this
3114 is useful when the auto newlines depend on the code around the brace.
3115
3116 @defopt c-hanging-braces-alist
3117 @vindex hanging-braces-alist (c-)
3118
3119 This variable is an association list which maps syntactic symbols to
3120 lists of places to insert a newline. @xref{Association
3121 Lists,,,@lispref{}, @lispreftitle{}}. The key of each element is the
3122 syntactic symbol, the associated value is either @code{nil}, a list,
3123 or a function.
3124
3125 @table @asis
3126 @item The Key - the syntactic symbol
3127 The syntactic symbols that are useful as keys in this list are
3128 @code{brace-list-intro}, @code{statement-cont},
3129 @code{inexpr-class-open}, @code{inexpr-class-close}, and all the
3130 @code{*-open} and @code{*-close} symbols. @xref{Syntactic Symbols},
3131 for a more detailed description of these syntactic symbols, except for
3132 @code{inexpr-class-open} and @code{inexpr-class-close}, which aren't
3133 actual syntactic symbols. Elements with any other value as a key get
3134 ignored.
3135
3136 The braces of anonymous inner classes in Java are given the special
3137 symbols @code{inexpr-class-open} and @code{inexpr-class-close}, so that
3138 they can be distinguished from the braces of normal classes@footnote{The
3139 braces of anonymous classes produce a combination of
3140 @code{inexpr-class}, and @code{class-open} or @code{class-close} in
3141 normal indentation analysis.}.
3142
3143 Note that the aggregate constructs in Pike mode, @samp{(@{}, @samp{@})},
3144 @samp{([}, @samp{])}, and @samp{(<}, @samp{>)}, do not count as brace
3145 lists in this regard, even though they do for normal indentation
3146 purposes. It's currently not possible to set automatic newlines on
3147 these constructs.
3148
3149 @item The associated value - the ``ACTION'' list or function
3150 The value associated with each syntactic symbol in this association
3151 list is called an @var{action}, which can be either a list or a
3152 function which returns a list. @xref{Custom Braces}, for how to use
3153 a function as a brace hanging @var{action}.
3154
3155 The list @var{action} (or the list returned by @var{action} when it's
3156 a function) contains some combination of the symbols @code{before} and
3157 @code{after}, directing @ccmode{} where to put newlines in
3158 relationship to the brace being inserted. Thus, if the list contains
3159 only the symbol @code{after}, then the brace hangs on the right side
3160 of the line, as in:
3161
3162 @example
3163 // here, open braces always `hang'
3164 void spam( int i ) @{
3165 if( i == 7 ) @{
3166 dosomething(i);
3167 @}
3168 @}
3169 @end example
3170
3171 When the list contains both @code{after} and @code{before}, the braces
3172 will appear on a line by themselves, as shown by the close braces in
3173 the above example. The list can also be empty, in which case newlines
3174 are added neither before nor after the brace.
3175 @end table
3176
3177 If a syntactic symbol is missing entirely from
3178 @code{c-hanging-braces-alist}, it's treated in the same way as an
3179 @var{action} with a list containing @code{before} and @code{after}, so
3180 that braces by default end up on their own line.
3181
3182 For example, the default value of @code{c-hanging-braces-alist} is:
3183
3184 @example
3185 ((brace-list-open)
3186 (brace-entry-open)
3187 (statement-cont)
3188 (substatement-open after)
3189 (block-close . c-snug-do-while)
3190 (extern-lang-open after)
3191 (namespace-open after)
3192 (module-open after)
3193 (composition-open after)
3194 (inexpr-class-open after)
3195 (inexpr-class-close before))
3196 @end example
3197
3198 @noindent which says that @code{brace-list-open},
3199 @code{brace-entry-open} and @code{statement-cont}@footnote{Brace lists
3200 inside statements, such as initializers for static array variables
3201 inside functions in C, are recognized as @code{statement-cont}. All
3202 normal substatement blocks are recognized with other symbols.} braces
3203 should both hang on the right side and allow subsequent text to follow
3204 on the same line as the brace. Also, @code{substatement-open},
3205 @code{extern-lang-open}, and @code{inexpr-class-open} braces should hang
3206 on the right side, but subsequent text should follow on the next line.
3207 The opposite holds for @code{inexpr-class-close} braces; they won't
3208 hang, but the following text continues on the same line. Here, in the
3209 @code{block-close} entry, you also see an example of using a function as
3210 an @var{action}. In all other cases, braces are put on a line by
3211 themselves.
3212 @end defopt
3213
3214 @menu
3215 * Custom Braces::
3216 @end menu
3217
3218 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3219 @node Custom Braces, , Hanging Braces, Hanging Braces
3220 @comment node-name, next, previous, up
3221 @subsection Custom Brace Hanging
3222 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3223
3224 @vindex c-hanging-braces-alist
3225 @vindex hanging-braces-alist (c-)
3226 @cindex action functions
3227 Syntactic symbols aren't the only place where you can customize
3228 @ccmode{} with the lisp equivalent of callback functions. Remember
3229 that @var{action}s are usually a list containing some combination of
3230 the symbols @code{before} and @code{after} (@pxref{Hanging Braces}).
3231 For more flexibility, you can instead specify brace ``hanginess'' by
3232 giving a syntactic symbol an @dfn{action function} in
3233 @code{c-hanging-braces-alist}; this function determines the
3234 ``hanginess'' of a brace, usually by looking at the code near it.
3235
3236 @cindex customization, brace hanging
3237 An action function is called with two arguments: the syntactic symbol
3238 for the brace (e.g. @code{substatement-open}), and the buffer position
3239 where the brace has been inserted. Point is undefined on entry to an
3240 action function, but the function must preserve it (e.g. by using
3241 @code{save-excursion}). The return value should be a list containing
3242 some combination of @code{before} and @code{after}, including neither
3243 of them (i.e. @code{nil}).
3244
3245 @defvar c-syntactic-context
3246 @vindex syntactic-context (c-)
3247 During the call to the indentation or brace hanging @var{action}
3248 function, this variable is bound to the full syntactic analysis list.
3249 This might be, for example, @samp{((block-close 73))}. Don't ever
3250 give @code{c-syntactic-context} a value yourself---this would disrupt
3251 the proper functioning of @ccmode{}.
3252
3253 This variable is also bound in three other circumstances:
3254 (i)@w{ }when calling a c-hanging-semi&comma-criteria function
3255 (@pxref{Hanging Semicolons and Commas}); (ii)@w{ }when calling a
3256 line-up function (@pxref{Custom Line-Up}); (iii)@w{ }when calling a
3257 c-special-indent-hook function (@pxref{Other Indentation}).
3258 @end defvar
3259
3260 As an example, @ccmode{} itself uses this feature to dynamically
3261 determine the hanginess of braces which close ``do-while''
3262 constructs:
3263
3264 @example
3265 void do_list( int count, char** atleast_one_string )
3266 @{
3267 int i=0;
3268 do @{
3269 handle_string( atleast_one_string[i] );
3270 i++;
3271 @} while( i < count );
3272 @}
3273 @end example
3274
3275 @ccmode{} assigns the @code{block-close} syntactic symbol to the
3276 brace that closes the @code{do} construct, and normally we'd like the
3277 line that follows a @code{block-close} brace to begin on a separate
3278 line. However, with ``do-while'' constructs, we want the
3279 @code{while} clause to follow the closing brace. To do this, we
3280 associate the @code{block-close} symbol with the @var{action} function
3281 @code{c-snug-do-while}:
3282
3283 @example
3284 (defun c-snug-do-while (syntax pos)
3285 "Dynamically calculate brace hanginess for do-while statements."
3286 (save-excursion
3287 (let (langelem)
3288 (if (and (eq syntax 'block-close)
3289 (setq langelem (assq 'block-close c-syntactic-context))
3290 (progn (goto-char (cdr langelem))
3291 (if (= (following-char) ?@{)
3292 (forward-sexp -1))
3293 (looking-at "\\<do\\>[^_]")))
3294 '(before)
3295 '(before after)))))
3296 @end example
3297
3298 @findex c-snug-do-while
3299 @findex snug-do-while (c-)
3300 This function simply looks to see if the brace closes a ``do-while''
3301 clause and if so, returns the list @samp{(before)} indicating
3302 that a newline should be inserted before the brace, but not after it.
3303 In all other cases, it returns the list @samp{(before after)} so
3304 that the brace appears on a line by itself.
3305
3306 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3307 @node Hanging Colons, Hanging Semicolons and Commas, Hanging Braces, Custom Auto-newlines
3308 @comment node-name, next, previous, up
3309 @section Hanging Colons
3310 @cindex hanging colons
3311 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3312
3313 @cindex customization, colon hanging
3314 @vindex c-hanging-colons-alist
3315 @vindex hanging-colons-alist (c-)
3316
3317 Using a mechanism similar to brace hanging (@pxref{Hanging Braces}),
3318 colons can also be made to hang using the style variable
3319 @code{c-hanging-colons-alist} - When a colon is typed, @ccmode
3320 determines its syntactic context, looks this up in the alist
3321 @code{c-changing-colons-alist} and inserts up to two newlines
3322 accordingly. Here, however, If @ccmode fails to find an entry for a
3323 syntactic symbol in the alist, no newlines are inserted around the
3324 newly typed colon.
3325
3326 @defopt c-hanging-colons-alist
3327 @vindex hanging-colons-alist (c-)
3328
3329 @table @asis
3330 @item The Key - the syntactic symbol
3331 The syntactic symbols appropriate as keys in this association list
3332 are: @code{case-label}, @code{label}, @code{access-label},
3333 @code{member-init-intro}, and @code{inher-intro}. @xref{Syntactic
3334 Symbols}. Elements with any other value as a key get ignored.
3335
3336 @item The associate value - the ``ACTION'' list
3337 The @var{action} here is simply a list containing a combination of the
3338 symbols @code{before} and @code{after}. Unlike in
3339 @code{c-hanging-braces-alist}, functions as @var{actions} are not
3340 supported - there doesn't seem to be any need for them.
3341 @end table
3342 @end defopt
3343
3344 In C++, double-colons are used as a scope operator but because these
3345 colons always appear right next to each other, newlines before and after
3346 them are controlled by a different mechanism, called @dfn{clean-ups} in
3347 @ccmode{}. @xref{Clean-ups}, for details.
3348
3349 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3350 @node Hanging Semicolons and Commas, , Hanging Colons, Custom Auto-newlines
3351 @comment node-name, next, previous, up
3352 @section Hanging Semicolons and Commas
3353 @cindex hanging semicolons
3354 @cindex hanging commas
3355 @cindex customization, semicolon newlines
3356 @cindex customization, comma newlines
3357 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3358
3359 @defopt c-hanging-semi&comma-criteria
3360 @vindex hanging-semi&comma-criteria (c-)
3361 This style variable takes a list of functions; these get called when
3362 you type a semicolon or comma. The functions are called in order
3363 without arguments. When these functions are entered, point is just
3364 after the newly inserted @samp{;} or @samp{,} and they must preserve
3365 point (e.g., by using @code{save-excursion}). During the call, the
3366 variable @code{c-syntactic-context} is bound to the syntactic context
3367 of the current line@footnote{This was first introduced in @ccmode{}
3368 5.31.} @pxref{Custom Braces}. These functions don't insert newlines
3369 themselves, rather they direct @ccmode{} whether or not to do so.
3370 They should return one of the following values:
3371
3372 @table @code
3373 @item t
3374 A newline is to be inserted after the @samp{;} or @samp{,}, and no
3375 more functions from the list are to be called.
3376 @item stop
3377 No more functions from the list are to be called, and no newline is to
3378 be inserted.
3379 @item nil
3380 No determination has been made, and the next function in the list is
3381 to be called.
3382 @end table
3383
3384 Note that auto-newlines are never inserted @emph{before} a semicolon
3385 or comma. If every function in the list is called without a
3386 determination being made, then no newline is added.
3387
3388 In AWK mode, this variable is set by default to @code{nil}. In the
3389 other modes, the default value is a list containing a single function,
3390 @code{c-semi&comma-inside-parenlist}. This inserts newlines after all
3391 semicolons, apart from those separating @code{for}-clause statements.
3392 @end defopt
3393
3394 @defun c-semi&comma-no-newlines-before-nonblanks
3395 @findex semi&comma-no-newlines-before-nonblanks (c-)
3396 This is an example of a criteria function, provided by @ccmode{}. It
3397 prevents newlines from being inserted after semicolons when there is a
3398 non-blank following line. Otherwise, it makes no determination. To
3399 use, add this function to the front of the
3400 @code{c-hanging-semi&comma-criteria} list.
3401
3402 @example
3403 (defun c-semi&comma-no-newlines-before-nonblanks ()
3404 (save-excursion
3405 (if (and (eq last-command-char ?\;)
3406 (zerop (forward-line 1))
3407 (not (looking-at "^[ \t]*$")))
3408 'stop
3409 nil)))
3410 @end example
3411 @end defun
3412
3413 @defun c-semi&comma-inside-parenlist
3414 @findex semi&comma-inside-parenlist (c-)
3415 @defunx c-semi&comma-no-newlines-for-oneline-inliners
3416 @findex semi&comma-no-newlines-for-oneline-inliners (c-)
3417 The function @code{c-semi&comma-inside-parenlist} is what prevents
3418 newlines from being inserted inside the parenthesis list of @code{for}
3419 statements. In addition to
3420 @code{c-semi&comma-no-newlines-before-nonblanks} described above,
3421 @ccmode{} also comes with the criteria function
3422 @code{c-semi&comma-no-newlines-for-oneline-inliners}, which suppresses
3423 newlines after semicolons inside one-line inline method definitions
3424 (e.g. in C++ or Java).
3425 @end defun
3426
3427
3428 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3429 @node Clean-ups, Indentation Engine Basics, Custom Auto-newlines, Top
3430 @comment node-name, next, previous, up
3431 @chapter Clean-ups
3432 @cindex clean-ups
3433 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3434
3435 @dfn{Clean-ups} are mechanisms which remove (or exceptionally, add)
3436 whitespace in specific circumstances and are complementary to colon
3437 and brace hanging. You enable a clean-up by adding its symbol into
3438 @code{c-cleanup-list}, e.g. like this:
3439
3440 @example
3441 (add-to-list 'c-cleanup-list 'space-before-funcall)
3442 @end example
3443
3444 On the surface, it would seem that clean-ups overlap the functionality
3445 provided by the @code{c-hanging-*-alist} variables. Clean-ups,
3446 however, are used to adjust code ``after-the-fact'', i.e. to adjust
3447 the whitespace in constructs later than when they were typed.
3448
3449 Most of the clean-ups remove automatically inserted newlines, and are
3450 only active when auto-newline minor mode is turned on. Others will
3451 work all the time. Note that clean-ups are only performed when there
3452 is nothing but whitespace appearing between the individual components
3453 of the construct, and (apart from @code{comment-close-slash}) when the
3454 construct does not occur within a literal (@pxref{Auto-newlines}).
3455
3456 @defopt c-cleanup-list
3457 @vindex cleanup-list (c-)
3458 @cindex literal
3459
3460 You configure @ccmode{}'s clean-ups by setting the style variable
3461 @code{c-cleanup-list}, which is a list of clean-up symbols. By
3462 default, @ccmode{} cleans up only the @code{scope-operator} construct,
3463 which is necessary for proper C++ support.
3464 @end defopt
3465
3466 These are the clean-ups that are only active when electric and
3467 auto-newline minor modes are enabled:
3468
3469 @c TBD: Would like to use some sort of @deffoo here; @table indents a
3470 @c bit too much in dvi output.
3471 @table @code
3472 @item brace-else-brace
3473 Clean up @samp{@} else @{} constructs by placing the entire construct on
3474 a single line. Clean up occurs when the open brace after the
3475 @samp{else} is typed. So for example, this:
3476
3477 @example
3478 @group
3479 void spam(int i)
3480 @{
3481 if( i==7 ) @{
3482 dosomething();
3483 @}
3484 else
3485 @{
3486 @end group
3487 @end example
3488
3489 @noindent
3490 appears like this after the last open brace is typed:
3491
3492 @example
3493 @group
3494 void spam(int i)
3495 @{
3496 if( i==7 ) @{
3497 dosomething();
3498 @} else @{
3499 @end group
3500 @end example
3501
3502 @item brace-elseif-brace
3503 Similar to the @code{brace-else-brace} clean-up, but this cleans up
3504 @samp{@} else if (...) @{} constructs. For example:
3505
3506 @example
3507 @group
3508 void spam(int i)
3509 @{
3510 if( i==7 ) @{
3511 dosomething();
3512 @}
3513 else if( i==3 )
3514 @{
3515 @end group
3516 @end example
3517
3518 @noindent
3519 appears like this after the last open parenthesis is typed:
3520
3521 @example
3522 @group
3523 void spam(int i)
3524 @{
3525 if( i==7 ) @{
3526 dosomething();
3527 @} else if(
3528 @end group
3529 @end example
3530
3531 @noindent
3532 and like this after the last open brace is typed:
3533
3534 @example
3535 @group
3536 void spam(int i)
3537 @{
3538 if( i==7 ) @{
3539 dosomething();
3540 @} else if( i==3 ) @{
3541 @end group
3542 @end example
3543
3544 @item brace-catch-brace
3545 Analogous to @code{brace-elseif-brace}, but cleans up @samp{@} catch
3546 (...) @{} in C++ and Java mode.
3547
3548 @item empty-defun-braces
3549 Clean up braces following a top-level function or class definition that
3550 contains no body. Clean up occurs when the closing brace is typed.
3551 Thus the following:
3552
3553 @example
3554 @group
3555 class Spam
3556 @{
3557 @}
3558 @end group
3559 @end example
3560
3561 @noindent
3562 is transformed into this when the close brace is typed:
3563
3564 @example
3565 @group
3566 class Spam
3567 @{@}
3568 @end group
3569 @end example
3570
3571 @item defun-close-semi
3572 Clean up the terminating semicolon on top-level function or class
3573 definitions when they follow a close brace. Clean up occurs when the
3574 semicolon is typed. So for example, the following:
3575
3576 @example
3577 @group
3578 class Spam
3579 @{
3580 ...
3581 @}
3582 ;
3583 @end group
3584 @end example
3585
3586 @noindent
3587 is transformed into this when the semicolon is typed:
3588
3589 @example
3590 @group
3591 class Spam
3592 @{
3593 ...
3594 @};
3595 @end group
3596 @end example
3597
3598 @item list-close-comma
3599 Clean up commas following braces in array and aggregate initializers.
3600 Clean up occurs when the comma is typed. The space before the comma
3601 is zapped just like the space before the semicolon in
3602 @code{defun-close-semi}.
3603
3604 @item scope-operator
3605 Clean up double colons which might designate a C++ scope operator split
3606 across multiple lines@footnote{Certain C++ constructs introduce
3607 ambiguous situations, so @code{scope-operator} clean-ups might not
3608 always be correct. This usually only occurs when scoped identifiers
3609 appear in switch label tags.}. Clean up occurs when the second colon is
3610 typed. You will always want @code{scope-operator} in the
3611 @code{c-cleanup-list} when you are editing C++ code.
3612
3613 @item one-liner-defun
3614 Clean up a single line of code enclosed by defun braces by removing
3615 the whitespace before and after the code. The clean-up happens when
3616 the closing brace is typed. If the variable
3617 @code{c-max-one-liner-length} is set, the cleanup is only done if the
3618 resulting line would be no longer than the value of that variable.
3619
3620 For example, consider this AWK code:
3621
3622 @example
3623 @group
3624 BEGIN @{
3625 FS = "\t" # use <TAB> as a field separator
3626 @}
3627 @end group
3628 @end example
3629
3630 @noindent
3631 It gets compacted to the following when the closing brace is typed:
3632
3633 @example
3634 @group
3635 BEGIN @{FS = "\t"@} # use <TAB> as a field separator
3636 @end group
3637 @end example
3638
3639 @defopt c-max-one-liner-length
3640 @vindex max-one-liner-length (c-)
3641 The maximum length of the resulting line for which the clean-up
3642 @code{one-liner-defun} will be triggered. This length is that of the entire
3643 line, including any leading whitespace and any trailing comment. Its
3644 default value is 80. If the value is zero or @code{nil}, no limit
3645 applies.
3646 @end defopt
3647 @end table
3648
3649 The following clean-ups are always active when they occur on
3650 @code{c-cleanup-list}, regardless of whether Electric minor mode or
3651 Auto-newline minor mode are enabled:
3652
3653 @table @code
3654 @item space-before-funcall
3655 Insert a space between the function name and the opening parenthesis
3656 of a function call. This produces function calls in the style
3657 mandated by the GNU coding standards, e.g. @samp{signal@w{ }(SIGINT,
3658 SIG_IGN)} and @samp{abort@w{ }()}. Clean up occurs when the opening
3659 parenthesis is typed. This clean-up should never be active in AWK
3660 Mode, since such a space is syntactically invalid for user defined
3661 functions.
3662
3663 @item compact-empty-funcall
3664 Clean up any space between the function name and the opening parenthesis
3665 of a function call that has no arguments. This is typically used
3666 together with @code{space-before-funcall} if you prefer the GNU function
3667 call style for functions with arguments but think it looks ugly when
3668 it's only an empty parenthesis pair. I.e. you will get @samp{signal
3669 (SIGINT, SIG_IGN)}, but @samp{abort()}. Clean up occurs when the
3670 closing parenthesis is typed.
3671
3672 @item comment-close-slash
3673 When inside a block comment, terminate the comment when you type a slash
3674 at the beginning of a line (i.e. immediately after the comment prefix).
3675 This clean-up removes whitespace preceding the slash and if needed,
3676 inserts a star to complete the token @samp{*/}. Type @kbd{C-q /} in this
3677 situation if you just want a literal @samp{/} inserted.
3678 @end table
3679
3680
3681 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3682 @node Indentation Engine Basics, Customizing Indentation, Clean-ups, Top
3683 @comment node-name, next, previous, up
3684 @chapter Indentation Engine Basics
3685 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3686
3687 This chapter will briefly cover how @ccmode{} indents lines of code.
3688 It is helpful to understand the indentation model being used so that
3689 you will know how to customize @ccmode{} for your personal coding
3690 style. All the details are in @ref{Customizing Indentation}.
3691
3692 @ccmode{} has an indentation engine that provides a flexible and
3693 general mechanism for customizing indentation. When @ccmode{} indents
3694 a line of code, it separates its calculations into two steps:
3695
3696 @enumerate
3697 @item
3698 @cindex syntactic symbol
3699 @cindex anchor position
3700 It analyzes the line to determine its @dfn{syntactic symbol(s)} (the
3701 kind of language construct it's looking at) and its @dfn{anchor
3702 position} (the position earlier in the file that @ccmode{} will indent
3703 the line relative to). The anchor position might be the location of
3704 an opening brace in the previous line, for example. @xref{Syntactic
3705 Analysis}.
3706 @item
3707 @cindex offsets
3708 @cindex indentation offset specifications
3709 It looks up the syntactic symbol(s) in the configuration to get the
3710 corresponding @dfn{offset(s)}. The symbol @code{+}, which means
3711 ``indent this line one more level'' is a typical offset. @ccmode{}
3712 then applies these offset(s) to the anchor position, giving the
3713 indentation for the line. The different sorts of offsets are
3714 described in @ref{c-offsets-alist}.
3715 @end enumerate
3716
3717 In exceptional circumstances, the syntax directed indentation
3718 described here may be a nuisance rather than a help. You can disable
3719 it by setting @code{c-syntactic-indentation} to @code{nil}. (To set
3720 the variable interactively, @ref{Minor Modes}).
3721
3722 @defopt c-syntactic-indentation
3723 @vindex syntactic-indentation (c-)
3724 When this is non-@code{nil} (which it is by default), the indentation
3725 of code is done according to its syntactic structure. When it's
3726 @code{nil}, every line is just indented to the same level as the
3727 previous one, and @kbd{TAB} (@code{c-indent-command}) adjusts the
3728 indentation in steps of @code{c-basic-offset}. The current style
3729 (@pxref{Config Basics}) then has no effect on indentation, nor do any
3730 of the variables associated with indentation, not even
3731 @code{c-special-indent-hook}.
3732 @end defopt
3733
3734 @menu
3735 * Syntactic Analysis::
3736 * Syntactic Symbols::
3737 * Indentation Calculation::
3738 @end menu
3739
3740
3741 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3742 @node Syntactic Analysis, Syntactic Symbols, Indentation Engine Basics, Indentation Engine Basics
3743 @comment node-name, next, previous, up
3744 @section Syntactic Analysis
3745 @cindex syntactic analysis
3746 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3747
3748 @cindex syntactic element
3749 @cindex syntactic context
3750 The first thing @ccmode{} does when indenting a line of code, is to
3751 analyze the line, determining the @dfn{syntactic context} of the
3752 (first) construct on that line. It's a list of @dfn{syntactic
3753 elements}, where each syntactic element in turn is a list@footnote{In
3754 @ccmode 5.28 and earlier, a syntactic element was a dotted pair; the
3755 cons was the syntactic symbol and the cdr was the anchor position.
3756 For compatibility's sake, the parameter passed to a line-up function
3757 still has this dotted pair form (@pxref{Custom Line-Up}).} Here is a
3758 brief and typical example:
3759
3760 @example
3761 ((defun-block-intro 1959))
3762 @end example
3763
3764 @cindex syntactic symbol
3765 @noindent
3766 The first thing inside each syntactic element is always a
3767 @dfn{syntactic symbol}. It describes the kind of construct that was
3768 recognized, e.g. @code{statement}, @code{substatement},
3769 @code{class-open}, @code{class-close}, etc. @xref{Syntactic Symbols},
3770 for a complete list of currently recognized syntactic symbols and
3771 their semantics. The remaining entries are various data associated
3772 with the recognized construct - there might be zero or more.
3773
3774 @cindex anchor position
3775 Conceptually, a line of code is always indented relative to some
3776 position higher up in the buffer (typically the indentation of the
3777 previous line). That position is the @dfn{anchor position} in the
3778 syntactic element. If there is an entry after the syntactic symbol in
3779 the syntactic element list then it's either nil or that anchor position.
3780
3781 Here is an example. Suppose we had the following code as the only thing
3782 in a C++ buffer @footnote{The line numbers in this and future examples
3783 don't actually appear in the buffer, of course!}:
3784
3785 @example
3786 1: void swap( int& a, int& b )
3787 2: @{
3788 3: int tmp = a;
3789 4: a = b;
3790 5: b = tmp;
3791 6: @}
3792 @end example
3793
3794 @noindent
3795 We can use @kbd{C-c C-s} (@code{c-show-syntactic-information}) to
3796 report what the syntactic analysis is for the current line:
3797
3798 @table @asis
3799 @item @kbd{C-c C-s} (@code{c-show-syntactic-information})
3800 @kindex C-c C-s
3801 @findex c-show-syntactic-information
3802 @findex show-syntactic-information (c-)
3803 This command calculates the syntactic analysis of the current line and
3804 displays it in the minibuffer. The command also highlights the anchor
3805 position(s).
3806 @end table
3807
3808 Running this command on line 4 of this example, we'd see in the echo
3809 area@footnote{With a universal argument (i.e. @kbd{C-u C-c C-s}) the
3810 analysis is inserted into the buffer as a comment on the current
3811 line.}:
3812
3813 @example
3814 ((statement 35))
3815 @end example
3816
3817 @noindent
3818 and the @samp{i} of @code{int} on line 3 would be highlighted. This
3819 tells us that the line is a statement and it is indented relative to
3820 buffer position 35, the highlighted position. If you were to move
3821 point to line 3 and hit @kbd{C-c C-s}, you would see:
3822
3823 @example
3824 ((defun-block-intro 29))
3825 @end example
3826
3827 @noindent
3828 This indicates that the @samp{int} line is the first statement in a top
3829 level function block, and is indented relative to buffer position 29,
3830 which is the brace just after the function header.
3831
3832 Here's another example:
3833
3834 @example
3835 1: int add( int val, int incr, int doit )
3836 2: @{
3837 3: if( doit )
3838 4: @{
3839 5: return( val + incr );
3840 6: @}
3841 7: return( val );
3842 8: @}
3843 @end example
3844
3845 @noindent
3846 Hitting @kbd{C-c C-s} on line 4 gives us:
3847
3848 @example
3849 ((substatement-open 46))
3850 @end example
3851
3852 @cindex substatement
3853 @cindex substatement block
3854 @noindent
3855 which tells us that this is a brace that @emph{opens} a substatement
3856 block. @footnote{A @dfn{substatement} is the line after a
3857 conditional statement, such as @code{if}, @code{else}, @code{while},
3858 @code{do}, @code{switch}, etc. A @dfn{substatement
3859 block} is a brace block following one of these conditional statements.}
3860
3861 @cindex comment-only line
3862 Syntactic contexts can contain more than one element, and syntactic
3863 elements need not have anchor positions. The most common example of
3864 this is a @dfn{comment-only line}:
3865
3866 @example
3867 1: void draw_list( List<Drawables>& drawables )
3868 2: @{
3869 3: // call the virtual draw() method on each element in list
3870 4: for( int i=0; i < drawables.count(), ++i )
3871 5: @{
3872 6: drawables[i].draw();
3873 7: @}
3874 8: @}
3875 @end example
3876
3877 @noindent
3878 Hitting @kbd{C-c C-s} on line 3 of this example gives:
3879
3880 @example
3881 ((comment-intro) (defun-block-intro 46))
3882 @end example
3883
3884 @noindent
3885 and you can see that the syntactic context contains two syntactic
3886 elements. Notice that the first element, @samp{(comment-intro)}, has no
3887 anchor position.
3888
3889
3890 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3891 @node Syntactic Symbols, Indentation Calculation, Syntactic Analysis, Indentation Engine Basics
3892 @comment node-name, next, previous, up
3893 @section Syntactic Symbols
3894 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3895
3896 @cindex syntactic symbols, brief list
3897 @vindex c-offsets-alist
3898 @vindex offsets-alist (c-)
3899 This section is a complete list of the syntactic symbols which appear
3900 in the @code{c-offsets-alist} style variable, along with brief
3901 descriptions. The previous section (@pxref{Syntactic Analysis})
3902 states what syntactic symbols are and how the indentation engine uses
3903 them.
3904
3905 More detailed descriptions of these symbols, together with snippets of
3906 source code to which they apply, appear in the examples in the
3907 subsections below. Note that, in the interests of brevity, the anchor
3908 position associated with most syntactic symbols is @emph{not}
3909 specified. In cases of doubt, type @kbd{C-c C-s} on a pertinent
3910 line---this highlights the anchor position.
3911
3912 @ssindex -open symbols
3913 @ssindex -close symbols
3914 @ssindex -block-intro symbols
3915 The syntactic symbols which indicate brace constructs follow a general
3916 naming convention. When a line begins with an open or close brace,
3917 its syntactic symbol will contain the suffix @code{-open} or
3918 @code{-close} respectively. The first line within the brace block
3919 construct will contain the suffix @code{-block-intro}.
3920
3921 @ssindex -intro symbols
3922 @ssindex -cont symbols
3923 In constructs which can span several lines, a distinction is usually
3924 made between the first line that introduces the construct and the
3925 lines that continue it. The syntactic symbols that indicate these
3926 lines will contain the suffixes @code{-intro} or @code{-cont}
3927 respectively.
3928
3929 The best way to understand how all this works is by looking at some
3930 examples. Remember that you can see the syntax of any source code
3931 line by using @kbd{C-c C-s}.
3932
3933 @table @code
3934 @item string
3935 Inside a multiline string. @ref{Literal Symbols}.
3936 @item c
3937 Inside a multiline C style block comment. @ref{Literal Symbols}.
3938 @item defun-open
3939 Brace that opens a top-level function definition. @ref{Function
3940 Symbols}.
3941 @item defun-close
3942 Brace that closes a top-level function definition. @ref{Function
3943 Symbols}.
3944 @item defun-block-intro
3945 The first line in a top-level defun. @ref{Function Symbols}.
3946 @item class-open
3947 Brace that opens a class definition. @ref{Class Symbols}.
3948 @item class-close
3949 Brace that closes a class definition. @ref{Class Symbols}.
3950 @item inline-open
3951 Brace that opens an in-class inline method. @ref{Class Symbols}.
3952 @item inline-close
3953 Brace that closes an in-class inline method. @ref{Class Symbols}.
3954 @item func-decl-cont
3955 The region between a function definition's argument list and the
3956 function opening brace (excluding K&R argument declarations). In C,
3957 you cannot put anything but whitespace and comments in this region,
3958 however in C++ and Java, @code{throws} declarations and other things
3959 can appear here. @ref{Literal Symbols}. @c @emph{FIXME!!! Can it not
3960 @c go somewhere better?}
3961 @item knr-argdecl-intro
3962 First line of a K&R C argument declaration. @ref{K&R Symbols}.
3963 @item knr-argdecl
3964 Subsequent lines in a K&R C argument declaration. @ref{K&R Symbols}.
3965 @item topmost-intro
3966 The first line in a ``topmost'' definition. @ref{Function Symbols}.
3967 @item topmost-intro-cont
3968 Topmost definition continuation lines. This is only used in the parts
3969 that aren't covered by other symbols such as @code{func-decl-cont} and
3970 @code{knr-argdecl}. @ref{Function Symbols}.
3971 @item member-init-intro
3972 First line in a member initialization list. @ref{Class Symbols}.
3973 @item member-init-cont
3974 Subsequent member initialization list lines. @ref{Class Symbols}.
3975 @item inher-intro
3976 First line of a multiple inheritance list. @ref{Class Symbols}.
3977 @item inher-cont
3978 Subsequent multiple inheritance lines. @ref{Class Symbols}.
3979 @item block-open
3980 Statement block open brace. @ref{Literal Symbols}.
3981 @item block-close
3982 Statement block close brace. @ref{Conditional Construct Symbols}.
3983 @item brace-list-open
3984 Open brace of an enum or static array list. @ref{Brace List Symbols}.
3985 @item brace-list-close
3986 Close brace of an enum or static array list. @ref{Brace List Symbols}.
3987 @item brace-list-intro
3988 First line in an enum or static array list. @ref{Brace List Symbols}.
3989 @item brace-list-entry
3990 Subsequent lines in an enum or static array list. @ref{Brace List
3991 Symbols}.
3992 @item brace-entry-open
3993 Subsequent lines in an enum or static array list where the line begins
3994 with an open brace. @ref{Brace List Symbols}.
3995 @item statement
3996 A statement. @ref{Function Symbols}.
3997 @item statement-cont
3998 A continuation of a statement. @ref{Function Symbols}.
3999 @item statement-block-intro
4000 The first line in a new statement block. @ref{Conditional Construct
4001 Symbols}.
4002 @item statement-case-intro
4003 The first line in a case block. @ref{Switch Statement Symbols}.
4004 @item statement-case-open
4005 The first line in a case block that starts with a brace. @ref{Switch
4006 Statement Symbols}.
4007 @item substatement
4008 The first line after a conditional or loop construct.
4009 @ref{Conditional Construct Symbols}.
4010 @item substatement-open
4011 The brace that opens a substatement block. @ref{Conditional Construct
4012 Symbols}.
4013 @item substatement-label
4014 The first line after a conditional or loop construct if it's a label.
4015 @ref{Conditional Construct Symbols}.
4016 @item case-label
4017 A label in a @code{switch} block. @ref{Switch Statement Symbols}.
4018 @item access-label
4019 C++ access control label. @ref{Class Symbols}.
4020 @item label
4021 Any other label. @ref{Literal Symbols}.
4022 @item do-while-closure
4023 The @code{while} line that ends a @code{do}-@code{while} construct.
4024 @ref{Conditional Construct Symbols}.
4025 @item else-clause
4026 The @code{else} line of an @code{if}-@code{else} construct.
4027 @ref{Conditional Construct Symbols}.
4028 @item catch-clause
4029 The @code{catch} or @code{finally} (in Java) line of a
4030 @code{try}-@code{catch} construct. @ref{Conditional Construct
4031 Symbols}.
4032 @item comment-intro
4033 A line containing only a comment introduction. @ref{Literal Symbols}.
4034 @item arglist-intro
4035 The first line in an argument list. @ref{Paren List Symbols}.
4036 @item arglist-cont
4037 Subsequent argument list lines when no arguments follow on the same
4038 line as the arglist opening paren. @ref{Paren List Symbols}.
4039 @item arglist-cont-nonempty
4040 Subsequent argument list lines when at least one argument follows on
4041 the same line as the arglist opening paren. @ref{Paren List Symbols}.
4042 @item arglist-close
4043 The solo close paren of an argument list. @ref{Paren List Symbols}.
4044 @item stream-op
4045 Lines continuing a stream operator (C++ only). @ref{Literal
4046 Symbols}. @c @emph{FIXME!!! Can this not be moved somewhere better?}
4047 @item inclass
4048 The line is nested inside a class definition. @ref{Class Symbols}.
4049 @item cpp-macro
4050 The start of a preprocessor macro definition. @ref{Literal Symbols}.
4051 @item cpp-define-intro
4052 The first line inside a multiline preprocessor macro if
4053 @code{c-syntactic-indentation-in-macros} is set. @ref{Multiline Macro
4054 Symbols}.
4055 @item cpp-macro-cont
4056 All lines inside multiline preprocessor macros if
4057 @code{c-syntactic-indentation-in-macros} is @code{nil}.
4058 @ref{Multiline Macro Symbols}.
4059 @item friend
4060 A C++ friend declaration. @ref{Class Symbols}.
4061 @item objc-method-intro
4062 The first line of an Objective-C method definition. @ref{Objective-C
4063 Method Symbols}.
4064 @item objc-method-args-cont
4065 Lines continuing an Objective-C method definition. @ref{Objective-C
4066 Method Symbols}.
4067 @item objc-method-call-cont
4068 Lines continuing an Objective-C method call. @ref{Objective-C Method
4069 Symbols}.
4070 @item extern-lang-open
4071 Brace that opens an @code{extern} block (e.g. @code{extern "C"
4072 @{...@}}). @ref{External Scope Symbols}.
4073 @item extern-lang-close
4074 Brace that closes an @code{extern} block. @ref{External Scope
4075 Symbols}.
4076 @item inextern-lang
4077 Analogous to @code{inclass} syntactic symbol, but used inside
4078 @code{extern} blocks. @ref{External Scope Symbols}.
4079 @item namespace-open
4080 @itemx namespace-close
4081 @itemx innamespace
4082 These are analogous to the three @code{extern-lang} symbols above, but
4083 are returned for C++ namespace blocks. @ref{External Scope Symbols}.
4084 @item module-open
4085 @itemx module-close
4086 @itemx inmodule
4087 Analogous to the above, but for CORBA IDL @code{module} blocks.
4088 @ref{External Scope Symbols}.
4089 @item composition-open
4090 @itemx composition-close
4091 @itemx incomposition
4092 Analogous to the above, but for CORBA CIDL @code{composition} blocks.
4093 @ref{External Scope Symbols}.
4094 @item template-args-cont
4095 C++ template argument list continuations. @ref{Class Symbols}.
4096 @item inlambda
4097 Analogous to @code{inclass} syntactic symbol, but used inside lambda
4098 (i.e. anonymous) functions. Only used in Pike mode. @ref{Statement
4099 Block Symbols}.
4100 @item lambda-intro-cont
4101 Lines continuing the header of a lambda function, i.e. between the
4102 @code{lambda} keyword and the function body. Only used in Pike mode.
4103 @ref{Statement Block Symbols}.
4104 @item inexpr-statement
4105 A statement block inside an expression. The gcc C and C++ extension
4106 for this is recognized. It's also used for the special functions that
4107 take a statement block as an argument in Pike. @ref{Statement Block
4108 Symbols}.
4109 @item inexpr-class
4110 A class definition inside an expression. This is used for anonymous
4111 classes in Java. It's also used for anonymous array initializers in
4112 Java. @ref{Anonymous Class Symbol}.
4113 @end table
4114
4115 @menu
4116 * Function Symbols::
4117 * Class Symbols::
4118 * Conditional Construct Symbols::
4119 * Switch Statement Symbols::
4120 * Brace List Symbols::
4121 * External Scope Symbols::
4122 * Paren List Symbols::
4123 * Literal Symbols::
4124 * Multiline Macro Symbols::
4125 * Objective-C Method Symbols::
4126 * Anonymous Class Symbol::
4127 * Statement Block Symbols::
4128 * K&R Symbols::
4129 @end menu
4130
4131 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4132 @node Function Symbols, Class Symbols, Syntactic Symbols, Syntactic Symbols
4133 @comment node-name, next, previous, up
4134 @subsection Function Symbols
4135 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4136
4137 This example shows a typical function declaration.
4138
4139 @example
4140 1: void
4141 2: swap( int& a, int& b )
4142 3: @{
4143 4: int tmp = a;
4144 5: a = b;
4145 6: b = tmp;
4146 7: int ignored =
4147 8: a + b;
4148 9: @}
4149 @end example
4150
4151 @ssindex topmost-intro
4152 @ssindex topmost-intro-cont
4153 @ssindex defun-open
4154 @ssindex defun-close
4155 @ssindex defun-block-intro
4156 Line 1 shows a @code{topmost-intro} since it is the first line that
4157 introduces a top-level construct. Line 2 is a continuation of the
4158 top-level construct introduction so it has the syntax
4159 @code{topmost-intro-cont}. Line 3 shows a @code{defun-open} since it is
4160 the brace that opens a top-level function definition. Line 9 is the
4161 corresponding
4162 @code{defun-close} since it contains the brace that closes the top-level
4163 function definition. Line 4 is a @code{defun-block-intro}, i.e. it is
4164 the first line of a brace-block, enclosed in a
4165 top-level function definition.
4166
4167 @ssindex statement
4168 @ssindex statement-cont
4169 Lines 5, 6, and 7 are all given @code{statement} syntax since there
4170 isn't much special about them. Note however that line 8 is given
4171 @code{statement-cont} syntax since it continues the statement begun
4172 on the previous line.
4173
4174 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4175 @node Class Symbols, Conditional Construct Symbols, Function Symbols, Syntactic Symbols
4176 @comment node-name, next, previous, up
4177 @subsection Class related Symbols
4178 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4179
4180 Here's an example which illustrates some C++ class syntactic symbols:
4181
4182 @example
4183 1: class Bass
4184 2: : public Guitar,
4185 3: public Amplifiable
4186 4: @{
4187 5: public:
4188 6: Bass()
4189 7: : eString( new BassString( 0.105 )),
4190 8: aString( new BassString( 0.085 )),
4191 9: dString( new BassString( 0.065 )),
4192 10: gString( new BassString( 0.045 ))
4193 11: @{
4194 12: eString.tune( 'E' );
4195 13: aString.tune( 'A' );
4196 14: dString.tune( 'D' );
4197 15: gString.tune( 'G' );
4198 16: @}
4199 17: friend class Luthier;
4200 18: @};
4201 @end example
4202
4203 @ssindex class-open
4204 @ssindex class-close
4205 As in the previous example, line 1 has the @code{topmost-intro} syntax.
4206 Here however, the brace that opens a C++ class definition on line 4 is
4207 assigned the @code{class-open} syntax. Note that in C++, classes,
4208 structs, and unions are essentially equivalent syntactically (and are
4209 very similar semantically), so replacing the @code{class} keyword in the
4210 example above with @code{struct} or @code{union} would still result in a
4211 syntax of @code{class-open} for line 4 @footnote{This is the case even
4212 for C and Objective-C. For consistency, structs in all supported
4213 languages are syntactically equivalent to classes. Note however that
4214 the keyword @code{class} is meaningless in C and Objective-C.}.
4215 Similarly, line 18 is assigned @code{class-close} syntax.
4216
4217 @ssindex inher-intro
4218 @ssindex inher-cont
4219 Line 2 introduces the inheritance list for the class so it is assigned
4220 the @code{inher-intro} syntax, and line 3, which continues the
4221 inheritance list is given @code{inher-cont} syntax.
4222
4223 @ssindex access-label
4224 @ssindex inclass
4225 Hitting @kbd{C-c C-s} on line 5 shows the following analysis:
4226
4227 @example
4228 ((inclass 58) (access-label 58))
4229 @end example
4230
4231 @noindent
4232 The primary syntactic symbol for this line is @code{access-label} as
4233 this a label keyword that specifies access protection in C++. However,
4234 because this line is also a top-level construct inside a class
4235 definition, the analysis actually shows two syntactic symbols. The
4236 other syntactic symbol assigned to this line is @code{inclass}.
4237 Similarly, line 6 is given both @code{inclass} and @code{topmost-intro}
4238 syntax:
4239
4240 @example
4241 ((inclass 58) (topmost-intro 60))
4242 @end example
4243
4244 @ssindex member-init-intro
4245 @ssindex member-init-cont
4246 Line 7 introduces a C++ member initialization list and as such is given
4247 @code{member-init-intro} syntax. Note that in this case it is
4248 @emph{not} assigned @code{inclass} since this is not considered a
4249 top-level construct. Lines 8 through 10 are all assigned
4250 @code{member-init-cont} since they continue the member initialization
4251 list started on line 7.
4252
4253 @cindex in-class inline methods
4254 @ssindex inline-open
4255 @ssindex inline-close
4256 Line 11's analysis is a bit more complicated:
4257
4258 @example
4259 ((inclass 58) (inline-open))
4260 @end example
4261
4262 This line is assigned a syntax of both @code{inline-open} and
4263 @code{inclass} because it opens an @dfn{in-class} C++ inline method
4264 definition. This is distinct from, but related to, the C++ notion of an
4265 inline function in that its definition occurs inside an enclosing class
4266 definition, which in C++ implies that the function should be inlined.
4267 However, if the definition of the @code{Bass} constructor appeared
4268 outside the class definition, the construct would be given the
4269 @code{defun-open} syntax, even if the keyword @code{inline} appeared
4270 before the method name, as in:
4271
4272 @example
4273 1: class Bass
4274 2: : public Guitar,
4275 3: public Amplifiable
4276 4: @{
4277 5: public:
4278 6: Bass();
4279 7: @};
4280 8:
4281 9: inline
4282 10: Bass::Bass()
4283 11: : eString( new BassString( 0.105 )),
4284 12: aString( new BassString( 0.085 )),
4285 13: dString( new BassString( 0.065 )),
4286 14: gString( new BassString( 0.045 ))
4287 15: @{
4288 16: eString.tune( 'E' );
4289 17: aString.tune( 'A' );
4290 18: dString.tune( 'D' );
4291 19: gString.tune( 'G' );
4292 20: @}
4293 @end example
4294
4295 @ssindex friend
4296 Returning to the previous example, line 16 is given @code{inline-close}
4297 syntax, while line 12 is given @code{defun-block-open} syntax, and lines
4298 13 through 15 are all given @code{statement} syntax. Line 17 is
4299 interesting in that its syntactic analysis list contains three
4300 elements:
4301
4302 @example
4303 ((inclass 58) (topmost-intro 380) (friend))
4304 @end example
4305
4306 The @code{friend} and @code{inline-open} syntactic symbols are
4307 modifiers that do not have anchor positions.
4308
4309 @ssindex template-args-cont
4310 Template definitions introduce yet another syntactic symbol:
4311
4312 @example
4313 1: ThingManager <int,
4314 2: Framework::Callback *,
4315 3: Mutex> framework_callbacks;
4316 @end example
4317
4318 Here, line 1 is analyzed as a @code{topmost-intro}, but lines 2 and 3
4319 are both analyzed as @code{template-args-cont} lines.
4320
4321 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4322 @node Conditional Construct Symbols, Switch Statement Symbols, Class Symbols, Syntactic Symbols
4323 @comment node-name, next, previous, up
4324 @subsection Conditional Construct Symbols
4325 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4326
4327 Here is a (totally contrived) example which illustrates how syntax is
4328 assigned to various conditional constructs:
4329
4330 @example
4331 1: void spam( int index )
4332 2: @{
4333 3: for( int i=0; i<index; i++ )
4334 4: @{
4335 5: if( i == 10 )
4336 6: do_something_special();
4337 7: else
4338 8: silly_label:
4339 9: do_something( i );
4340 10: @}
4341 11: do @{
4342 12: another_thing( i-- );
4343 13: @}
4344 14: while( i > 0 );
4345 15: @}
4346 @end example
4347
4348 Only the lines that illustrate new syntactic symbols will be discussed.
4349
4350 @ssindex substatement-open
4351 @ssindex statement-block-intro
4352 @ssindex block-close
4353 Line 4 has a brace which opens a conditional's substatement block. It
4354 is thus assigned @code{substatement-open} syntax, and since line 5 is
4355 the first line in the substatement block, it is assigned
4356 @code{statement-block-intro} syntax. Line 10 contains the brace
4357 that closes the inner substatement block, and is therefore given the
4358 syntax @code{block-close}@footnote{@code{block-open} is used only for
4359 ``free-standing'' blocks, and is somewhat rare (@pxref{Literal
4360 Symbols} for an example.)}. Line 13 is treated the same way.
4361
4362 @ssindex substatement
4363 Lines 6 and 9 are also substatements of conditionals, but since they
4364 don't start blocks they are given @code{substatement} syntax
4365 instead of @code{substatement-open}.
4366
4367 @ssindex substatement-label
4368 Line 8 contains a label, which is normally given @code{label} syntax.
4369 This one is however a bit special since it's between a conditional and
4370 its substatement. It's analyzed as @code{substatement-label} to let you
4371 handle this rather odd case differently from normal labels.
4372
4373 @ssindex else-clause
4374 @ssindex catch-clause
4375 Line 7 start with an @code{else} that matches the @code{if} statement on
4376 line 5. It is therefore given the @code{else-clause} syntax and is
4377 anchored on the matching @code{if}. The @code{try}-@code{catch}
4378 constructs in C++ and Java are treated this way too, except that
4379 @code{catch} and (in Java) @code{finally}, are marked with
4380 @code{catch-clause}.
4381
4382 @ssindex do-while-closure
4383 The @code{while} construct on line 14 that closes a @code{do}
4384 conditional is given the special syntax @code{do-while-closure} if it
4385 appears on a line by itself. Note that if the @code{while} appeared on
4386 the same line as the preceding close brace, that line would still have
4387 @code{block-close} syntax.
4388
4389 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4390 @node Switch Statement Symbols, Brace List Symbols, Conditional Construct Symbols, Syntactic Symbols
4391 @comment node-name, next, previous, up
4392 @subsection Switch Statement Symbols
4393 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4394
4395 Switch statements have their own set of syntactic symbols. Here's an
4396 example:
4397
4398 @example
4399 1: void spam( enum Ingredient i )
4400 2: @{
4401 3: switch( i ) @{
4402 4: case Ham:
4403 5: be_a_pig();
4404 6: break;
4405 7: case Salt:
4406 8: drink_some_water();
4407 9: break;
4408 10: default:
4409 11: @{
4410 12: what_is_it();
4411 13: break;
4412 14: @}
4413 15: @}
4414 14: @}
4415 @end example
4416
4417 @ssindex case-label
4418 @ssindex statement-case-intro
4419 @ssindex statement-case-open
4420 Here, lines 4, 7, and 10 are all assigned @code{case-label} syntax,
4421 while lines 5 and 8 are assigned @code{statement-case-intro}. Line 11
4422 is treated slightly differently since it contains a brace that opens a
4423 block --- it is given @code{statement-case-open} syntax.
4424
4425 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4426 @node Brace List Symbols, External Scope Symbols, Switch Statement Symbols, Syntactic Symbols
4427 @comment node-name, next, previous, up
4428 @subsection Brace List Symbols
4429 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4430
4431 @cindex brace lists
4432 There are a set of syntactic symbols that are used to recognize
4433 constructs inside of brace lists. A brace list is defined as an
4434 @code{enum} or aggregate initializer list, such as might statically
4435 initialize an array of structs. The three special aggregate constructs
4436 in Pike, @code{(@{ @})}, @code{([ ])} and @code{(< >)}, are treated as
4437 brace lists too. An example:
4438
4439 @example
4440 1: static char* ingredients[] =
4441 2: @{
4442 3: "Ham",
4443 4: "Salt",
4444 5: NULL
4445 6: @};
4446 @end example
4447
4448 @ssindex brace-list-open
4449 @ssindex brace-list-intro
4450 @ssindex brace-list-close
4451 @ssindex brace-list-entry
4452 Following convention, line 2 in this example is assigned
4453 @code{brace-list-open} syntax, and line 3 is assigned
4454 @code{brace-list-intro} syntax. Likewise, line 6 is assigned
4455 @code{brace-list-close} syntax. Lines 4 and 5 however, are assigned
4456 @code{brace-list-entry} syntax, as would all subsequent lines in this
4457 initializer list.
4458
4459 @ssindex brace-entry-open
4460 Your static initializer might be initializing nested structures, for
4461 example:
4462
4463 @example
4464 1: struct intpairs[] =
4465 2: @{
4466 3: @{ 1, 2 @},
4467 4: @{
4468 5: 3,
4469 6: 4
4470 7: @}
4471 8: @{ 1,
4472 9: 2 @},
4473 10: @{ 3, 4 @}
4474 11: @};
4475 @end example
4476
4477 Here, you've already seen the analysis of lines 1, 2, 3, and 11. On
4478 line 4, things get interesting; this line is assigned
4479 @code{brace-entry-open} syntactic symbol because it's a bracelist entry
4480 line that starts with an open brace. Lines 5 and 6 (and line 9) are
4481 pretty standard, and line 7 is a @code{brace-list-close} as you'd
4482 expect. Once again, line 8 is assigned as @code{brace-entry-open} as is
4483 line 10.
4484
4485 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4486 @node External Scope Symbols, Paren List Symbols, Brace List Symbols, Syntactic Symbols
4487 @comment node-name, next, previous, up
4488 @subsection External Scope Symbols
4489 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4490
4491 External language definition blocks also have their own syntactic
4492 symbols. In this example:
4493
4494 @example
4495 1: extern "C"
4496 2: @{
4497 3: int thing_one( int );
4498 4: int thing_two( double );
4499 5: @}
4500 @end example
4501
4502 @ssindex extern-lang-open
4503 @ssindex extern-lang-close
4504 @ssindex inextern-lang
4505 @ssindex inclass
4506 @noindent
4507 line 2 is given the @code{extern-lang-open} syntax, while line 5 is given
4508 the @code{extern-lang-close} syntax. The analysis for line 3 yields:
4509
4510 @example
4511 ((inextern-lang) (topmost-intro 14))
4512 @end example
4513
4514 @noindent
4515 where @code{inextern-lang} is a modifier similar in purpose to
4516 @code{inclass}.
4517
4518 There are various other top level blocks like @code{extern}, and they
4519 are all treated in the same way except that the symbols are named after
4520 the keyword that introduces the block. E.g. C++ namespace blocks get
4521 the three symbols @code{namespace-open}, @code{namespace-close} and
4522 @code{innamespace}. The currently recognized top level blocks are:
4523
4524 @table @asis
4525 @item @code{extern-lang-open}, @code{extern-lang-close}, @code{inextern-lang}
4526 @code{extern} blocks in C and C++.@footnote{These should logically be
4527 named @code{extern-open}, @code{extern-close} and @code{inextern}, but
4528 that isn't the case for historical reasons.}
4529
4530 @item @code{namespace-open}, @code{namespace-close}, @code{innamespace}
4531 @ssindex namespace-open
4532 @ssindex namespace-close
4533 @ssindex innamespace
4534 @code{namespace} blocks in C++.
4535
4536 @item @code{module-open}, @code{module-close}, @code{inmodule}
4537 @ssindex module-open
4538 @ssindex module-close
4539 @ssindex inmodule
4540 @code{module} blocks in CORBA IDL.
4541
4542 @item @code{composition-open}, @code{composition-close}, @code{incomposition}
4543 @ssindex composition-open
4544 @ssindex composition-close
4545 @ssindex incomposition
4546 @code{composition} blocks in CORBA CIDL.
4547 @end table
4548
4549 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4550 @node Paren List Symbols, Literal Symbols, External Scope Symbols, Syntactic Symbols
4551 @comment node-name, next, previous, up
4552 @subsection Parenthesis (Argument) List Symbols
4553 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4554
4555 A number of syntactic symbols are associated with parenthesis lists,
4556 a.k.a argument lists, as found in function declarations and function
4557 calls. This example illustrates these:
4558
4559 @example
4560 1: void a_function( int line1,
4561 2: int line2 );
4562 3:
4563 4: void a_longer_function(
4564 5: int line1,
4565 6: int line2
4566 7: );
4567 8:
4568 9: void call_them( int line1, int line2 )
4569 10: @{
4570 11: a_function(
4571 12: line1,
4572 13: line2
4573 14: );
4574 15:
4575 16: a_longer_function( line1,
4576 17: line2 );
4577 18: @}
4578 @end example
4579
4580 @ssindex arglist-intro
4581 @ssindex arglist-close
4582 Lines 5 and 12 are assigned @code{arglist-intro} syntax since they are
4583 the first line following the open parenthesis, and lines 7 and 14 are
4584 assigned @code{arglist-close} syntax since they contain the parenthesis
4585 that closes the argument list.
4586
4587 @ssindex arglist-cont-nonempty
4588 @ssindex arglist-cont
4589 Lines that continue argument lists can be assigned one of two syntactic
4590 symbols. For example, Lines 2 and 17
4591 are assigned @code{arglist-cont-nonempty} syntax. What this means
4592 is that they continue an argument list, but that the line containing the
4593 parenthesis that opens the list is @emph{not empty} following the open
4594 parenthesis. Contrast this against lines 6 and 13 which are assigned
4595 @code{arglist-cont} syntax. This is because the parenthesis that opens
4596 their argument lists is the last character on that line.
4597
4598 Syntactic elements with @code{arglist-intro},
4599 @code{arglist-cont-nonempty}, and @code{arglist-close} contain two
4600 buffer positions: the anchor position (the beginning of the
4601 declaration or statement) and the position of the open parenthesis.
4602 The latter position can be used in a line-up function (@pxref{Line-Up
4603 Functions}).
4604
4605 Note that there is no @code{arglist-open} syntax. This is because any
4606 parenthesis that opens an argument list, appearing on a separate line,
4607 is assigned the @code{statement-cont} syntax instead.
4608
4609 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4610 @node Literal Symbols, Multiline Macro Symbols, Paren List Symbols, Syntactic Symbols
4611 @comment node-name, next, previous, up
4612 @subsection Comment String Label and Macro Symbols
4613 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4614
4615 A few miscellaneous syntactic symbols that haven't been previously
4616 covered are illustrated by this C++ example:
4617
4618 @example
4619 1: void Bass::play( int volume )
4620 2: const
4621 3: @{
4622 4: /* this line starts a multiline
4623 5: * comment. This line should get `c' syntax */
4624 6:
4625 7: char* a_multiline_string = "This line starts a multiline \
4626 8: string. This line should get `string' syntax.";
4627 9:
4628 10: note:
4629 11: @{
4630 12: #ifdef LOCK
4631 13: Lock acquire();
4632 14: #endif // LOCK
4633 15: slap_pop();
4634 16: cout << "I played "
4635 17: << "a note\n";
4636 18: @}
4637 19: @}
4638 @end example
4639
4640 The lines to note in this example include:
4641
4642 @itemize @bullet
4643 @item
4644 @ssindex func-decl-cont
4645 Line 2 is assigned the @code{func-decl-cont} syntax.
4646
4647 @item
4648 @ssindex comment-intro
4649 Line 4 is assigned both @code{defun-block-intro} @emph{and}
4650 @code{comment-intro} syntax. A syntactic element with
4651 @code{comment-intro} has no anchor point --- It is always accompanied
4652 by another syntactic element which does have one.
4653
4654 @item
4655 @ssindex c
4656 Line 5 is assigned @code{c} syntax.
4657
4658 @item
4659 @cindex syntactic whitespace
4660 Line 6 which, even though it contains nothing but whitespace, is
4661 assigned @code{defun-block-intro}. Note that the appearance of the
4662 comment on lines 4 and 5 do not cause line 6 to be assigned
4663 @code{statement} syntax because comments are considered to be
4664 @dfn{syntactic whitespace}, which are ignored when analyzing
4665 code.
4666
4667 @item
4668 @ssindex string
4669 Line 8 is assigned @code{string} syntax.
4670
4671 @item
4672 @ssindex label
4673 Line 10 is assigned @code{label} syntax.
4674
4675 @item
4676 @ssindex block-open
4677 Line 11 is assigned @code{block-open} as well as @code{statement}
4678 syntax. A @code{block-open} syntactic element doesn't have an anchor
4679 position, since it always appears with another syntactic element which
4680 does have one.
4681
4682 @item
4683 @ssindex cpp-macro
4684 Lines 12 and 14 are assigned @code{cpp-macro} syntax in addition to the
4685 normal syntactic symbols (@code{statement-block-intro} and
4686 @code{statement}, respectively). Normally @code{cpp-macro} is
4687 configured to cancel out the normal syntactic context to make all
4688 preprocessor directives stick to the first column, but that's easily
4689 changed if you want preprocessor directives to be indented like the rest
4690 of the code. Like @code{comment-intro}, a syntactic element with
4691 @code{cpp-macro} doesn't contain an anchor position.
4692
4693 @item
4694 @ssindex stream-op
4695 Line 17 is assigned @code{stream-op} syntax.
4696 @end itemize
4697
4698 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4699 @node Multiline Macro Symbols, Objective-C Method Symbols, Literal Symbols, Syntactic Symbols
4700 @comment node-name, next, previous, up
4701 @subsection Multiline Macro Symbols
4702 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4703
4704 @cindex multiline macros
4705 @cindex syntactic whitespace
4706 @ssindex cpp-define-intro
4707 @ssindex cpp-macro-cont
4708 Multiline preprocessor macro definitions are normally handled just like
4709 other code, i.e. the lines inside them are indented according to the
4710 syntactic analysis of the preceding lines inside the macro. The first
4711 line inside a macro definition (i.e. the line after the starting line of
4712 the cpp directive itself) gets @code{cpp-define-intro}. In this example:
4713
4714 @example
4715 1: #define LIST_LOOP(cons, listp) \
4716 2: for (cons = listp; !NILP (cons); cons = XCDR (cons)) \
4717 3: if (!CONSP (cons)) \
4718 4: signal_error ("Invalid list format", listp); \
4719 5: else
4720 @end example
4721
4722 @noindent
4723 line 1 is given the syntactic symbol @code{cpp-macro}. The first line
4724 of a cpp directive is always given that symbol. Line 2 is given
4725 @code{cpp-define-intro}, so that you can give the macro body as a whole
4726 some extra indentation. Lines 3 through 5 are then analyzed as normal
4727 code, i.e. @code{substatement} on lines 3 and 4, and @code{else-clause}
4728 on line 5.
4729
4730 The syntactic analysis inside macros can be turned off with
4731 @code{c-syntactic-indentation-in-macros} (@pxref{Custom Macros}). In
4732 that case, lines 2 through 5 would all be given @code{cpp-macro-cont}
4733 with an anchor position pointing to the @code{#} which starts the cpp
4734 directive@footnote{This is how @ccmode{} 5.28 and earlier analyzed
4735 macros.}.
4736
4737 @xref{Custom Macros}, for more info about the treatment of macros.
4738
4739 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4740 @node Objective-C Method Symbols, Anonymous Class Symbol, Multiline Macro Symbols, Syntactic Symbols
4741 @comment node-name, next, previous, up
4742 @subsection Objective-C Method Symbols
4743 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4744
4745 In Objective-C buffers, there are three additional syntactic symbols
4746 assigned to various message calling constructs. Here's an example
4747 illustrating these:
4748
4749 @example
4750 1: - (void)setDelegate:anObject
4751 2: withStuff:stuff
4752 3: @{
4753 4: [delegate masterWillRebind:self
4754 5: toDelegate:anObject
4755 6: withExtraStuff:stuff];
4756 7: @}
4757 @end example
4758
4759 @ssindex objc-method-intro
4760 @ssindex objc-method-args-cont
4761 @ssindex objc-method-call-cont
4762 Here, line 1 is assigned @code{objc-method-intro} syntax, and line 2 is
4763 assigned @code{objc-method-args-cont} syntax. Lines 5 and 6 are both
4764 assigned @code{objc-method-call-cont} syntax.
4765
4766 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4767 @node Anonymous Class Symbol, Statement Block Symbols, Objective-C Method Symbols, Syntactic Symbols
4768 @comment node-name, next, previous, up
4769 @subsection Anonymous Class Symbol (Java)
4770 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4771
4772 Java has a concept of anonymous classes which can look something like
4773 this:
4774
4775 @example
4776 1: public void watch(Observable o) @{
4777 2: o.addObserver(new Observer() @{
4778 3: public void update(Observable o, Object arg) @{
4779 4: history.addElement(arg);
4780 5: @}
4781 6: @});
4782 7: @}
4783 @end example
4784
4785 @ssindex inexpr-class
4786 The brace following the @code{new} operator opens the anonymous class.
4787 Lines 3 and 6 are assigned the @code{inexpr-class} syntax, besides the
4788 @code{inclass} symbol used in normal classes. Thus, the class will be
4789 indented just like a normal class, with the added indentation given to
4790 @code{inexpr-class}. An @code{inexpr-class} syntactic element doesn't
4791 have an anchor position.
4792
4793 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4794 @node Statement Block Symbols, K&R Symbols, Anonymous Class Symbol, Syntactic Symbols
4795 @comment node-name, next, previous, up
4796 @subsection Statement Block Symbols
4797 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4798
4799 There are a few occasions where a statement block might be used inside
4800 an expression. One is in C or C++ code using the gcc extension for
4801 this, e.g:
4802
4803 @example
4804 1: int res = (@{
4805 2: int y = foo (); int z;
4806 3: if (y > 0) z = y; else z = - y;
4807 4: z;
4808 5: @});
4809 @end example
4810
4811 @ssindex inexpr-statement
4812 Lines 2 and 5 get the @code{inexpr-statement} syntax, besides the
4813 symbols they'd get in a normal block. Therefore, the indentation put on
4814 @code{inexpr-statement} is added to the normal statement block
4815 indentation. An @code{inexpr-statement} syntactic element doesn't
4816 contain an anchor position.
4817
4818 In Pike code, there are a few other situations where blocks occur inside
4819 statements, as illustrated here:
4820
4821 @example
4822 1: array itgob()
4823 2: @{
4824 3: string s = map (backtrace()[-2][3..],
4825 4: lambda
4826 5: (mixed arg)
4827 6: @{
4828 7: return sprintf ("%t", arg);
4829 8: @}) * ", " + "\n";
4830 9: return catch @{
4831 10: write (s + "\n");
4832 11: @};
4833 12: @}
4834 @end example
4835
4836 @ssindex inlambda
4837 @ssindex lambda-intro-cont
4838 Lines 4 through 8 contain a lambda function, which @ccmode{} recognizes
4839 by the @code{lambda} keyword. If the function argument list is put
4840 on a line of its own, as in line 5, it gets the @code{lambda-intro-cont}
4841 syntax. The function body is handled as an inline method body, with the
4842 addition of the @code{inlambda} syntactic symbol. This means that line
4843 6 gets @code{inlambda} and @code{inline-open}, and line 8 gets
4844 @code{inline-close}@footnote{You might wonder why it doesn't get
4845 @code{inlambda} too. It's because the closing brace is relative to the
4846 opening brace, which stands on its own line in this example. If the
4847 opening brace was hanging on the previous line, then the closing brace
4848 would get the @code{inlambda} syntax too to be indented correctly.}.
4849
4850 @ssindex inexpr-statement
4851 On line 9, @code{catch} is a special function taking a statement block
4852 as its argument. The block is handled as an in-expression statement
4853 with the @code{inexpr-statement} syntax, just like the gcc extended C
4854 example above. The other similar special function, @code{gauge}, is
4855 handled like this too.
4856
4857 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4858 @node K&R Symbols, , Statement Block Symbols, Syntactic Symbols
4859 @comment node-name, next, previous, up
4860 @subsection K&R Symbols
4861 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4862
4863 @ssindex knr-argdecl-intro
4864 @ssindex knr-argdecl
4865 Two other syntactic symbols can appear in old style, non-prototyped C
4866 code @footnote{a.k.a. K&R C, or Kernighan & Ritchie C}:
4867
4868 @example
4869 1: int add_three_integers(a, b, c)
4870 2: int a;
4871 3: int b;
4872 4: int c;
4873 5: @{
4874 6: return a + b + c;
4875 7: @}
4876 @end example
4877
4878 Here, line 2 is the first line in an argument declaration list and so is
4879 given the @code{knr-argdecl-intro} syntactic symbol. Subsequent lines
4880 (i.e. lines 3 and 4 in this example), are given @code{knr-argdecl}
4881 syntax.
4882
4883
4884 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4885 @node Indentation Calculation, , Syntactic Symbols, Indentation Engine Basics
4886 @comment node-name, next, previous, up
4887 @section Indentation Calculation
4888 @cindex indentation
4889 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4890
4891 Indentation for a line is calculated from the syntactic context
4892 (@pxref{Syntactic Analysis}).
4893
4894 First, a buffer position is found whose column will be the base for the
4895 indentation calculation. It's the anchor position in the first
4896 syntactic element that provides one that is used. If no syntactic
4897 element has an anchor position then column zero is used.
4898
4899 Second, the syntactic symbols in each syntactic element are looked up
4900 in the @code{c-offsets-alist} style variable
4901 (@pxref{c-offsets-alist}), which is an association list of syntactic
4902 symbols and the offsets to apply for those symbols. These offsets are
4903 added together with the base column to produce the new indentation
4904 column.
4905
4906 Let's use our two code examples above to see how this works. Here is
4907 our first example again:
4908
4909 @example
4910 1: void swap( int& a, int& b )
4911 2: @{
4912 3: int tmp = a;
4913 4: a = b;
4914 5: b = tmp;
4915 6: @}
4916 @end example
4917
4918 Let's say point is on line 3 and we hit the @key{TAB} key to reindent
4919 the line. The syntactic context for that line is:
4920
4921 @example
4922 ((defun-block-intro 29))
4923 @end example
4924
4925 @noindent
4926 Since buffer position 29 is the first and only anchor position in the
4927 list, @ccmode{} goes there and asks for the current column. This brace
4928 is in column zero, so @ccmode{} uses @samp{0} as the base column.
4929
4930 Next, @ccmode{} looks up @code{defun-block-intro} in the
4931 @code{c-offsets-alist} style variable. Let's say it finds the value
4932 @samp{4}; it adds this to the base column @samp{0}, yielding a running
4933 total indentation of 4 spaces.
4934
4935 Since there is only one syntactic element on the list for this line,
4936 indentation calculation is complete, and the total indentation for the
4937 line is 4 spaces.
4938
4939 Here's another example:
4940
4941 @example
4942 1: int add( int val, int incr, int doit )
4943 2: @{
4944 3: if( doit )
4945 4: @{
4946 5: return( val + incr );
4947 6: @}
4948 7: return( val );
4949 8: @}
4950 @end example
4951
4952 If we were to hit @kbd{TAB} on line 4 in the above example, the same
4953 basic process is performed, despite the differences in the syntactic
4954 context. The context for this line is:
4955
4956 @example
4957 ((substatement-open 46))
4958 @end example
4959
4960 Here, @ccmode{} goes to buffer position 46, which is the @samp{i} in
4961 @code{if} on line 3. This character is in the fourth column on that
4962 line so the base column is @samp{4}. Then @ccmode{} looks up the
4963 @code{substatement-open} symbol in @code{c-offsets-alist}. Let's say it
4964 finds the value @samp{4}. It's added with the base column and yields an
4965 indentation for the line of 8 spaces.
4966
4967 Simple, huh?
4968
4969 Actually, it's a bit more complicated than that since the entries on
4970 @code{c-offsets-alist} can be much more than plain offsets.
4971 @xref{c-offsets-alist}, for the full story.
4972
4973 Anyway, the mode usually just does The Right Thing without you having to
4974 think about it in this much detail. But when customizing indentation,
4975 it's helpful to understand the general indentation model being used.
4976
4977 As you configure @ccmode{}, you might want to set the variable
4978 @code{c-echo-syntactic-information-p} to non-@code{nil} so that the
4979 syntactic context and calculated offset always is echoed in the
4980 minibuffer when you hit @kbd{TAB}.
4981
4982
4983 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4984 @node Customizing Indentation, Custom Macros, Indentation Engine Basics, Top
4985 @comment node-name, next, previous, up
4986 @chapter Customizing Indentation
4987 @cindex customization, indentation
4988 @cindex indentation
4989 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4990
4991 The principal variable for customizing indentation is the style
4992 variable @code{c-offsets-alist}, which gives an @dfn{offset} (an
4993 indentation rule) for each syntactic symbol. Its structure and
4994 semantics are completely described in @ref{c-offsets-alist}. The
4995 various ways you can set the variable, including the use of the
4996 @ccmode{} style system, are described in @ref{Config Basics} and its
4997 sections, in particular @ref{Style Variables}.
4998
4999 The simplest and most used kind of ``offset'' setting in
5000 @code{c-offsets-alist} is in terms of multiples of
5001 @code{c-basic-offset}:
5002
5003 @defopt c-basic-offset
5004 @vindex basic-offset (c-)
5005 This style variable holds the basic offset between indentation levels.
5006 It's factory default is 4, but all the built-in styles set it
5007 themselves, to some value between 2 (for @code{gnu} style) and 8 (for
5008 @code{bsd}, @code{linux}, and @code{python} styles).
5009 @end defopt
5010
5011 The most flexible ``offset'' setting you can make in
5012 @code{c-offsets-alist} is a line-up function (or even a list of them),
5013 either one supplied by @ccmode{} (@pxref{Line-Up Functions}) or one
5014 you write yourself (@pxref{Custom Line-Up}).
5015
5016 Finally, in @ref{Other Indentation} you'll find the tool of last
5017 resort: a hook which is called after a line has been indented. You
5018 can install functions here to make ad-hoc adjustments to any line's
5019 indentation.
5020
5021 @menu
5022 * c-offsets-alist::
5023 * Interactive Customization::
5024 * Line-Up Functions::
5025 * Custom Line-Up::
5026 * Other Indentation::
5027 @end menu
5028
5029
5030 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5031 @node c-offsets-alist, Interactive Customization, Customizing Indentation, Customizing Indentation
5032 @comment node-name, next, previous, up
5033 @section c-offsets-alist
5034 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5035
5036 This section explains the structure and semantics of the style
5037 variable @code{c-offset-alist}, the principal variable for configuring
5038 indentation. Details of how to set it up, and its relationship to
5039 @ccmode{}'s style system are given in @ref{Style Variables}.
5040
5041 @defopt c-offsets-alist
5042 @vindex offsets-alist (c-)
5043 This is an alist which associates an offset with each syntactic
5044 symbol. This @dfn{offset} is a rule specifying how to indent a line
5045 whose syntactic context matches the symbol. @xref{Syntactic
5046 Analysis}.
5047
5048 Note that the buffer-local binding of this alist in a @ccmode{} buffer
5049 contains an entry for @emph{every} syntactic symbol. Its global
5050 binding and its settings within style specifications usually contain
5051 only a few entries. @xref{Style Variables}.
5052
5053 The offset specification associated with any particular syntactic
5054 symbol can be an integer, a variable name, a vector, a function or
5055 lambda expression, a list, or one of the following special symbols:
5056 @code{+}, @code{-}, @code{++}, @code{--}, @code{*}, or @code{/}. The
5057 meanings of these values are described in detail below.
5058
5059 Here is an example fragment of a @code{c-offsets-alist}, showing some
5060 of these kinds of offsets:
5061
5062 @example
5063 ((statement . 0)
5064 (substatement . +)
5065 (cpp-macro . [0])
5066 (topmost-intro-cont . c-lineup-topmost-intro-cont)
5067 (statement-block-intro . (add c-lineup-whitesmith-in-block
5068 c-indent-multi-line-block))
5069 @dots{}
5070 @*)
5071 @end example
5072 @end defopt
5073
5074 @deffn Command c-set-offset (@kbd{C-c C-o})
5075 @findex set-offset (c-)
5076 @kindex C-c C-o
5077 This command changes the entry for a syntactic symbol in the current
5078 binding of @code{c-offsets-alist}, or it inserts a new entry if there
5079 isn't already one for that syntactic symbol.
5080
5081 You can use @code{c-set-offsets} interactively within a @ccmode{}
5082 buffer to make experimental changes to your indentation settings.
5083 @kbd{C-c C-o} prompts you for the syntactic symbol to change
5084 (defaulting to that of the current line) and the new offset
5085 (defaulting to the current offset).
5086
5087 @code{c-set-offsets} takes two arguments when used programmatically:
5088 @var{symbol}, the syntactic element symbol to change and @var{offset},
5089 the new offset for that syntactic element. You can call the command
5090 in your @file{.emacs} to change the global binding of
5091 @code{c-offsets-alist} (@pxref{Style Variables}); you can use it in a
5092 hook function to make changes from the current style. @ccmode{}
5093 itself uses this function when initializing styles.
5094 @end deffn
5095
5096 @cindex offset specification
5097 The ``offset specifications'' in @code{c-offsets-alist} can be any of
5098 the following:
5099
5100 @table @asis
5101 @item An integer
5102 The integer specifies a relative offset. All relative
5103 offsets@footnote{The syntactic context @code{@w{((defun-block-intro
5104 2724) (comment-intro))}} would likely have two relative offsets.} will
5105 be added together and used to calculate the indentation relative to an
5106 anchor position earlier in the buffer. @xref{Indentation
5107 Calculation}, for details. Most of the time, it's probably better to
5108 use one of the special symbols like @code{+} than an integer (apart
5109 from zero).
5110
5111 @item One of the symbols @code{+}, @code{-}, @code{++}, @code{--}, @code{*}, or @code{/}
5112 These special symbols describe a relative offset in multiples of
5113 @code{c-basic-offset}:
5114
5115 By defining a style's indentation in terms of @code{c-basic-offset},
5116 you can change the amount of whitespace given to an indentation level
5117 while maintaining the same basic shape of your code. Here are the
5118 values that the special symbols correspond to:
5119
5120 @table @code
5121 @item +
5122 @code{c-basic-offset} times 1
5123 @item -
5124 @code{c-basic-offset} times -1
5125 @item ++
5126 @code{c-basic-offset} times 2
5127 @item --
5128 @code{c-basic-offset} times -2
5129 @item *
5130 @code{c-basic-offset} times 0.5
5131 @item /
5132 @code{c-basic-offset} times -0.5
5133 @end table
5134
5135 @item A vector
5136 The first element of the vector, an integer, sets the absolute
5137 indentation column. This will override any previously calculated
5138 indentation, but won't override relative indentation calculated from
5139 syntactic elements later on in the syntactic context of the line being
5140 indented. @xref{Indentation Calculation}. Any elements in the vector
5141 beyond the first will be ignored.
5142
5143 @item A function or lambda expression
5144 The function will be called and its return value will in turn be
5145 evaluated as an offset specification. Functions are useful when more
5146 context than just the syntactic symbol is needed to get the desired
5147 indentation. @xref{Line-Up Functions}, and @ref{Custom Line-Up}, for
5148 details about them.
5149
5150 @item A symbol with a variable binding
5151 If the symbol also has a function binding, the function takes
5152 precedence over the variable. Otherwise the value of the variable is
5153 used. It must be an integer (which is used as relative offset) or a
5154 vector (an absolute offset).
5155
5156 @item A list
5157 The offset can also be a list containing several offset
5158 specifications; these are evaluated recursively and combined. A list
5159 is typically only useful when some of the offsets are line-up
5160 functions. A common strategy is calling a sequence of functions in
5161 turn until one of them recognizes that it is appropriate for the
5162 source line and returns a non-@code{nil} value.
5163
5164 @code{nil} values are always ignored when the offsets are combined.
5165 The first element of the list specifies the method of combining the
5166 non-@code{nil} offsets from the remaining elements:
5167
5168 @table @code
5169 @item first
5170 Use the first offset that doesn't evaluate to @code{nil}. Subsequent
5171 elements of the list don't get evaluated.
5172 @item min
5173 Use the minimum of all the offsets. All must be either relative or
5174 absolute - they can't be mixed.
5175 @item max
5176 Use the maximum of all the offsets. All must be either relative or
5177 absolute - they can't be mixed.
5178 @item add
5179 Add all the evaluated offsets together. Exactly one of them may be
5180 absolute, in which case the result is absolute. Any relative offsets
5181 that preceded the absolute one in the list will be ignored in that case.
5182 @end table
5183
5184 As a compatibility measure, if the first element is none of the above
5185 then it too will be taken as an offset specification and the whole list
5186 will be combined according to the method @code{first}.
5187 @end table
5188
5189 @vindex c-strict-syntax-p
5190 @vindex strict-syntax-p (c-)
5191 If an offset specification evaluates to @code{nil}, then a relative
5192 offset of 0 (zero) is used@footnote{There is however a variable
5193 @code{c-strict-syntax-p} that when set to non-@code{nil} will cause an
5194 error to be signaled in that case. It's now considered obsolete since
5195 it doesn't work well with some of the alignment functions that return
5196 @code{nil} instead of zero. You should therefore leave
5197 @code{c-strict-syntax-p} set to @code{nil}.}.
5198
5199 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5200 @node Interactive Customization, Line-Up Functions, c-offsets-alist, Customizing Indentation
5201 @comment node-name, next, previous, up
5202 @section Interactive Customization
5203 @cindex customization, interactive
5204 @cindex interactive customization
5205 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5206
5207 As an example of how to customize indentation, let's change the
5208 style of this example@footnote{In this and subsequent examples, the
5209 original code is formatted using the @samp{gnu} style unless otherwise
5210 indicated. @xref{Styles}.}:
5211
5212 @example
5213 @group
5214 1: int add( int val, int incr, int doit )
5215 2: @{
5216 3: if( doit )
5217 4: @{
5218 5: return( val + incr );
5219 6: @}
5220 7: return( val );
5221 8: @}
5222 @end group
5223 @end example
5224
5225 @noindent
5226 to:
5227
5228 @example
5229 @group
5230 1: int add( int val, int incr, int doit )
5231 2: @{
5232 3: if( doit )
5233 4: @{
5234 5: return( val + incr );
5235 6: @}
5236 7: return( val );
5237 8: @}
5238 @end group
5239 @end example
5240
5241 In other words, we want to change the indentation of braces that open a
5242 block following a condition so that the braces line up under the
5243 conditional, instead of being indented. Notice that the construct we
5244 want to change starts on line 4. To change the indentation of a line,
5245 we need to see which syntactic symbols affect the offset calculations
5246 for that line. Hitting @kbd{C-c C-s} on line 4 yields:
5247
5248 @example
5249 ((substatement-open 44))
5250 @end example
5251
5252 @noindent
5253 so we know that to change the offset of the open brace, we need to
5254 change the indentation for the @code{substatement-open} syntactic
5255 symbol.
5256
5257 To do this interactively, just hit @kbd{C-c C-o}. This prompts
5258 you for the syntactic symbol to change, providing a reasonable default.
5259 In this case, the default is @code{substatement-open}, which is just the
5260 syntactic symbol we want to change!
5261
5262 After you hit return, @ccmode{} will then prompt you for the new
5263 offset value, with the old value as the default. The default in this
5264 case is @samp{+}, but we want no extra indentation so enter
5265 @samp{0} and @kbd{RET}. This will associate the offset 0 with the
5266 syntactic symbol @code{substatement-open}.
5267
5268 To check your changes quickly, just hit @kbd{C-c C-q}
5269 (@code{c-indent-defun}) to reindent the entire function. The example
5270 should now look like:
5271
5272 @example
5273 @group
5274 1: int add( int val, int incr, int doit )
5275 2: @{
5276 3: if( doit )
5277 4: @{
5278 5: return( val + incr );
5279 6: @}
5280 7: return( val );
5281 8: @}
5282 @end group
5283 @end example
5284
5285 Notice how just changing the open brace offset on line 4 is all we
5286 needed to do. Since the other affected lines are indented relative to
5287 line 4, they are automatically indented the way you'd expect. For more
5288 complicated examples, this might not always work. The general approach
5289 to take is to always start adjusting offsets for lines higher up in the
5290 file, then reindent and see if any following lines need further
5291 adjustments.
5292
5293 @c Move this bit to "Styles" (2005/10/7)
5294 @deffn Command c-set-offset symbol offset
5295 @findex set-offset (c-)
5296 @kindex C-c C-o
5297 This is the command bound to @kbd{C-c C-o}. It provides a convenient
5298 way to set offsets on @code{c-offsets-alist} both interactively (see
5299 the example above) and from your mode hook.
5300
5301 It takes two arguments when used programmatically: @var{symbol} is the
5302 syntactic element symbol to change and @var{offset} is the new offset
5303 for that syntactic element.
5304 @end deffn
5305 @c End of MOVE THIS BIT.
5306
5307 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5308 @node Line-Up Functions, Custom Line-Up, Interactive Customization, Customizing Indentation
5309 @comment node-name, next, previous, up
5310 @section Line-Up Functions
5311 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5312
5313 @cindex line-up function
5314 @cindex indentation function
5315 Often there are cases when a simple offset setting on a syntactic
5316 symbol isn't enough to get the desired indentation---for example, you
5317 might want to line up a closing parenthesis with the matching opening
5318 one rather than indenting relative to its ``anchor point''. @ccmode{}
5319 provides this flexibility with @dfn{line-up functions}.
5320
5321 The way you associate a line-up function with a syntactic symbol is
5322 described in @ref{c-offsets-alist}. @ccmode{} comes with many
5323 predefined line-up functions for common situations. If none of these
5324 does what you want, you can write your own. @xref{Custom Line-Up}.
5325 Sometimes, it is easier to tweak the standard indentation by adding a
5326 function to @code{c-special-indent-hook} (@pxref{Other Indentation}).
5327
5328 The line-up functions haven't been adapted for AWK buffers or tested
5329 with them. Some of them might work serendipitously. There shouldn't be
5330 any problems writing custom line-up functions for AWK mode.
5331
5332 The calling convention for line-up functions is described fully in
5333 @ref{Custom Line-Up}. Roughly speaking, the return value is either an
5334 offset itself (such as @code{+} or @code{[0]}) or it's @code{nil},
5335 meaning ``this function is inappropriate in this case - try a
5336 different one''. @xref{c-offsets-alist}.
5337
5338 The subsections below describe all the standard line-up functions,
5339 categorized by the sort of token the lining-up centers around. For
5340 each of these functions there is a ``works with'' list that indicates
5341 which syntactic symbols the function is intended to be used with.
5342
5343 @macro workswith
5344 @emph{Works with:@ }
5345 @end macro
5346 @ifinfo
5347 @unmacro workswith
5348 @macro workswith
5349 Works with:
5350 @end macro
5351 @end ifinfo
5352
5353 @macro sssTBasicOffset
5354 <--> @i{c-basic-offset}@c
5355 @end macro
5356
5357 @macro sssTsssTBasicOffset
5358 <--><--> @i{c-basic-offset}@c
5359 @end macro
5360
5361 @macro hereFn{func}
5362 <- @i{\func\}@c
5363 @end macro
5364
5365 @c The TeX backend seems to insert extra spaces around the argument. :P
5366 @iftex
5367 @unmacro hereFn
5368 @macro hereFn{func}
5369 <-@i{\func\}@c
5370 @end macro
5371 @end iftex
5372
5373 @menu
5374 * Brace/Paren Line-Up::
5375 * List Line-Up::
5376 * Operator Line-Up::
5377 * Comment Line-Up::
5378 * Misc Line-Up::
5379 @end menu
5380
5381 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5382 @node Brace/Paren Line-Up, List Line-Up, Line-Up Functions, Line-Up Functions
5383 @comment node-name, next, previous, up
5384 @subsection Brace and Parenthesis Line-Up Functions
5385 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5386
5387 The line-up functions here calculate the indentation for braces,
5388 parentheses and statements within brace blocks.
5389
5390 @defun c-lineup-close-paren
5391 @findex lineup-close-paren (c-)
5392 Line up the closing paren under its corresponding open paren if the
5393 open paren is followed by code. If the open paren ends its line, no
5394 indentation is added. E.g:
5395
5396 @example
5397 @group
5398 main (int,
5399 char **
5400 ) @hereFn{c-lineup-close-paren}
5401 @end group
5402 @end example
5403
5404 @noindent
5405 and
5406
5407 @example
5408 @group
5409 main (
5410 int, char **
5411 ) @hereFn{c-lineup-close-paren}
5412 @end group
5413 @end example
5414
5415 As a special case, if a brace block is opened at the same line as the
5416 open parenthesis of the argument list, the indentation is
5417 @code{c-basic-offset} instead of the open paren column. See
5418 @code{c-lineup-arglist} for further discussion of this ``DWIM'' measure.
5419
5420 @workswith All @code{*-close} symbols.
5421 @end defun
5422
5423 @comment ------------------------------------------------------------
5424
5425 @anchor{c-lineup-arglist-close-under-paren}
5426 @defun c-lineup-arglist-close-under-paren
5427 @findex lineup-arglist-close-under-paren (c-)
5428 Set your @code{arglist-close} syntactic symbol to this line-up function
5429 so that parentheses that close argument lists will line up under the
5430 parenthesis that opened the argument list. It can also be used with
5431 @code{arglist-cont} and @code{arglist-cont-nonempty} to line up all
5432 lines inside a parenthesis under the open paren.
5433
5434 As a special case, if a brace block is opened at the same line as the
5435 open parenthesis of the argument list, the indentation is
5436 @code{c-basic-offset} only. See @code{c-lineup-arglist} for further
5437 discussion of this ``DWIM'' measure.
5438
5439 @workswith Almost all symbols, but are typically most useful on
5440 @code{arglist-close}, @code{brace-list-close}, @code{arglist-cont} and
5441 @code{arglist-cont-nonempty}.
5442 @end defun
5443
5444 @comment ------------------------------------------------------------
5445
5446 @defun c-indent-one-line-block
5447 @findex indent-one-line-block (c-)
5448 Indent a one line block @code{c-basic-offset} extra. E.g:
5449
5450 @example
5451 @group
5452 if (n > 0)
5453 @{m+=n; n=0;@} @hereFn{c-indent-one-line-block}
5454 @sssTBasicOffset{}
5455 @end group
5456 @end example
5457
5458 @noindent
5459 and
5460
5461 @example
5462 @group
5463 if (n > 0)
5464 @{ @hereFn{c-indent-one-line-block}
5465 m+=n; n=0;
5466 @}
5467 @end group
5468 @end example
5469
5470 The block may be surrounded by any kind of parenthesis characters.
5471 @code{nil} is returned if the line doesn't start with a one line block,
5472 which makes the function usable in list expressions.
5473
5474 @workswith Almost all syntactic symbols, but most useful on the
5475 @code{-open} symbols.
5476 @end defun
5477
5478 @comment ------------------------------------------------------------
5479
5480 @defun c-indent-multi-line-block
5481 @findex indent-multi-line-block (c-)
5482 Indent a multiline block @code{c-basic-offset} extra. E.g:
5483
5484 @example
5485 @group
5486 int *foo[] = @{
5487 NULL,
5488 @{17@}, @hereFn{c-indent-multi-line-block}
5489 @end group
5490 @end example
5491
5492 @noindent
5493 and
5494
5495 @example
5496 @group
5497 int *foo[] = @{
5498 NULL,
5499 @{ @hereFn{c-indent-multi-line-block}
5500 17
5501 @},
5502 @sssTBasicOffset{}
5503 @end group
5504 @end example
5505
5506 The block may be surrounded by any kind of parenthesis characters.
5507 @code{nil} is returned if the line doesn't start with a multiline
5508 block, which makes the function usable in list expressions.
5509
5510 @workswith Almost all syntactic symbols, but most useful on the
5511 @code{-open} symbols.
5512 @end defun
5513
5514 @comment ------------------------------------------------------------
5515
5516 @defun c-lineup-runin-statements
5517 @findex lineup-runin-statements (c-)
5518 Line up statements for coding standards which place the first statement
5519 in a block on the same line as the block opening brace@footnote{Run-in
5520 style doesn't really work too well. You might need to write your own
5521 custom line-up functions to better support this style.}. E.g:
5522
5523 @example
5524 @group
5525 int main()
5526 @{ puts ("Hello!");
5527 return 0; @hereFn{c-lineup-runin-statements}
5528 @}
5529 @end group
5530 @end example
5531
5532 If there is no statement after the opening brace to align with,
5533 @code{nil} is returned. This makes the function usable in list
5534 expressions.
5535
5536 @workswith The @code{statement} syntactic symbol.
5537 @end defun
5538
5539 @comment ------------------------------------------------------------
5540
5541 @defun c-lineup-inexpr-block
5542 @findex lineup-inexpr-block (c-)
5543 This can be used with the in-expression block symbols to indent the
5544 whole block to the column where the construct is started. E.g. for Java
5545 anonymous classes, this lines up the class under the @samp{new} keyword,
5546 and in Pike it lines up the lambda function body under the @samp{lambda}
5547 keyword. Returns @code{nil} if the block isn't part of such a
5548 construct.
5549
5550 @workswith @code{inlambda}, @code{inexpr-statement},
5551 @code{inexpr-class}.
5552 @end defun
5553
5554 @comment ------------------------------------------------------------
5555
5556 @defun c-lineup-after-whitesmith-blocks
5557 @findex lineup-after-whitesmith-blocks (c-)
5558 Compensate for Whitesmith style indentation of blocks. Due to the way
5559 @ccmode{} calculates anchor positions for normal lines inside blocks,
5560 this function is necessary for those lines to get correct Whitesmith
5561 style indentation. Consider the following examples:
5562
5563 @example
5564 @group
5565 int foo()
5566 @{
5567 a;
5568 x; @hereFn{c-lineup-after-whitesmith-blocks}
5569 @end group
5570 @end example
5571
5572 @example
5573 @group
5574 int foo()
5575 @{
5576 @{
5577 a;
5578 @}
5579 x; @hereFn{c-lineup-after-whitesmith-blocks}
5580 @end group
5581 @end example
5582
5583 The fact that the line with @code{x} is preceded by a Whitesmith style
5584 indented block in the latter case and not the first should not affect
5585 its indentation. But since CC Mode in cases like this uses the
5586 indentation of the preceding statement as anchor position, the @code{x}
5587 would in the second case be indented too much if the offset for
5588 @code{statement} was set simply to zero.
5589
5590 This lineup function corrects for this situation by detecting if the
5591 anchor position is at an open paren character. In that case, it instead
5592 indents relative to the surrounding block just like
5593 @code{c-lineup-whitesmith-in-block}.
5594
5595 @workswith @code{brace-list-entry}, @code{brace-entry-open},
5596 @code{statement}, @code{arglist-cont}.
5597 @end defun
5598
5599 @comment ------------------------------------------------------------
5600
5601 @defun c-lineup-whitesmith-in-block
5602 @findex lineup-whitesmith-in-block (c-)
5603 Line up lines inside a block in Whitesmith style. It's done in a way
5604 that works both when the opening brace hangs and when it doesn't. E.g:
5605
5606 @example
5607 @group
5608 something
5609 @{
5610 foo; @hereFn{c-lineup-whitesmith-in-block}
5611 @}
5612 @end group
5613 @end example
5614
5615 @noindent
5616 and
5617
5618 @example
5619 @group
5620 something @{
5621 foo; @hereFn{c-lineup-whitesmith-in-block}
5622 @}
5623 @sssTBasicOffset{}
5624 @end group
5625 @end example
5626
5627 In the first case the indentation is kept unchanged, in the second
5628 @code{c-basic-offset} is added.
5629
5630 @workswith @code{defun-close}, @code{defun-block-intro},
5631 @code{inline-close}, @code{block-close}, @code{brace-list-close},
5632 @code{brace-list-intro}, @code{statement-block-intro},
5633 @code{arglist-intro}, @code{arglist-cont-nonempty},
5634 @code{arglist-close}, and all @code{in*} symbols, e.g. @code{inclass}
5635 and @code{inextern-lang}.
5636 @end defun
5637
5638 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5639 @node List Line-Up, Operator Line-Up, Brace/Paren Line-Up, Line-Up Functions
5640 @comment node-name, next, previous, up
5641 @subsection List Line-Up Functions
5642 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5643
5644 The line-up functions here calculate the indentation for lines which
5645 form lists of items, usually separated by commas.
5646
5647 The function @ref{c-lineup-arglist-close-under-paren}, which is mainly
5648 for indenting a close parenthesis, is also useful for the lines
5649 contained within parentheses.
5650
5651 @defun c-lineup-arglist
5652 @findex lineup-arglist (c-)
5653 Line up the current argument line under the first argument.
5654
5655 As a special case, if an argument on the same line as the open
5656 parenthesis starts with a brace block opener, the indentation is
5657 @code{c-basic-offset} only. This is intended as a ``DWIM'' measure in
5658 cases like macros that contain statement blocks, e.g:
5659
5660 @example
5661 @group
5662 A_VERY_LONG_MACRO_NAME (@{
5663 some (code, with + long, lines * in[it]);
5664 @});
5665 @sssTBasicOffset{}
5666 @end group
5667 @end example
5668
5669 This is motivated partly because it's more in line with how code
5670 blocks are handled, and partly since it approximates the behavior of
5671 earlier CC Mode versions, which due to inaccurate analysis tended to
5672 indent such cases this way.
5673
5674 @workswith @code{arglist-cont-nonempty}, @code{arglist-close}.
5675 @end defun
5676
5677 @comment ------------------------------------------------------------
5678
5679 @defun c-lineup-arglist-intro-after-paren
5680 @findex lineup-arglist-intro-after-paren (c-)
5681 Line up a line to just after the open paren of the surrounding paren or
5682 brace block.
5683
5684 @workswith @code{defun-block-intro}, @code{brace-list-intro},
5685 @code{statement-block-intro}, @code{statement-case-intro},
5686 @code{arglist-intro}.
5687 @end defun
5688
5689 @comment ------------------------------------------------------------
5690
5691 @defun c-lineup-multi-inher
5692 @findex lineup-multi-inher (c-)
5693 Line up the classes in C++ multiple inheritance clauses and member
5694 initializers under each other. E.g:
5695
5696 @example
5697 @group
5698 Foo::Foo (int a, int b):
5699 Cyphr (a),
5700 Bar (b) @hereFn{c-lineup-multi-inher}
5701 @end group
5702 @end example
5703
5704 @noindent
5705 and
5706
5707 @example
5708 @group
5709 class Foo
5710 : public Cyphr,
5711 public Bar @hereFn{c-lineup-multi-inher}
5712 @end group
5713 @end example
5714
5715 @noindent
5716 and
5717
5718 @example
5719 @group
5720 Foo::Foo (int a, int b)
5721 : Cyphr (a)
5722 , Bar (b) @hereFn{c-lineup-multi-inher}
5723 @end group
5724 @end example
5725
5726 @workswith @code{inher-cont}, @code{member-init-cont}.
5727 @end defun
5728
5729 @comment ------------------------------------------------------------
5730
5731 @defun c-lineup-java-inher
5732 @findex lineup-java-inher (c-)
5733 Line up Java implements and extends declarations. If class names
5734 follow on the same line as the @samp{implements}/@samp{extends}
5735 keyword, they are lined up under each other. Otherwise, they are
5736 indented by adding @code{c-basic-offset} to the column of the keyword.
5737 E.g:
5738
5739 @example
5740 @group
5741 class Foo
5742 extends
5743 Bar @hereFn{c-lineup-java-inher}
5744 @sssTBasicOffset{}
5745 @end group
5746 @end example
5747
5748 @noindent
5749 and
5750
5751 @example
5752 @group
5753 class Foo
5754 extends Cyphr,
5755 Bar @hereFn{c-lineup-java-inher}
5756 @end group
5757 @end example
5758
5759 @workswith @code{inher-cont}.
5760 @end defun
5761
5762 @comment ------------------------------------------------------------
5763
5764 @defun c-lineup-java-throws
5765 @findex lineup-java-throws (c-)
5766 Line up Java throws declarations. If exception names follow on the
5767 same line as the throws keyword, they are lined up under each other.
5768 Otherwise, they are indented by adding @code{c-basic-offset} to the
5769 column of the @samp{throws} keyword. The @samp{throws} keyword itself
5770 is also indented by @code{c-basic-offset} from the function declaration
5771 start if it doesn't hang. E.g:
5772
5773 @example
5774 @group
5775 int foo()
5776 throws @hereFn{c-lineup-java-throws}
5777 Bar @hereFn{c-lineup-java-throws}
5778 @sssTsssTBasicOffset{}
5779 @end group
5780 @end example
5781
5782 @noindent
5783 and
5784
5785 @example
5786 @group
5787 int foo() throws Cyphr,
5788 Bar, @hereFn{c-lineup-java-throws}
5789 Vlod @hereFn{c-lineup-java-throws}
5790 @end group
5791 @end example
5792
5793 @workswith @code{func-decl-cont}.
5794 @end defun
5795
5796 @comment ------------------------------------------------------------
5797
5798 @defun c-lineup-template-args
5799 @findex lineup-template-args (c-)
5800 Line up the arguments of a template argument list under each other, but
5801 only in the case where the first argument is on the same line as the
5802 opening @samp{<}.
5803
5804 To allow this function to be used in a list expression, @code{nil} is
5805 returned if there's no template argument on the first line.
5806
5807 @workswith @code{template-args-cont}.
5808 @end defun
5809
5810 @comment ------------------------------------------------------------
5811
5812 @defun c-lineup-ObjC-method-call
5813 @findex lineup-ObjC-method-call (c-)
5814 For Objective-C code, line up selector args as Emacs Lisp mode does
5815 with function args: go to the position right after the message receiver,
5816 and if you are at the end of the line, indent the current line
5817 c-basic-offset columns from the opening bracket; otherwise you are
5818 looking at the first character of the first method call argument, so
5819 lineup the current line with it.
5820
5821 @workswith @code{objc-method-call-cont}.
5822 @end defun
5823
5824 @comment ------------------------------------------------------------
5825
5826 @defun c-lineup-ObjC-method-args
5827 @findex lineup-ObjC-method-args (c-)
5828 For Objective-C code, line up the colons that separate args. The colon
5829 on the current line is aligned with the one on the first line.
5830
5831 @workswith @code{objc-method-args-cont}.
5832 @end defun
5833
5834 @comment ------------------------------------------------------------
5835
5836 @defun c-lineup-ObjC-method-args-2
5837 @findex lineup-ObjC-method-args-2 (c-)
5838 Similar to @code{c-lineup-ObjC-method-args} but lines up the colon on
5839 the current line with the colon on the previous line.
5840
5841 @workswith @code{objc-method-args-cont}.
5842 @end defun
5843
5844 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5845 @node Operator Line-Up, Comment Line-Up, List Line-Up, Line-Up Functions
5846 @comment node-name, next, previous, up
5847 @subsection Operator Line-Up Functions
5848 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5849
5850 The line-up functions here calculate the indentation for lines which
5851 start with an operator, by lining it up with something on the previous
5852 line.
5853
5854 @defun c-lineup-argcont
5855 @findex lineup-argcont (c-)
5856 Line up a continued argument. E.g:
5857
5858 @example
5859 @group
5860 foo (xyz, aaa + bbb + ccc
5861 + ddd + eee + fff); @hereFn{c-lineup-argcont}
5862 @end group
5863 @end example
5864
5865 Only continuation lines like this are touched, @code{nil} is returned on
5866 lines which are the start of an argument.
5867
5868 Within a gcc @code{asm} block, @code{:} is recognised as an argument
5869 separator, but of course only between operand specifications, not in the
5870 expressions for the operands.
5871
5872 @workswith @code{arglist-cont}, @code{arglist-cont-nonempty}.
5873 @end defun
5874
5875 @comment ------------------------------------------------------------
5876
5877 @defun c-lineup-arglist-operators
5878 @findex lineup-arglist-operators (c-)
5879 Line up lines starting with an infix operator under the open paren.
5880 Return @code{nil} on lines that don't start with an operator, to leave
5881 those cases to other line-up functions. Example:
5882
5883 @example
5884 @group
5885 if ( x < 10
5886 || at_limit (x, @hereFn{c-lineup-arglist-operators}
5887 list) @hereFn{c-lineup-arglist-operators@r{ returns nil}}
5888 )
5889 @end group
5890 @end example
5891
5892 Since this function doesn't do anything for lines without an infix
5893 operator you typically want to use it together with some other lineup
5894 settings, e.g. as follows (the @code{arglist-close} setting is just a
5895 suggestion to get a consistent style):
5896
5897 @example
5898 (c-set-offset 'arglist-cont
5899 '(c-lineup-arglist-operators 0))
5900 (c-set-offset 'arglist-cont-nonempty
5901 '(c-lineup-arglist-operators c-lineup-arglist))
5902 (c-set-offset 'arglist-close
5903 '(c-lineup-arglist-close-under-paren))
5904 @end example
5905
5906 @workswith @code{arglist-cont}, @code{arglist-cont-nonempty}.
5907 @end defun
5908
5909 @comment ------------------------------------------------------------
5910
5911 @defun c-lineup-assignments
5912 @findex lineup-assignments (c-)
5913 Line up the current line after the assignment operator on the first line
5914 in the statement. If there isn't any, return nil to allow stacking with
5915 other line-up functions. If the current line contains an assignment
5916 operator too, try to align it with the first one.
5917
5918 @workswith @code{topmost-intro-cont}, @code{statement-cont},
5919 @code{arglist-cont}, @code{arglist-cont-nonempty}.
5920
5921 @end defun
5922
5923 @comment ------------------------------------------------------------
5924
5925 @defun c-lineup-math
5926 @findex lineup-math (c-)
5927 Like @code{c-lineup-assignments} but indent with @code{c-basic-offset}
5928 if no assignment operator was found on the first line. I.e. this
5929 function is the same as specifying a list @code{(c-lineup-assignments
5930 +)}. It's provided for compatibility with old configurations.
5931
5932 @workswith @code{topmost-intro-cont}, @code{statement-cont},
5933 @code{arglist-cont}, @code{arglist-cont-nonempty}.
5934 @end defun
5935
5936 @comment ------------------------------------------------------------
5937
5938 @defun c-lineup-cascaded-calls
5939 @findex lineup-cascaded-calls (c-)
5940 Line up ``cascaded calls'' under each other. If the line begins with
5941 @code{->} or @code{.} and the preceding line ends with one or more
5942 function calls preceded by the same token, then the arrow is lined up
5943 with the first of those tokens. E.g:
5944
5945 @example
5946 @group
5947 r = proc->add(17)->add(18)
5948 ->add(19) + @hereFn{c-lineup-cascaded-calls}
5949 offset; @hereFn{c-lineup-cascaded-calls@r{ (inactive)}}
5950 @end group
5951 @end example
5952
5953 In any other situation @code{nil} is returned to allow use in list
5954 expressions.
5955
5956 @workswith @code{topmost-intro-cont}, @code{statement-cont},
5957 @code{arglist-cont}, @code{arglist-cont-nonempty}.
5958 @end defun
5959
5960 @comment ------------------------------------------------------------
5961
5962 @defun c-lineup-streamop
5963 @findex lineup-streamop (c-)
5964 Line up C++ stream operators (i.e. @samp{<<} and @samp{>>}).
5965
5966 @workswith @code{stream-op}.
5967 @end defun
5968
5969 @comment ------------------------------------------------------------
5970
5971 @defun c-lineup-string-cont
5972 @findex lineup-string-cont (c-)
5973 Line up a continued string under the one it continues. A continued
5974 string in this sense is where a string literal follows directly after
5975 another one. E.g:
5976
5977 @example
5978 @group
5979 result = prefix + "A message "
5980 "string."; @hereFn{c-lineup-string-cont}
5981 @end group
5982 @end example
5983
5984 @code{nil} is returned in other situations, to allow stacking with other
5985 lineup functions.
5986
5987 @workswith @code{topmost-intro-cont}, @code{statement-cont},
5988 @code{arglist-cont}, @code{arglist-cont-nonempty}.
5989 @end defun
5990
5991
5992 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5993 @node Comment Line-Up, Misc Line-Up, Operator Line-Up, Line-Up Functions
5994 @comment node-name, next, previous, up
5995 @subsection Comment Line-Up Functions
5996 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5997
5998 The lineup functions here calculate the indentation for several types
5999 of comment structure.
6000
6001 @defun c-lineup-C-comments
6002 @findex lineup-C-comments (c-)
6003 Line up C block comment continuation lines. Various heuristics are used
6004 to handle most of the common comment styles. Some examples:
6005
6006 @example
6007 @group
6008 /* /** /*
6009 * text * text text
6010 */ */ */
6011 @end group
6012 @end example
6013
6014 @example
6015 @group
6016 /* text /* /**
6017 text ** text ** text
6018 */ */ */
6019 @end group
6020 @end example
6021
6022 @example
6023 @group
6024 /**************************************************
6025 * text
6026 *************************************************/
6027 @end group
6028 @end example
6029
6030 @vindex comment-start-skip
6031 @example
6032 @group
6033 /**************************************************
6034 Free form text comments:
6035 In comments with a long delimiter line at the
6036 start, the indentation is kept unchanged for lines
6037 that start with an empty comment line prefix. The
6038 delimiter line is whatever matches the
6039 @code{comment-start-skip} regexp.
6040 **************************************************/
6041 @end group
6042 @end example
6043
6044 The style variable @code{c-comment-prefix-regexp} is used to recognize
6045 the comment line prefix, e.g. the @samp{*} that usually starts every
6046 line inside a comment.
6047
6048 @workswith The @code{c} syntactic symbol.
6049 @end defun
6050
6051 @comment ------------------------------------------------------------
6052
6053 @defun c-lineup-comment
6054 @findex lineup-comment (c-)
6055 Line up a comment-only line according to the style variable
6056 @code{c-comment-only-line-offset}. If the comment is lined up with a
6057 comment starter on the previous line, that alignment is preserved.
6058
6059 @defopt c-comment-only-line-offset
6060 @vindex comment-only-line-offset (c-)
6061 This style variable specifies the extra offset for the line. It can
6062 contain an integer or a cons cell of the form
6063
6064 @example
6065 (@r{@var{non-anchored-offset}} . @r{@var{anchored-offset}})
6066 @end example
6067
6068 @noindent
6069 where @var{non-anchored-offset} is the amount of offset given to
6070 non-column-zero anchored lines, and @var{anchored-offset} is the amount
6071 of offset to give column-zero anchored lines. Just an integer as value
6072 is equivalent to @code{(@r{@var{value}} . -1000)}.
6073 @end defopt
6074
6075 @workswith @code{comment-intro}.
6076 @end defun
6077
6078 @comment ------------------------------------------------------------
6079
6080 @defun c-lineup-knr-region-comment
6081 @findex lineup-knr-region-comment (c-)
6082 Line up a comment in the ``K&R region'' with the declaration. That is
6083 the region between the function or class header and the beginning of the
6084 block. E.g:
6085
6086 @example
6087 @group
6088 int main()
6089 /* Called at startup. */ @hereFn{c-lineup-knr-region-comment}
6090 @{
6091 return 0;
6092 @}
6093 @end group
6094 @end example
6095
6096 Return @code{nil} if called in any other situation, to be useful in list
6097 expressions.
6098
6099 @workswith @code{comment-intro}.
6100 @end defun
6101
6102 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6103 @node Misc Line-Up, , Comment Line-Up, Line-Up Functions
6104 @comment node-name, next, previous, up
6105 @subsection Miscellaneous Line-Up Functions
6106 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6107
6108 The line-up functions here are the odds and ends which didn't fit into
6109 any earlier category.
6110
6111 @defun c-lineup-dont-change
6112 @findex lineup-dont-change (c-)
6113 This lineup function makes the line stay at whatever indentation it
6114 already has; think of it as an identity function for lineups.
6115
6116 @workswith Any syntactic symbol.
6117 @end defun
6118
6119 @comment ------------------------------------------------------------
6120
6121 @defun c-lineup-cpp-define
6122 @findex lineup-cpp-define (c-)
6123 Line up macro continuation lines according to the indentation of the
6124 construct preceding the macro. E.g:
6125
6126 @example
6127 @group
6128 const char msg[] = @hereFn{@r{The beginning of the preceding construct.}}
6129 \"Some text.\";
6130
6131 #define X(A, B) \
6132 do @{ \ @hereFn{c-lineup-cpp-define}
6133 printf (A, B); \
6134 @} while (0)
6135 @end group
6136 @end example
6137
6138 @noindent
6139 and:
6140
6141 @example
6142 @group
6143 int dribble() @{
6144 if (!running) @hereFn{@r{The beginning of the preceding construct.}}
6145 error(\"Not running!\");
6146
6147 #define X(A, B) \
6148 do @{ \ @hereFn{c-lineup-cpp-define}
6149 printf (A, B); \
6150 @} while (0)
6151 @end group
6152 @end example
6153
6154 If @code{c-syntactic-indentation-in-macros} is non-@code{nil}, the
6155 function returns the relative indentation to the macro start line to
6156 allow accumulation with other offsets. E.g. in the following cases,
6157 @code{cpp-define-intro} is combined with the
6158 @code{statement-block-intro} that comes from the @samp{do @{} that hangs
6159 on the @samp{#define} line:
6160
6161 @example
6162 @group
6163 const char msg[] =
6164 \"Some text.\";
6165
6166 #define X(A, B) do @{ \
6167 printf (A, B); \ @hereFn{c-lineup-cpp-define}
6168 this->refs++; \
6169 @} while (0) @hereFn{c-lineup-cpp-define}
6170 @end group
6171 @end example
6172
6173 @noindent
6174 and:
6175
6176 @example
6177 @group
6178 int dribble() @{
6179 if (!running)
6180 error(\"Not running!\");
6181
6182 #define X(A, B) do @{ \
6183 printf (A, B); \ @hereFn{c-lineup-cpp-define}
6184 this->refs++; \
6185 @} while (0) @hereFn{c-lineup-cpp-define}
6186 @end group
6187 @end example
6188
6189 The relative indentation returned by @code{c-lineup-cpp-define} is zero
6190 and two, respectively, on the two lines in each of these examples. They
6191 are then added to the two column indentation that
6192 @code{statement-block-intro} gives in both cases here.
6193
6194 If the relative indentation is zero, then @code{nil} is returned
6195 instead. That is useful in a list expression to specify the default
6196 indentation on the top level.
6197
6198 If @code{c-syntactic-indentation-in-macros} is @code{nil} then this
6199 function keeps the current indentation, except for empty lines (ignoring
6200 the ending backslash) where it takes the indentation from the closest
6201 preceding nonempty line in the macro. If there's no such line in the
6202 macro then the indentation is taken from the construct preceding it, as
6203 described above.
6204
6205 @workswith @code{cpp-define-intro}.
6206 @end defun
6207
6208 @comment ------------------------------------------------------------
6209
6210 @defun c-lineup-gcc-asm-reg
6211 @findex lineup-gcc-asm-reg (c-)
6212 Line up a gcc asm register under one on a previous line.
6213
6214 @example
6215 @group
6216 asm ("foo %1, %0\n"
6217 "bar %0, %1"
6218 : "=r" (w),
6219 "=r" (x)
6220 : "0" (y),
6221 "1" (z));
6222 @end group
6223 @end example
6224
6225 The @samp{x} line is aligned to the text after the @samp{:} on the
6226 @samp{w} line, and similarly @samp{z} under @samp{y}.
6227
6228 This is done only in an @samp{asm} or @samp{__asm__} block, and only to
6229 those lines mentioned. Anywhere else @code{nil} is returned. The usual
6230 arrangement is to have this routine as an extra feature at the start of
6231 arglist lineups, e.g.
6232
6233 @example
6234 (c-lineup-gcc-asm-reg c-lineup-arglist)
6235 @end example
6236
6237 @workswith @code{arglist-cont}, @code{arglist-cont-nonempty}.
6238 @end defun
6239
6240 @comment ------------------------------------------------------------
6241
6242 @defun c-lineup-topmost-intro-cont
6243 @findex lineup-topmost-intro-cont (c-)
6244 Line up declaration continuation lines zero or one indentation
6245 step@footnote{This function is mainly provided to mimic the behavior of
6246 CC Mode 5.28 and earlier where this case wasn't handled consistently so
6247 that those lines could be analyzed as either topmost-intro-cont or
6248 statement-cont. It's used for @code{topmost-intro-cont} by default, but
6249 you might consider using @code{+} instead.}. For lines preceding a
6250 definition, zero is used. For other lines, @code{c-basic-offset} is
6251 added to the indentation. E.g:
6252
6253 @example
6254 @group
6255 int
6256 neg (int i) @hereFn{c-lineup-topmost-intro-cont}
6257 @{
6258 return -i;
6259 @}
6260 @end group
6261 @end example
6262
6263 @noindent
6264 and
6265
6266 @example
6267 @group
6268 struct
6269 larch @hereFn{c-lineup-topmost-intro-cont}
6270 @{
6271 double height;
6272 @}
6273 the_larch, @hereFn{c-lineup-topmost-intro-cont}
6274 another_larch; @hereFn{c-lineup-topmost-intro-cont}
6275 @sssTBasicOffset{}
6276 @end group
6277 @end example
6278
6279 @noindent
6280 and
6281
6282 @example
6283 @group
6284 struct larch
6285 the_larch, @hereFn{c-lineup-topmost-intro-cont}
6286 another_larch; @hereFn{c-lineup-topmost-intro-cont}
6287 @end group
6288 @end example
6289
6290 @workswith @code{topmost-intro-cont}.
6291 @end defun
6292
6293 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6294 @node Custom Line-Up, Other Indentation, Line-Up Functions, Customizing Indentation
6295 @comment node-name, next, previous, up
6296 @section Custom Line-Up Functions
6297 @cindex customization, indentation functions
6298 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6299
6300 The most flexible way to customize indentation is by writing custom
6301 line-up functions, and associating them with specific syntactic
6302 symbols (@pxref{c-offsets-alist}). Depending on the effect you want,
6303 it might be better to write a @code{c-special-indent-hook} function
6304 rather than a line-up function (@pxref{Other Indentation}).
6305
6306 @ccmode{} comes with an extensive set of predefined line-up functions,
6307 not all of which are used by the default styles. So there's a good
6308 chance the function you want already exists. @xref{Line-Up
6309 Functions}, for a list of them. If you write your own line-up
6310 function, it's probably a good idea to start working from one of these
6311 predefined functions, which can be found in the file
6312 @file{cc-align.el}. If you have written a line-up function that you
6313 think is generally useful, you're very welcome to contribute it;
6314 please contact @email{bug-cc-mode@@gnu.org}.
6315
6316 Line-up functions are passed a single argument, the syntactic
6317 element (see below). The return value is a @code{c-offsets-alist}
6318 offset specification: for example, an integer, a symbol such as
6319 @code{+}, a vector, @code{nil}@footnote{Returning @code{nil} is useful
6320 when the offset specification for a syntactic element is a list
6321 containing the line-up function (@pxref{c-offsets-alist}).}, or even
6322 another line-up function. Full details of these are in
6323 @ref{c-offsets-alist}.
6324
6325 Line-up functions must not move point or change the content of the
6326 buffer (except temporarily). They are however allowed to do
6327 @dfn{hidden buffer changes}, i.e. setting text properties for caching
6328 purposes etc. Buffer undo recording is disabled while they run.
6329
6330 The syntactic element passed as the parameter to a line-up function is
6331 a cons cell of the form
6332
6333 @example
6334 (@r{@var{syntactic-symbol}} . @r{@var{anchor-position}})
6335 @end example
6336
6337 @noindent
6338 @c FIXME!!! The following sentence might be better omitted, since the
6339 @c information is in the cross reference "Syntactic Analysis". 2005/10/2.
6340 where @var{syntactic-symbol} is the symbol that the function was
6341 called for, and @var{anchor-position} is the anchor position (if any)
6342 for the construct that triggered the syntactic symbol
6343 (@pxref{Syntactic Analysis}). This cons cell is how the syntactic
6344 element of a line used to be represented in @ccmode{} 5.28 and
6345 earlier. Line-up functions are still passed this cons cell, so as to
6346 preserve compatibility with older configurations. In the future, we
6347 may decide to convert to using the full list format---you can prepare
6348 your setup for this by using the access functions
6349 (@code{c-langelem-sym}, etc.) described below.
6350
6351 @vindex c-syntactic-element
6352 @vindex syntactic-element (c-)
6353 @vindex c-syntactic-context
6354 @vindex syntactic-context (c-)
6355 Some syntactic symbols, e.g. @code{arglist-cont-nonempty}, have more
6356 info in the syntactic element - typically other positions that can be
6357 interesting besides the anchor position. That info can't be accessed
6358 through the passed argument, which is a cons cell. Instead, you can
6359 get this information from the variable @code{c-syntactic-element},
6360 which is dynamically bound to the complete syntactic element. The
6361 variable @code{c-syntactic-context} might also be useful - it gets
6362 dynamically bound to the complete syntactic context. @xref{Custom
6363 Braces}.
6364
6365 @ccmode{} provides a few functions to access parts of syntactic
6366 elements in a more abstract way. Besides making the code easier to
6367 read, they also hide the difference between the old cons cell form
6368 used in the line-up function argument and the new list form used in
6369 @code{c-syntactic-element} and everywhere else. The functions are:
6370
6371 @defun c-langelem-sym langelem
6372 @findex langelem-sym (c-)
6373 Return the syntactic symbol in @var{langelem}.
6374 @end defun
6375
6376 @defun c-langelem-pos langelem
6377 @findex langelem-pos (c-)
6378 Return the anchor position in @var{langelem}, or nil if there is none.
6379 @end defun
6380
6381 @defun c-langelem-col langelem &optional preserve-point
6382 @findex langelem-col (c-)
6383 Return the column of the anchor position in @var{langelem}. Also move
6384 the point to that position unless @var{preserve-point} is
6385 non-@code{nil}.
6386 @end defun
6387
6388 @defun c-langelem-2nd-pos langelem
6389 @findex langelem-2nd-pos (c-)
6390 Return the secondary position in @var{langelem}, or @code{nil} if there
6391 is none.
6392
6393 Note that the return value of this function is always @code{nil} if
6394 @var{langelem} is in the old cons cell form. Thus this function is
6395 only meaningful when used on syntactic elements taken from
6396 @code{c-syntactic-element} or @code{c-syntactic-context}.
6397 @end defun
6398
6399 Custom line-up functions can be as simple or as complex as you like, and
6400 any syntactic symbol that appears in @code{c-offsets-alist} can have a
6401 custom line-up function associated with it.
6402
6403 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6404 @node Other Indentation, , Custom Line-Up, Customizing Indentation
6405 @comment node-name, next, previous, up
6406 @section Other Special Indentations
6407 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6408
6409 Here are the remaining odds and ends regarding indentation:
6410
6411 @defopt c-label-minimum-indentation
6412 @vindex label-minimum-indentation (c-)
6413 In @samp{gnu} style (@pxref{Built-in Styles}), a minimum indentation is
6414 imposed on lines inside code blocks. This minimum indentation is
6415 controlled by this style variable. The default value is 1.
6416
6417 @findex c-gnu-impose-minimum
6418 @findex gnu-impose-minimum (c-)
6419 It's the function @code{c-gnu-impose-minimum} that enforces this minimum
6420 indentation. It must be present on @code{c-special-indent-hook} to
6421 work.
6422 @end defopt
6423
6424 @defopt c-special-indent-hook
6425 @vindex special-indent-hook (c-)
6426 This style variable is a standard hook variable that is called after
6427 every line is indented by @ccmode{}. It is called only if
6428 @code{c-syntactic-indentation} is non-@code{nil} (which it is by
6429 default (@pxref{Indentation Engine Basics})). You can put a function
6430 on this hook to do any special indentation or ad hoc line adjustments
6431 your style dictates, such as adding extra indentation to constructors
6432 or destructor declarations in a class definition, etc. Sometimes it
6433 is better to write a custom Line-up Function instead (@pxref{Custom
6434 Line-Up}).
6435
6436 When the indentation engine calls this hook, the variable
6437 @code{c-syntactic-context} is bound to the current syntactic context
6438 (i.e. what you would get by typing @kbd{C-c C-s} on the source line.
6439 @xref{Custom Braces}.). Note that you should not change point or mark
6440 inside a @code{c-special-indent-hook} function, i.e. you'll probably
6441 want to wrap your function in a @code{save-excursion}@footnote{The
6442 numerical value returned by @code{point} will change if you change the
6443 indentation of the line within a @code{save-excursion} form, but point
6444 itself will still be over the same piece of text.}.
6445
6446 Setting @code{c-special-indent-hook} in style definitions is handled
6447 slightly differently from other variables---A style can only add
6448 functions to this hook, not remove them. @xref{Style Variables}.
6449 @end defopt
6450
6451
6452 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6453 @node Custom Macros, Odds and Ends, Customizing Indentation, Top
6454 @comment node-name, next, previous, up
6455 @chapter Customizing Macros
6456 @cindex macros
6457 @cindex preprocessor directives
6458 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6459
6460 Normally, the lines in a multi-line macro are indented relative to
6461 each other as though they were code. You can suppress this behaviour
6462 by setting the following user option:
6463
6464 @defopt c-syntactic-indentation-in-macros
6465 @vindex syntactic-indentation-in-macros (c-)
6466 Enable syntactic analysis inside macros, which is the default. If this
6467 is @code{nil}, all lines inside macro definitions are analyzed as
6468 @code{cpp-macro-cont}.
6469 @end defopt
6470
6471 @ccmode{} provides some tools to help keep the line continuation
6472 backslashes in macros neat and tidy. Their precise action is
6473 customized with these variables:
6474
6475 @defopt c-backslash-column
6476 @vindex backslash-column (c-)
6477 @defoptx c-backslash-max-column
6478 @vindex backslash-max-column (c-)
6479 These variables control the alignment columns for line continuation
6480 backslashes in multiline macros. They are used by the functions that
6481 automatically insert or align such backslashes,
6482 e.g. @code{c-backslash-region} and @code{c-context-line-break}.
6483
6484 @code{c-backslash-column} specifies the minimum column for the
6485 backslashes. If any line in the macro goes past this column, then the
6486 next tab stop (i.e. next multiple of @code{tab-width}) in that line is
6487 used as the alignment column for all the backslashes, so that they
6488 remain in a single column. However, if any lines go past
6489 @code{c-backslash-max-column} then the backslashes in the rest of the
6490 macro will be kept at that column, so that the lines which are too
6491 long ``stick out'' instead.
6492
6493 Don't ever set these variables to @code{nil}. If you want to disable
6494 the automatic alignment of backslashes, use
6495 @code{c-auto-align-backslashes}.
6496 @end defopt
6497
6498 @defopt c-auto-align-backslashes
6499 @vindex auto-align-backslashes (c-)
6500 Align automatically inserted line continuation backslashes if
6501 non-@code{nil}. When line continuation backslashes are inserted
6502 automatically for line breaks in multiline macros, e.g. by
6503 @code{c-context-line-break}, they are aligned with the other
6504 backslashes in the same macro if this flag is set.
6505
6506 If @code{c-auto-align-backslashes} is @code{nil}, automatically
6507 inserted backslashes are preceded by a single space, and backslashes
6508 get aligned only when you explicitly invoke the command
6509 @code{c-backslash-region} (@kbd{C-c C-\}).
6510 @end defopt
6511
6512 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6513 @node Odds and Ends, Sample .emacs File, Custom Macros, Top
6514 @comment node-name, next, previous, up
6515 @chapter Odds and Ends
6516 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6517
6518 The stuff that didn't fit in anywhere else is documented here.
6519
6520 @defopt c-require-final-newline
6521 @vindex require-final-newline (c-)
6522 Controls whether a final newline is enforced when the file is saved.
6523 The value is an association list that for each language mode specifies
6524 the value to give to @code{require-final-newline} (@pxref{Saving
6525 Buffers,,, @lispref{}, @lispreftitle{}}) at mode initialization. If a
6526 language isn't present on the association list, CC Mode won't touch
6527 @code{require-final-newline} in buffers for that language.
6528
6529 The default is to set @code{require-final-newline} to @code{t} in the
6530 languages that mandate that source files should end with newlines.
6531 These are C, C++ and Objective-C.
6532 @end defopt
6533
6534 @defopt c-echo-syntactic-information-p
6535 @vindex echo-syntactic-information-p (c-)
6536 If non-@code{nil}, the syntactic analysis for the current line is shown
6537 in the echo area when it's indented (unless
6538 @code{c-syntactic-indentation} is @code{nil}). That's useful when
6539 finding out which syntactic symbols to modify to get the indentation you
6540 want.
6541 @end defopt
6542
6543 @defopt c-report-syntactic-errors
6544 @vindex report-syntactic-errors (c-)
6545 If non-@code{nil}, certain syntactic errors are reported with a ding and
6546 a message, for example when an @code{else} is indented for which there
6547 is no corresponding @code{if}.
6548
6549 Note however that @ccmode{} doesn't make any special effort to check for
6550 syntactic errors; that's the job of the compiler. The reason it can
6551 report cases like the one above is that it can't find the correct
6552 anchoring position to indent the line in that case.
6553 @end defopt
6554
6555
6556 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6557 @node Sample .emacs File, Performance Issues, Odds and Ends, Top
6558 @comment node-name, next, previous, up
6559 @appendix Sample .emacs File
6560 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6561
6562 Here's a sample .emacs file fragment that might help you along the way.
6563 Just copy this region and paste it into your .emacs file. You might want
6564 to change some of the actual values.
6565
6566 @verbatim
6567 ;; Make a non-standard key binding. We can put this in
6568 ;; c-mode-base-map because c-mode-map, c++-mode-map, and so on,
6569 ;; inherit from it.
6570 (defun my-c-initialization-hook ()
6571 (define-key c-mode-base-map "\C-m" 'c-context-line-break))
6572 (add-hook 'c-initialization-hook 'my-c-initialization-hook)
6573
6574 ;; offset customizations not in my-c-style
6575 ;; This will take precedence over any setting of the syntactic symbol
6576 ;; made by a style.
6577 (setq c-offsets-alist '((member-init-intro . ++)))
6578
6579 ;; Create my personal style.
6580 (defconst my-c-style
6581 '((c-tab-always-indent . t)
6582 (c-comment-only-line-offset . 4)
6583 (c-hanging-braces-alist . ((substatement-open after)
6584 (brace-list-open)))
6585 (c-hanging-colons-alist . ((member-init-intro before)
6586 (inher-intro)
6587 (case-label after)
6588 (label after)
6589 (access-label after)))
6590 (c-cleanup-list . (scope-operator
6591 empty-defun-braces
6592 defun-close-semi))
6593 (c-offsets-alist . ((arglist-close . c-lineup-arglist)
6594 (substatement-open . 0)
6595 (case-label . 4)
6596 (block-open . 0)
6597 (knr-argdecl-intro . -)))
6598 (c-echo-syntactic-information-p . t))
6599 "My C Programming Style")
6600 (c-add-style "PERSONAL" my-c-style)
6601
6602 ;; Customizations for all modes in CC Mode.
6603 (defun my-c-mode-common-hook ()
6604 ;; set my personal style for the current buffer
6605 (c-set-style "PERSONAL")
6606 ;; other customizations
6607 (setq tab-width 8
6608 ;; this will make sure spaces are used instead of tabs
6609 indent-tabs-mode nil)
6610 ;; we like auto-newline, but not hungry-delete
6611 (c-toggle-auto-newline 1))
6612 (add-hook 'c-mode-common-hook 'my-c-mode-common-hook)
6613 @end verbatim
6614
6615 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6616 @node Performance Issues, Limitations and Known Bugs, Sample .emacs File, Top
6617 @comment node-name, next, previous, up
6618 @chapter Performance Issues
6619 @cindex performance
6620 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6621
6622 @comment FIXME: (ACM, 2003/5/24). Check whether AWK needs mentioning here.
6623
6624 C and its derivative languages are highly complex creatures. Often,
6625 ambiguous code situations arise that require @ccmode{} to scan large
6626 portions of the buffer to determine syntactic context. Such
6627 pathological code can cause @ccmode{} to perform fairly badly. This
6628 section gives some insight in how @ccmode{} operates, how that interacts
6629 with some coding styles, and what you can use to improve performance.
6630
6631 The overall goal is that @ccmode{} shouldn't be overly slow (i.e. take
6632 more than a fraction of a second) in any interactive operation.
6633 I.e. it's tuned to limit the maximum response time in single operations,
6634 which is sometimes at the expense of batch-like operations like
6635 reindenting whole blocks. If you find that @ccmode{} gradually gets
6636 slower and slower in certain situations, perhaps as the file grows in
6637 size or as the macro or comment you're editing gets bigger, then chances
6638 are that something isn't working right. You should consider reporting
6639 it, unless it's something that's mentioned in this section.
6640
6641 Because @ccmode{} has to scan the buffer backwards from the current
6642 insertion point, and because C's syntax is fairly difficult to parse in
6643 the backwards direction, @ccmode{} often tries to find the nearest
6644 position higher up in the buffer from which to begin a forward scan
6645 (it's typically an opening or closing parenthesis of some kind). The
6646 farther this position is from the current insertion point, the slower it
6647 gets.
6648
6649 @findex beginning-of-defun
6650 In earlier versions of @ccmode{}, we used to recommend putting the
6651 opening brace of a top-level construct@footnote{E.g. a function in C,
6652 or outermost class definition in C++ or Java.} into the leftmost
6653 column. Earlier still, this used to be a rigid Emacs constraint, as
6654 embodied in the @code{beginning-of-defun} function. @ccmode now
6655 caches syntactic information much better, so that the delay caused by
6656 searching for such a brace when it's not in column 0 is minimal,
6657 except perhaps when you've just moved a long way inside the file.
6658
6659 @findex defun-prompt-regexp
6660 @vindex c-Java-defun-prompt-regexp
6661 @vindex Java-defun-prompt-regexp (c-)
6662 A special note about @code{defun-prompt-regexp} in Java mode: The common
6663 style is to hang the opening braces of functions and classes on the
6664 right side of the line, and that doesn't work well with the Emacs
6665 approach. @ccmode{} comes with a constant
6666 @code{c-Java-defun-prompt-regexp} which tries to define a regular
6667 expression usable for this style, but there are problems with it. In
6668 some cases it can cause @code{beginning-of-defun} to hang@footnote{This
6669 has been observed in Emacs 19.34 and XEmacs 19.15.}. For this reason,
6670 it is not used by default, but if you feel adventurous, you can set
6671 @code{defun-prompt-regexp} to it in your mode hook. In any event,
6672 setting and relying on @code{defun-prompt-regexp} will definitely slow
6673 things down because (X)Emacs will be doing regular expression searches a
6674 lot, so you'll probably be taking a hit either way!
6675
6676 @ccmode{} maintains a cache of the opening parentheses of the blocks
6677 surrounding the point, and it adapts that cache as the point is moved
6678 around. That means that in bad cases it can take noticeable time to
6679 indent a line in a new surrounding, but after that it gets fast as long
6680 as the point isn't moved far off. The farther the point is moved, the
6681 less useful is the cache. Since editing typically is done in ``chunks''
6682 rather than on single lines far apart from each other, the cache
6683 typically gives good performance even when the code doesn't fit the
6684 Emacs approach to finding the defun starts.
6685
6686 @vindex c-enable-xemacs-performance-kludge-p
6687 @vindex enable-xemacs-performance-kludge-p (c-)
6688 XEmacs users can set the variable
6689 @code{c-enable-xemacs-performance-kludge-p} to non-@code{nil}. This
6690 tells @ccmode{} to use XEmacs-specific built-in functions which, in some
6691 circumstances, can locate the top-most opening brace much more quickly than
6692 @code{beginning-of-defun}. Preliminary testing has shown that for
6693 styles where these braces are hung (e.g. most JDK-derived Java styles),
6694 this hack can improve performance of the core syntax parsing routines
6695 from 3 to 60 times. However, for styles which @emph{do} conform to
6696 Emacs' recommended style of putting top-level braces in column zero,
6697 this hack can degrade performance by about as much. Thus this variable
6698 is set to @code{nil} by default, since the Emacs-friendly styles should
6699 be more common (and encouraged!). Note that this variable has no effect
6700 in Emacs since the necessary built-in functions don't exist (in Emacs
6701 22.1 as of this writing in February 2007).
6702
6703 Text properties are used to speed up skipping over syntactic whitespace,
6704 i.e. comments and preprocessor directives. Indenting a line after a
6705 huge macro definition can be slow the first time, but after that the
6706 text properties are in place and it should be fast (even after you've
6707 edited other parts of the file and then moved back).
6708
6709 Font locking can be a CPU hog, especially the font locking done on
6710 decoration level 3 which tries to be very accurate. Note that that
6711 level is designed to be used with a font lock support mode that only
6712 fontifies the text that's actually shown, i.e. Lazy Lock or Just-in-time
6713 Lock mode, so make sure you use one of them. Fontification of a whole
6714 buffer with some thousand lines can often take over a minute. That is
6715 a known weakness; the idea is that it never should happen.
6716
6717 The most effective way to speed up font locking is to reduce the
6718 decoration level to 2 by setting @code{font-lock-maximum-decoration}
6719 appropriately. That level is designed to be as pretty as possible
6720 without sacrificing performance. @xref{Font Locking Preliminaries}, for
6721 more info.
6722
6723
6724 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6725 @node Limitations and Known Bugs, FAQ, Performance Issues, Top
6726 @comment node-name, next, previous, up
6727 @chapter Limitations and Known Bugs
6728 @cindex limitations
6729 @cindex bugs
6730 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6731
6732 @itemize @bullet
6733 @item
6734 @ccmode{} doesn't support trigraphs. (These are character sequences
6735 such as @samp{??(}, which represents @samp{[}. They date from a time
6736 when some character sets didn't have all the characters that C needs,
6737 and are now utterly obsolete.)
6738
6739 @item
6740 There is no way to apply auto newline settings (@pxref{Auto-newlines})
6741 on already typed lines. That's only a feature to ease interactive
6742 editing.
6743
6744 To generalize this issue a bit: @ccmode{} is not intended to be used as
6745 a reformatter for old code in some more or less batch-like way. With
6746 the exception of some functions like @code{c-indent-region}, it's only
6747 geared to be used interactively to edit new code. There's currently no
6748 intention to change this goal.
6749
6750 If you want to reformat old code, you're probably better off using some
6751 other tool instead, e.g. @ref{Top, , GNU indent, indent, The `indent'
6752 Manual}, which has more powerful reformatting capabilities than
6753 @ccmode{}.
6754
6755 @item
6756 The support for C++ templates (in angle brackets) is not yet complete.
6757 When a non-nested template is used in a declaration, @ccmode{} indents
6758 it and font-locks it OK. Templates used in expressions, and nested
6759 templates do not fare so well. Sometimes a workaround is to refontify
6760 the expression after typing the closing @samp{>}.
6761
6762 @item
6763 On loading @ccmode{}, sometimes this error message appears:
6764
6765 @example
6766 File mode specification error: (void-variable c-font-lock-keywords-3)
6767 @end example
6768
6769 This is due to a bug in the function @code{eval-after-load} in some
6770 versions of (X)Emacs. It can manifest itself when there is a symbolic
6771 link in the path of the directory which contains (X)Emacs. As a
6772 workaround, put the following into your @file{.emacs} file, fairly
6773 early on:
6774
6775 @example
6776 (defun my-load-cc-fonts ()
6777 (require "cc-fonts"))
6778 (add-hook 'c-initialization-hook 'my-load-cc-fonts)
6779 @end example
6780 @end itemize
6781
6782 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6783 @node FAQ, Updating CC Mode, Limitations and Known Bugs, Top
6784 @comment node-name, next, previous, up
6785 @appendix Frequently Asked Questions
6786 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6787
6788 @itemize @bullet
6789 @item
6790 @emph{How can I change the indent level from 4 spaces to 2 spaces?}
6791
6792 Set the variable @code{c-basic-offset}. @xref{Getting Started}.
6793
6794 @item
6795 @kindex RET
6796 @kindex C-j
6797 @emph{Why doesn't the @kbd{RET} key indent the new line?}
6798
6799 Emacs' convention is that @kbd{RET} just adds a newline, and that
6800 @kbd{C-j} adds a newline and indents it. You can make @kbd{RET} do this
6801 too by adding this to your @code{c-initialization-hook}:
6802
6803 @example
6804 (define-key c-mode-base-map "\C-m" 'c-context-line-break)
6805 @end example
6806
6807 @xref{Getting Started}. This is a very common question. If you want
6808 this to be the default behavior, don't lobby us, lobby RMS! @t{:-)}
6809
6810 @item
6811 @emph{How do I stop my code jumping all over the place when I type?}
6812
6813 Deactivate ``electric minor mode'' with @kbd{C-c C-l}. @xref{Getting
6814 Started}.
6815
6816 @item
6817 @kindex C-x h
6818 @kindex C-M-\
6819 @emph{How do I reindent the whole file?}
6820
6821 Visit the file and hit @kbd{C-x h} to mark the whole buffer. Then hit
6822 @kbd{C-M-\}. @xref{Indentation Commands}.
6823
6824 @item
6825 @kindex C-M-q
6826 @kindex C-M-u
6827 @emph{How do I reindent the current block?}
6828
6829 First move to the brace which opens the block with @kbd{C-M-u}, then
6830 reindent that expression with @kbd{C-M-q}. @xref{Indentation
6831 Commands}.
6832
6833 @item
6834 @emph{I put @code{(c-set-offset 'substatement-open 0)} in my
6835 @file{.emacs} file but I get an error saying that @code{c-set-offset}'s
6836 function definition is void. What's wrong?}
6837
6838 This means that @ccmode{} hasn't yet been loaded into your Emacs
6839 session by the time the @code{c-set-offset} call is reached, most
6840 likely because @ccmode{} is being autoloaded. Instead of putting the
6841 @code{c-set-offset} line in your top-level @file{.emacs} file, put it
6842 in your @code{c-initialization-hook} (@pxref{CC Hooks}), or simply
6843 modify @code{c-offsets-alist} directly:
6844
6845 @example
6846 (setq c-offsets-alist '((substatement-open . 0)))
6847 @end example
6848
6849 @item
6850 @cindex open paren in column zero
6851 @emph{I have an open paren character at column zero inside a comment or
6852 multiline string literal, and it causes the fontification and/or
6853 indentation to go haywire. What gives?}
6854
6855 It's due to the ad-hoc rule in (X)Emacs that such open parens always
6856 start defuns (which translates to functions, classes, namespaces or any
6857 other top-level block constructs in the @ccmode{} languages).
6858 @ifset XEMACS
6859 @xref{Defuns,,, xemacs, XEmacs User's Manual}, for details.
6860 @end ifset
6861 @ifclear XEMACS
6862 @xref{Left Margin Paren,,, emacs, GNU Emacs Manual}, for details
6863 (@xref{Defuns,,, emacs, GNU Emacs Manual}, in the Emacs 20 manual).
6864 @end ifclear
6865
6866 This heuristic is built into the core syntax analysis routines in
6867 (X)Emacs, so it's not really a @ccmode{} issue. However, in Emacs
6868 21.1 it became possible to turn it off@footnote{Using the variable
6869 @code{open-paren-in-column-0-is-defun-start}.} and @ccmode{} does so
6870 there since it's got its own system to keep track of blocks.
6871
6872 @end itemize
6873
6874
6875 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6876 @node Updating CC Mode, Mailing Lists and Bug Reports, FAQ, Top
6877 @comment node-name, next, previous, up
6878 @appendix Getting the Latest CC Mode Release
6879 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6880
6881 @ccmode{} has been standard with all versions of Emacs since 19.34 and
6882 of XEmacs since 19.16.
6883
6884 @cindex web site
6885 Due to release schedule skew, it is likely that all of these Emacsen
6886 have old versions of @ccmode{} and so should be upgraded. Access to the
6887 @ccmode{} source code, as well as more detailed information on Emacsen
6888 compatibility, etc. are all available on the web site:
6889
6890 @quotation
6891 @uref{http://cc-mode.sourceforge.net/}
6892 @end quotation
6893
6894
6895 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6896 @node Mailing Lists and Bug Reports, GNU Free Documentation License, Updating CC Mode, Top
6897 @comment node-name, next, previous, up
6898 @appendix Mailing Lists and Submitting Bug Reports
6899 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6900
6901 @kindex C-c C-b
6902 @findex c-submit-bug-report
6903 @findex submit-bug-report (c-)
6904 To report bugs, use the @kbd{C-c C-b} (bound to
6905 @code{c-submit-bug-report}) command. This provides vital information
6906 we need to reproduce your problem. Make sure you include a concise,
6907 but complete code example. Please try to boil your example down to
6908 just the essential code needed to reproduce the problem, and include
6909 an exact recipe of steps needed to expose the bug. Be especially sure
6910 to include any code that appears @emph{before} your bug example, if
6911 you think it might affect our ability to reproduce it.
6912
6913 Please try to produce the problem in an Emacs instance without any
6914 customizations loaded (i.e. start it with the @samp{-q --no-site-file}
6915 arguments). If it works correctly there, the problem might be caused
6916 by faulty customizations in either your own or your site
6917 configuration. In that case, we'd appreciate it if you isolate the
6918 Emacs Lisp code that triggers the bug and include it in your report.
6919
6920 @cindex bug report mailing list
6921 Bug reports should be sent to @email{bug-cc-mode@@gnu.org}. You can
6922 also send other questions and suggestions (kudos? @t{;-)} to that
6923 address. It's a mailing list which you can join or browse an archive
6924 of; see the web site at @uref{http://cc-mode.sourceforge.net/} for
6925 further details.
6926
6927 @cindex announcement mailing list
6928 If you want to get announcements of new @ccmode{} releases, send the
6929 word @emph{subscribe} in the body of a message to
6930 @email{cc-mode-announce-request@@lists.sourceforge.net}. It's possible
6931 to subscribe from the web site too. Announcements will also be posted
6932 to the Usenet newsgroups @code{gnu.emacs.sources}, @code{comp.emacs},
6933 @code{comp.emacs.xemacs}, @code{comp.lang.c}, @code{comp.lang.c++},
6934 @code{comp.lang.objective-c}, @code{comp.lang.java.softwaretools},
6935 @code{comp.lang.idl}, and @code{comp.lang.awk}.
6936 @c There is no newsgroup for Pike. :-(
6937
6938
6939 @node GNU Free Documentation License, Command and Function Index, Mailing Lists and Bug Reports, Top
6940 @appendix GNU Free Documentation License
6941 @include doclicense.texi
6942
6943
6944 @c Removed the tentative node "Mode Initialization" from here, 2005/8/27.
6945 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6946 @node Command and Function Index, Variable Index, GNU Free Documentation License, Top
6947 @comment node-name, next, previous, up
6948 @unnumbered Command and Function Index
6949 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6950
6951 Since most @ccmode{} commands are prepended with the string
6952 @samp{c-}, each appears under its @code{c-@var{thing}} name and its
6953 @code{@var{thing} (c-)} name.
6954 @iftex
6955 @sp 2
6956 @end iftex
6957 @printindex fn
6958
6959
6960 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6961 @node Variable Index, Concept and Key Index, Command and Function Index, Top
6962 @comment node-name, next, previous, up
6963 @unnumbered Variable Index
6964 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6965
6966 Since most @ccmode{} variables are prepended with the string
6967 @samp{c-}, each appears under its @code{c-@var{thing}} name and its
6968 @code{@var{thing} (c-)} name.
6969 @iftex
6970 @sp 2
6971 @end iftex
6972 @printindex vr
6973
6974
6975 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6976 @node Concept and Key Index, , Variable Index, Top
6977 @comment node-name, next, previous, up
6978 @unnumbered Concept and Key Index
6979 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6980
6981 @printindex cp
6982
6983
6984 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6985 @comment Epilogue.
6986 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6987
6988 @iftex
6989 @page
6990 @summarycontents
6991 @contents
6992 @end iftex
6993
6994 @bye
6995
6996 @ignore
6997 arch-tag: c4cab162-5e57-4366-bdce-4a9db2fc97f0
6998 @end ignore