2 @c Notes to self regarding line handling:
4 @c Empty lines are often significant before @end directives; avoid them.
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
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:
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.
23 @comment TBD: Document the finer details of statement anchoring?
25 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
26 @comment %**start of header (This is for running Texinfo on a region)
27 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
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 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
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.
41 makeinfo -DXEMACS cc-mode.texi
44 ## You may need to set up the environment variable TEXINPUTS so
45 ## that tex can find the file texinfo.tex - See the tex
48 texi2dvi -t "@set XEMACS " cc-mode.texi
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
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
61 makeinfo --docbook --no-split --paragraph-indent=0 \
63 makeinfo --docbook --no-split --paragraph-indent=0 \
67 makeinfo --xml --no-split --paragraph-indent=0 \
69 makeinfo --xml --no-split --paragraph-indent=0 \
72 #### (You must be in the same directory as the viewed file.)
81 @comment No overfull hbox marks in the dvi file.
84 @setfilename ../../info/ccmode.info
85 @settitle CC Mode Manual
86 @include docstyle.texi
89 @c The following four macros generate the filenames and titles of the
90 @c main (X)Emacs manual and the Elisp/Lispref manual. Leave the
91 @c Texinfo variable 'XEMACS' unset to generate a GNU Emacs version, set it
92 @c to generate an XEmacs version, e.g., with
93 @c "makeinfo -DXEMACS cc-mode.texi".
105 XEmacs Lisp Reference Manual
120 GNU Emacs Lisp Reference Manual
129 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
130 @comment @setchapternewpage odd !! we don't want blank pages !!
131 @comment %**end of header (This is for running Texinfo on a region)
132 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
135 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
137 @comment Texinfo manual for CC Mode
138 @comment Generated from the original README file by Krishna Padmasola
139 @comment <krishna@earth-gw.njit.edu>
142 @comment Barry A. Warsaw
143 @comment Martin Stjernholm
144 @comment Alan Mackenzie
146 @comment Maintained by Martin Stjernholm and Alan Mackenzie <bug-cc-mode@gnu.org>
148 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
150 @comment Define an index for syntactic symbols.
153 @comment Combine key, syntactic symbol and concept indices into one.
158 This manual is for CC Mode in Emacs.
160 Copyright @copyright{} 1995--2018 Free Software Foundation, Inc.
163 Permission is granted to copy, distribute and/or modify this document
164 under the terms of the GNU Free Documentation License, Version 1.3 or
165 any later version published by the Free Software Foundation; with no
166 Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'',
167 and with the Back-Cover Texts as in (a) below. A copy of the license
168 is included in the section entitled ``GNU Free Documentation License''.
170 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
171 modify this GNU manual.''
175 @comment Info directory entry for use by install-info. The indentation
176 @comment here is by request from the FSF folks.
177 @dircategory Emacs editing modes
179 * CC Mode: (ccmode). Emacs mode for editing C, C++, Objective-C,
180 Java, Pike, AWK, and CORBA IDL code.
183 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
184 @comment TeX title page
185 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
190 @center @titlefont{CC Mode 5.32}
192 @center A GNU Emacs mode for editing C and C-like languages
194 @center Barry A. Warsaw, Martin Stjernholm, Alan Mackenzie
197 @vskip 0pt plus 1filll
200 This manual was generated from cc-mode.texi, which is distributed with Emacs,
201 or can be downloaded from @url{https://savannah.gnu.org/projects/emacs/}.
204 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
205 @comment The Top node contains the master menu for the Info file.
206 @comment This appears only in the Info file, not the printed manual.
207 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
212 @node Top, Introduction, (dir), (dir)
213 @comment node-name, next, previous, up
218 @ccmode{} is a GNU Emacs mode for editing files containing C, C++,
219 Objective-C, Java, CORBA IDL (and the variants PSDL and CIDL), Pike
220 and AWK code. It provides syntax-based indentation, font locking, and
221 has several handy commands and some minor modes to make the editing
222 easier. It does not provide tools to look up and navigate between
223 functions, classes, etc.; there are other packages for that.
228 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
229 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
238 * Custom Filling and Breaking::
239 * Custom Auto-newlines::
241 * Indentation Engine Basics::
242 * Customizing Indentation::
246 * Performance Issues::
247 * Limitations and Known Bugs::
250 * Mailing Lists and Bug Reports::
251 * GNU Free Documentation License::
252 * Command and Function Index::
254 * Concept and Key Index::
257 --- The Detailed Node Listing ---
261 * Indentation Commands::
263 * Movement Commands::
264 * Filling and Breaking::
268 * Hungry WS Deletion::
274 * Font Locking Preliminaries::
277 * Misc Font Locking::
278 * AWK Mode Font Locking::
291 * Guessing the Style::
294 Customizing Auto-newlines
298 * Hanging Semicolons and Commas::
304 Indentation Engine Basics
306 * Syntactic Analysis::
307 * Syntactic Symbols::
308 * Indentation Calculation::
314 * Conditional Construct Symbols::
315 * Switch Statement Symbols::
316 * Brace List Symbols::
317 * External Scope Symbols::
318 * Paren List Symbols::
320 * Multiline Macro Symbols::
321 * Objective-C Method Symbols::
323 * Statement Block Symbols::
326 Customizing Indentation
329 * Interactive Customization::
330 * Line-Up Functions::
332 * Other Indentation::
336 * Brace/Paren Line-Up::
345 * Macro Backslashes::
351 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
352 @node Introduction, Overview, Top, Top
353 @comment node-name, next, previous, up
354 @chapter Introduction
355 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
359 @cindex @file{awk-mode.el}
360 @cindex @file{c-mode.el}
361 @cindex @file{c++-mode.el}
363 Welcome to @ccmode{}, a GNU Emacs mode for editing files containing C,
364 C++, Objective-C, Java, CORBA IDL (and the variants CORBA PSDL and
365 CIDL), Pike and AWK code. This incarnation of the mode is descended
366 from @file{c-mode.el} (also called ``Boring Old C Mode'' or BOCM
367 @t{:-)}, @file{c++-mode.el} version 2, which Barry Warsaw had been
368 maintaining since 1992, and @file{awk-mode.el}, a long neglected mode
369 in the (X)Emacs base.
371 Late in 1997, Martin Stjernholm joined Barry on the @ccmode{}
372 Maintainers Team, and implemented the Pike support. In 2000 Martin
373 took over as the sole maintainer. In 2001 Alan Mackenzie joined the
374 team, implementing AWK support in version 5.30. @ccmode{} did not
375 originally contain the font lock support for its languages; that
376 was added in version 5.30.
378 This manual describes @ccmode{}
379 @comment The following line must appear on its own, so that the
381 @comment Release.py script can update the version number automatically
383 @ccmode{} supports the editing of C, C++, Objective-C,
384 Java, CORBA's Interface Definition Language, Pike@footnote{A C-like
385 scripting language with its roots in the LPC language used in some MUD
386 engines. See @uref{http://pike.ida.liu.se/}.} and AWK files. In this
387 way, you can easily set up consistent font locking and coding styles for
388 use in editing all of these languages, although AWK is not yet as
389 uniformly integrated as the other languages.
398 Note that the name of this package is ``@ccmode{}'', but there is no top
399 level @code{cc-mode} entry point. All of the variables, commands, and
400 functions in @ccmode{} are prefixed with @code{c-@var{thing}}, and
401 @code{c-mode}, @code{c++-mode}, @code{objc-mode}, @code{java-mode},
402 @code{idl-mode}, @code{pike-mode}, and @code{awk-mode} entry points are
403 provided. This package is intended to be a replacement for
404 @file{c-mode.el}, @file{c++-mode.el} and @file{awk-mode.el}.
406 A special word of thanks goes to Krishna Padmasola for his work in
407 converting the original @file{README} file to Texinfo format. I'd
408 also like to thank all the @ccmode{} victims who help enormously
409 during the early beta stages of @ccmode{}'s development.
411 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
412 @node Overview, Getting Started, Introduction, Top
413 @comment node-name, next, previous, up@cindex organization of the manual
414 @chapter Overview of the Manual
415 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
418 The manual starts with several introductory chapters (including this
422 The next chunk of the manual describes the day to day @emph{use} of
423 @ccmode{} (as contrasted with how to customize it).
427 The chapter ``Commands'' describes in detail how to use (nearly) all
428 of @ccmode{}'s features. There are extensive cross-references from
429 here to the corresponding sections later in the manual which tell you
430 how to customize these features.
433 ``Font Locking'' describes how ``syntax highlighting'' is applied to
434 your buffers. It is mainly background information and can be skipped
435 over at a first reading.
439 The next chunk of the manual describes how to @emph{customize}
440 @ccmode{}. Typically, an overview of a topic is given at the chapter
441 level, then the sections and subsections describe the material in
446 The chapter ``Configuration Basics'' tells you @emph{how} to write
447 customizations: whether in hooks, in styles, in both, or in neither,
448 depending on your needs. It describes the @ccmode{} style system and
449 lists the standard styles that @ccmode{} supplies.
452 The next few chapters describe in detail how to customize the various
453 features of @ccmode{}.
456 Finally, there is a sample @file{.emacs} fragment, which might help you
457 in creating your own customization.
461 The manual ends with ``this and that'', things that don't fit cleanly
462 into any of the previous chunks.
466 Two chapters discuss the performance of @ccmode{} and known
470 The FAQ contains a list of common problems and questions.
473 The next two chapters tell you how to get in touch with the @ccmode{}
474 project: whether for updating @ccmode{} or submitting bug reports.
478 Finally, there are the customary indices.
480 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
481 @node Getting Started, Commands, Overview, Top
482 @comment node-name, next, previous, up
483 @chapter Getting Started
484 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
486 If you got this version of @ccmode{} with Emacs or XEmacs, it should
487 work just fine right out of the box. Note however that you might not
488 have the latest @ccmode{} release and might want to upgrade your copy
491 You should probably start by skimming through the entire Commands chapter
492 (@pxref{Commands}) to get an overview of @ccmode{}'s capabilities.
494 After trying out some commands, you may dislike some aspects of
495 @ccmode{}'s default configuration. Here is an outline of how to
496 change some of the settings that newcomers to @ccmode{} most often
501 This Lisp variable holds an integer, the number of columns @ccmode{}
502 indents nested code. To set this value to 6, customize
503 @code{c-basic-offset} or put this into your @file{.emacs}:
506 (setq c-basic-offset 6)
509 @item The (indentation) style
510 The basic ``shape'' of indentation created by @ccmode{}---by default,
511 this is @code{gnu} style (except for Java and AWK buffers). A list of
512 the available styles and their descriptions can be found in
513 @ref{Built-in Styles}. A complete specification of the @ccmode{}
514 style system, including how to create your own style, can be found in
515 the chapter @ref{Styles}. To set your style to @code{linux}, either
516 customize @code{c-default-style} or put this into your @file{.emacs}:
519 (setq c-default-style '((java-mode . "java")
524 @item Electric Indentation
525 Normally, when you type ``punctuation'' characters such as @samp{;} or
526 @samp{@{}, @ccmode{} instantly reindents the current line. This can
527 be disconcerting until you get used to it. To disable @dfn{electric
528 indentation} in the current buffer, type @kbd{C-c C-l}. Type the same
529 thing to enable it again. To have electric indentation disabled by
530 default, put the following into your @file{.emacs} file@footnote{There
531 is no ``easy customization'' facility for making this change.}:
534 (setq-default c-electric-flag nil)
538 Details of this and other similar ``Minor Modes'' appear in the
539 section @ref{Minor Modes}.
541 @item Making the @key{RET} key indent the new line
542 The standard Emacs binding for @key{RET} just adds a new line. If you
543 want it to reindent the new line as well, rebind the key. Note that
544 the action of rebinding would fail if the pertinent keymap didn't yet
545 exist---we thus need to delay the action until after @ccmode{} has
546 been loaded. Put the following code into your @file{.emacs}:
549 (defun my-make-CR-do-indent ()
550 (define-key c-mode-base-map "\C-m" 'c-context-line-break))
551 (add-hook 'c-initialization-hook 'my-make-CR-do-indent)
555 This example demonstrates the use of a very powerful @ccmode{} (and
556 Emacs) facility, the hook. The use of @ccmode{}'s hooks is described
560 All these settings should occur in your @file{.emacs} @emph{before}
561 any @ccmode{} buffers get loaded---in particular, before any call of
564 As you get to know the mode better, you may want to make more
565 ambitious changes to your configuration. For this, you should start
566 reading the chapter @ref{Config Basics}.
568 If you are upgrading an existing @ccmode{} installation, please see
569 the @file{README} file for installation details. In particular, if
570 you are going to be editing AWK files, @file{README} describes how to
571 configure your (X)Emacs so that @ccmode{} will supersede the obsolete
572 @code{awk-mode.el} which might have been supplied with your (X)Emacs.
573 @ccmode{} might not work with older versions of Emacs or XEmacs. See
574 the @ccmode{} release notes at @uref{http://cc-mode.sourceforge.net}
575 for the latest information on Emacs version and package compatibility
576 (@pxref{Updating CC Mode}).
578 @deffn Command c-version
579 @findex version @r{(c-)}
580 You can find out what version of @ccmode{} you are using by visiting a
581 C file and entering @kbd{M-x c-version @key{RET}}. You should see
582 this message in the echo area:
585 Using CC Mode version 5.XX
589 where @samp{XX} is the minor release number.
592 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
593 @node Commands, Font Locking, Getting Started, Top
594 @comment node-name, next, previous, up
596 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
598 This chapter specifies all of CC Mode's commands, and thus contains
599 nearly everything you need to know to @emph{use} @ccmode{} (as
600 contrasted with configuring it). @dfn{Commands} here means both
601 control key sequences and @dfn{electric keys}, these being characters
602 such as @samp{;} which, as well as inserting themselves into the
603 buffer, also do other things.
605 You might well want to review
607 @ref{Lists,,,@emacsman{}, @emacsmantitle{}},
610 @ref{Moving by Parens,,,@emacsman{}, @emacsmantitle{}},
612 which describes commands for moving around brace and parenthesis
617 * Indentation Commands::
619 * Movement Commands::
620 * Filling and Breaking::
624 * Hungry WS Deletion::
629 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
630 @node Indentation Commands, Comment Commands, Commands, Commands
631 @comment node-name, next, previous,up
632 @section Indentation Commands
634 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
636 The following commands reindent C constructs. Note that when you
637 change your coding style, either interactively or through some other
638 means, your file does @emph{not} automatically get reindented. You
639 will need to execute one of the following commands to see the effects
642 @cindex GNU indent program
643 Also, variables like @code{c-hanging-*} and @code{c-cleanup-list}
644 (@pxref{Custom Auto-newlines}) only affect how on-the-fly code is
645 formatted. Changing the ``hanginess'' of a brace and then
646 reindenting, will not move the brace to a different line. For this,
647 you're better off getting an external program like GNU @code{indent},
648 which will rearrange brace location, amongst other things.
650 Preprocessor directives are handled as syntactic whitespace from other
651 code, i.e., they can be interspersed anywhere without affecting the
652 indentation of the surrounding code, just like comments.
654 The code inside macro definitions is, by default, still analyzed
655 syntactically so that you get relative indentation there just as you'd
656 get if the same code was outside a macro. However, since there is no
657 hint about the syntactic context, i.e., whether the macro expands to an
658 expression, to some statements, or perhaps to whole functions, the
659 syntactic recognition can be wrong. @ccmode{} manages to figure it
660 out correctly most of the time, though.
662 Some macros, when invoked, ''have their own semicolon''. To get the
663 next line indented correctly, rather than as a continuation line,
664 @xref{Macros with ;}.
666 Reindenting large sections of code can take a long time. When
667 @ccmode{} reindents a region of code, it is essentially equivalent to
668 hitting @key{TAB} on every line of the region.
670 These commands indent code:
673 @item @kbd{@key{TAB}} (@code{c-indent-command})
675 @findex c-indent-command
676 @findex indent-command @r{(c-)}
677 This command indents the current line. That is all you need to know
678 about it for normal use.
680 @code{c-indent-command} does different things, depending on the
681 setting of @code{c-syntactic-indentation} (@pxref{Indentation Engine
686 When it's non-@code{nil} (which it normally is), the command indents
687 the line according to its syntactic context. With a prefix argument
688 (@kbd{C-u @key{TAB}}), it will re-indent the entire
689 expression@footnote{this is only useful for a line starting with a
690 comment opener or an opening brace, parenthesis, or string quote.}
691 that begins at the line's left margin.
694 When it's @code{nil}, the command indents the line by an extra
695 @code{c-basic-offset} columns. A prefix argument acts as a
696 multiplier. A bare prefix (@kbd{C-u @key{TAB}}) is equivalent to @minus{}1,
697 removing @code{c-basic-offset} columns from the indentation.
700 The precise behavior is modified by several variables: With
701 @code{c-tab-always-indent}, you can make @key{TAB} insert whitespace
702 in some circumstances---@code{c-insert-tab-function} then defines
703 precisely what sort of ``whitespace'' this will be. Set the standard
704 Emacs variable @code{indent-tabs-mode} to @code{t} if you want real
705 @samp{tab} characters to be used in the indentation, to @code{nil} if
706 you want only spaces. @xref{Just Spaces,,,@emacsman{},
709 @defopt c-tab-always-indent
710 @vindex tab-always-indent @r{(c-)}
712 This variable modifies how @key{TAB} operates.
715 When it is @code{t} (the default), @key{TAB} simply indents the
718 When it is @code{nil}, @key{TAB} (re)indents the line only if point is
719 to the left of the first non-whitespace character on the line.
720 Otherwise it inserts some whitespace (a tab or an equivalent number of
721 spaces; see below) at point.
723 With some other value, the line is reindented. Additionally, if point
724 is within a string or comment, some whitespace is inserted.
728 @defopt c-insert-tab-function
729 @vindex insert-tab-function @r{(c-)}
730 @findex tab-to-tab-stop
731 When ``some whitespace'' is inserted as described above, what actually
732 happens is that the function stored in @code{c-insert-tab-function} is
733 called. Normally, this is @code{insert-tab}, which inserts a real tab
734 character or the equivalent number of spaces (depending on
735 @code{indent-tabs-mode}). Some people, however, set
736 @code{c-insert-tab-function} to @code{tab-to-tab-stop} so as to get
737 hard tab stops when indenting.
742 The kind of indentation the next five commands do depends on the
743 setting of @code{c-syntactic-indentation} (@pxref{Indentation Engine
747 when it is non-@code{nil} (the default), the commands indent lines
748 according to their syntactic context;
750 when it is @code{nil}, they just indent each line the same amount as
751 the previous non-blank line. The commands that indent a region aren't
752 very useful in this case.
756 @item @kbd{C-M-q} (@code{c-indent-exp})
759 @findex indent-exp @r{(c-)}
760 Indents an entire balanced brace or parenthesis expression. Note that
761 point must be on the opening brace or parenthesis of the expression
764 @item @kbd{C-c C-q} (@code{c-indent-defun})
766 @findex c-indent-defun
767 @findex indent-defun @r{(c-)}
768 Indents the entire top-level function, class or macro definition
769 encompassing point. It leaves point unchanged. This function can't be
770 used to reindent a nested brace construct, such as a nested class or
771 function, or a Java method. The top-level construct being reindented
772 must be complete, i.e., it must have both a beginning brace and an ending
775 @item @kbd{C-M-\} (@code{indent-region})
777 @findex indent-region
778 Indents an arbitrary region of code. This is a standard Emacs command,
779 tailored for C code in a @ccmode{} buffer. Note, of course, that point
780 and mark must delineate the region you want to indent.
782 @item @kbd{C-M-h} (@code{c-mark-function})
784 @findex c-mark-function
785 @findex mark-function @r{(c-)}
786 While not strictly an indentation command, this is useful for marking
787 the current top-level function or class definition as the current
788 region. As with @code{c-indent-defun}, this command operates on
789 top-level constructs, and can't be used to mark say, a Java method.
792 These variables are also useful when indenting code:
794 @defopt indent-tabs-mode
795 This is a standard Emacs variable that controls how line indentation
796 is composed. When it's non-@code{nil}, tabs can be used in a line's
797 indentation, otherwise only spaces are used.
800 @defopt c-progress-interval
801 @vindex progress-interval @r{(c-)}
802 When indenting large regions of code, this variable controls how often a
803 progress message is displayed. Set this variable to @code{nil} to
804 inhibit the progress messages, or set it to an integer which is how
805 often (in seconds) progress messages are to be displayed.
808 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
809 @node Comment Commands, Movement Commands, Indentation Commands, Commands
810 @comment node-name, next, previous, up
811 @section Comment Commands
812 @cindex comments (insertion of)
813 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
815 When the commands in this section add comment delimiters, they use
816 either line comments or block comments depending on the setting of the
817 comment style (@pxref{Minor Modes}).
820 @item @kbd{C-c C-c} (@code{comment-region})
822 @findex comment-region
823 This command comments out the lines that start in the region. With a
824 negative argument, it does the opposite: it deletes the comment
825 delimiters from these lines. @xref{Multi-Line Comments,,, emacs, GNU
826 Emacs Manual}, for fuller details. @code{comment-region} isn't
827 actually part of @ccmode{}; it is given a @ccmode{} binding for
830 @item @kbd{M-;} (@code{comment-dwim} or @code{indent-for-comment} @footnote{The name of this command varies between (X)Emacs versions.})
833 @findex indent-for-comment
834 Insert a comment at the end of the current line, if none is there
835 already. Then reindent the comment according to @code{comment-column}
837 (@pxref{Options for Comments,,, emacs, GNU Emacs Manual})
840 (@pxref{Comments,,, xemacs, XEmacs User's Manual})
842 and the variables below. Finally, position the point after the
843 comment starter. @kbd{C-u M-;} kills any comment on the current line,
844 together with any whitespace before it. This is a standard Emacs
845 command, but @ccmode{} enhances it a bit with two variables:
847 @defopt c-indent-comment-alist
848 @vindex indent-comment-alist @r{(c-)}
849 @vindex comment-column
850 This style variable allows you to vary the column that @kbd{M-;} puts
851 the comment at, depending on what sort of code is on the line, and
852 possibly the indentation of any similar comment on the preceding line.
853 It is an association list that maps different types of lines to
854 actions describing how they should be handled. If a certain line type
855 isn't present on the list then the line is indented to the column
856 specified by @code{comment-column}.
858 See the documentation string for a full description of this
859 variable (use @kbd{C-h v c-indent-comment-alist}).
862 @defopt c-indent-comments-syntactically-p
863 @vindex indent-comments-syntactically-p @r{(c-)}
864 Normally, when this style variable is @code{nil}, @kbd{M-;} will
865 indent comment-only lines according to @code{c-indent-comment-alist},
866 just as it does with lines where other code precede the comments.
867 However, if you want it to act just like @key{TAB} for comment-only
868 lines you can get that by setting
869 @code{c-indent-comments-syntactically-p} to non-@code{nil}.
871 If @code{c-indent-comments-syntactically-p} is non-@code{nil} then
872 @code{c-indent-comment-alist} won't be consulted at all for comment-only
877 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
878 @node Movement Commands, Filling and Breaking, Comment Commands, Commands
879 @comment node-name, next, previous, up
880 @section Movement Commands
882 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
884 @ccmode{} contains some useful commands for moving around in C code.
887 @item @kbd{C-M-a} (@code{c-beginning-of-defun})
888 @itemx @kbd{C-M-e} (@code{c-end-of-defun})
889 @findex c-beginning-of-defun
890 @findex c-end-of-defun
891 @vindex c-defun-tactic
892 @vindex defun-tactic @r{(c-)}
894 Move to the beginning or end of the current or next function. Other
895 constructs (such as a structs or classes) which have a brace block
896 also count as ``functions'' here. To move over several functions, you
897 can give these commands a repeat count.
899 The start of a function is at its header. The end of the function is
900 after its closing brace, or after the semicolon of a construct (such
901 as a @code{struct}) which doesn't end at the brace. These two
902 commands try to leave point at the beginning of a line near the actual
903 start or end of the function. This occasionally causes point not to
906 By default, these commands will recognize functions contained within a
907 @dfn{declaration scope} such as a C++ @code{class} or @code{namespace}
908 construct, should the point start inside it. If @ccmode fails to find
909 function beginnings or ends inside the current declaration scope, it
910 will search the enclosing scopes. If you want @ccmode to recognize
911 functions only at the top level@footnote{this was @ccmode{}'s
912 behavior prior to version 5.32.}, set @code{c-defun-tactic} to
915 These functions are analogous to the Emacs built-in commands
916 @code{beginning-of-defun} and @code{end-of-defun}, except they
917 eliminate the constraint that the top-level opening brace of the defun
918 must be in column zero. See @ref{Defuns,,,@emacsman{},
919 @emacsmantitle{}}, for more information.
921 @item @kbd{C-M-a} (AWK Mode) (@code{c-awk-beginning-of-defun})
922 @itemx @kbd{C-M-e} (AWK Mode) (@code{c-awk-end-of-defun})
923 @kindex C-M-a @r{(AWK Mode)}
924 @kindex C-M-e @r{(AWK Mode)}
925 @findex c-awk-beginning-of-defun
926 @findex awk-beginning-of-defun @r{(c-)}
927 @findex c-awk-end-of-defun
928 @findex awk-end-of-defun @r{(c-)}
929 Move to the beginning or end of the current or next AWK defun. These
930 commands can take prefix-arguments, their functionality being entirely
931 equivalent to @code{beginning-of-defun} and @code{end-of-defun}.
933 AWK Mode @dfn{defuns} are either pattern/action pairs (either of which
934 might be implicit) or user defined functions. Having the @samp{@{} and
935 @samp{@}} (if there are any) in column zero, as is suggested for some
936 modes, is neither necessary nor helpful in AWK mode.
938 @item @kbd{M-a} (@code{c-beginning-of-statement})
939 @itemx @kbd{M-e} (@code{c-end-of-statement})
942 @findex c-beginning-of-statement
943 @findex c-end-of-statement
944 @findex beginning-of-statement @r{(c-)}
945 @findex end-of-statement @r{(c-)}
946 Move to the beginning or end of the innermost C statement. If point
947 is already there, move to the next beginning or end of a statement,
948 even if that means moving into a block. (Use @kbd{C-M-b} or
949 @kbd{C-M-f} to move over a balanced block.) A prefix argument @var{n}
950 means move over @var{n} statements.
952 If point is within or next to a comment or a string which spans more
953 than one line, these commands move by sentences instead of statements.
955 When called from a program, these functions take three optional
956 arguments: the repetition count, a buffer position limit which is the
957 farthest back to search for the syntactic context, and a flag saying
958 whether to do sentence motion in or near comments and multiline
961 @item @kbd{C-c C-u} (@code{c-up-conditional})
963 @findex c-up-conditional
964 @findex up-conditional @r{(c-)}
965 Move back to the containing preprocessor conditional, leaving the mark
966 behind. A prefix argument acts as a repeat count. With a negative
967 argument, move forward to the end of the containing preprocessor
970 @samp{#elif} is treated like @samp{#else} followed by @samp{#if}, so the
971 function stops at them when going backward, but not when going
974 This key sequence is not bound in AWK Mode, which doesn't have
975 preprocessor statements.
977 @item @kbd{M-x c-up-conditional-with-else}
978 @findex c-up-conditional-with-else
979 @findex up-conditional-with-else @r{(c-)}
980 A variety of @code{c-up-conditional} that also stops at @samp{#else}
981 lines. Normally those lines are ignored.
983 @item @kbd{M-x c-down-conditional}
984 @findex c-down-conditional
985 @findex down-conditional @r{(c-)}
986 Move forward into the next nested preprocessor conditional, leaving
987 the mark behind. A prefix argument acts as a repeat count. With a
988 negative argument, move backward into the previous nested preprocessor
991 @samp{#elif} is treated like @samp{#else} followed by @samp{#if}, so the
992 function stops at them when going forward, but not when going backward.
994 @item @kbd{M-x c-down-conditional-with-else}
995 @findex c-down-conditional-with-else
996 @findex down-conditional-with-else @r{(c-)}
997 A variety of @code{c-down-conditional} that also stops at @samp{#else}
998 lines. Normally those lines are ignored.
1000 @item @kbd{C-c C-p} (@code{c-backward-conditional})
1001 @itemx @kbd{C-c C-n} (@code{c-forward-conditional})
1004 @findex c-backward-conditional
1005 @findex c-forward-conditional
1006 @findex backward-conditional @r{(c-)}
1007 @findex forward-conditional @r{(c-)}
1008 Move backward or forward across a preprocessor conditional, leaving
1009 the mark behind. A prefix argument acts as a repeat count. With a
1010 negative argument, move in the opposite direction.
1012 These key sequences are not bound in AWK Mode, which doesn't have
1013 preprocessor statements.
1015 @item @kbd{M-x c-backward-into-nomenclature}
1016 @itemx @kbd{M-x c-forward-into-nomenclature}
1017 @findex c-backward-into-nomenclature
1018 @findex c-forward-into-nomenclature
1019 @findex backward-into-nomenclature @r{(c-)}
1020 @findex forward-into-nomenclature @r{(c-)}
1021 A popular programming style, especially for object-oriented languages
1022 such as C++ is to write symbols in a mixed case format, where the
1023 first letter of each word is capitalized, and not separated by
1024 underscores. E.g., @samp{SymbolsWithMixedCaseAndNoUnderlines}.
1026 These commands move backward or forward to the beginning of the next
1027 capitalized word. With prefix argument @var{n}, move @var{n} times.
1028 If @var{n} is negative, move in the opposite direction.
1030 Note that these two commands have been superseded by
1031 @code{subword-mode}, which you should use instead. @xref{Subword
1032 Movement}. They might be removed from a future release of @ccmode{}.
1035 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1036 @node Filling and Breaking, Minor Modes, Movement Commands, Commands
1037 @comment node-name, next, previous, up
1038 @section Filling and Line Breaking Commands
1039 @cindex text filling
1040 @cindex line breaking
1041 @cindex comment handling
1042 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1044 Since there's a lot of normal text in comments and string literals,
1045 @ccmode{} provides features to edit these like in text mode. The goal
1046 is to do it seamlessly, i.e., you can use auto fill mode, sentence and
1047 paragraph movement, paragraph filling, adaptive filling etc.@: wherever
1048 there's a piece of normal text without having to think much about it.
1049 @ccmode{} keeps the indentation, fixes suitable comment line prefixes,
1052 You can configure the exact way comments get filled and broken, and
1053 where Emacs does auto-filling (see @pxref{Custom Filling and
1054 Breaking}). Typically, the style system (@pxref{Styles}) will have
1055 set this up for you, so you probably won't have to bother.
1057 @findex auto-fill-mode
1058 @cindex Auto Fill mode
1059 @cindex paragraph filling
1060 Line breaks are by default handled (almost) the same regardless of
1061 whether they are made by auto fill mode (@pxref{Auto
1062 Fill,,,@emacsman{}, @emacsmantitle{}}), by paragraph filling (e.g., with
1063 @kbd{M-q}), or explicitly with @kbd{M-j} or similar methods. In
1064 string literals, the new line gets the same indentation as the
1065 previous nonempty line.@footnote{You can change this default by
1066 setting the @code{string} syntactic symbol (@pxref{Syntactic Symbols}
1067 and @pxref{Customizing Indentation})}.
1070 @item @kbd{M-q} (@code{c-fill-paragraph})
1072 @findex c-fill-paragraph
1073 @findex fill-paragraph @r{(c-)}
1074 @cindex Javadoc markup
1075 @cindex Pike autodoc markup
1076 This command fills multiline string literals and both block
1077 and line style comments. In Java buffers, the Javadoc markup words
1078 are recognized as paragraph starters. The line oriented Pike autodoc
1079 markup words are recognized in the same way in Pike mode.
1081 The formatting of the starters (@code{/*}) and enders (@code{*/}) of
1082 block comments are kept as they were before the filling. I.e., if
1083 either the starter or ender were on a line of its own, then it stays
1084 on its own line; conversely, if the delimiter has comment text on its
1085 line, it keeps at least one word of that text with it on the line.
1087 This command is the replacement for @code{fill-paragraph} in @ccmode{}
1090 @item @kbd{M-j} (@code{c-indent-new-comment-line})
1092 @findex c-indent-new-comment-line
1093 @findex indent-new-comment-line @r{(c-)}
1094 This breaks the current line at point and indents the new line. If
1095 point was in a comment, the new line gets the proper comment line
1096 prefix. If point was inside a macro, a backslash is inserted before
1097 the line break. It is the replacement for
1098 @code{indent-new-comment-line}.
1100 @item @kbd{M-x c-context-line-break}
1101 @findex c-context-line-break
1102 @findex context-line-break @r{(c-)}
1103 Insert a line break suitable to the context: If the point is inside a
1104 comment, the new line gets the suitable indentation and comment line
1105 prefix like @code{c-indent-new-comment-line}. In normal code it's
1106 indented like @code{newline-and-indent} would do. In macros it acts
1107 like @code{newline-and-indent} but additionally inserts and optionally
1108 aligns the line ending backslash so that the macro remains unbroken.
1109 @xref{Custom Macros}, for details about the backslash alignment. In a
1110 string, a backslash is inserted only if the string is within a
1111 macro@footnote{In GCC, unescaped line breaks within strings are
1114 This function is not bound to a key by default, but it's intended to be
1115 used on the @kbd{RET} key. If you like the behavior of
1116 @code{newline-and-indent} on @kbd{RET}, you should consider switching to
1117 this function. @xref{Sample Init File}.
1119 @item @kbd{M-x c-context-open-line}
1120 @findex c-context-open-line
1121 @findex context-open-line @r{(c-)}
1122 This is to @kbd{C-o} (@kbd{M-x open-line}) as
1123 @code{c-context-line-break} is to @kbd{RET}. I.e., it works just like
1124 @code{c-context-line-break} but leaves the point before the inserted
1129 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1130 @node Minor Modes, Electric Keys, Filling and Breaking, Commands
1131 @comment node-name, next, previous, up
1132 @section Minor Modes
1134 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1136 @ccmode{} contains several minor-mode-like features that you might
1137 find useful while writing new code or editing old code:
1141 This specifies whether comment commands (such as @kbd{M-;}) insert
1142 block comments or line comments.
1144 When this is enabled, certain visible characters cause reformatting as
1145 they are typed. This is normally helpful, but can be a nuisance when
1146 editing chaotically formatted code. It can also be disconcerting,
1147 especially for users who are new to @ccmode{}.
1148 @item auto-newline mode
1149 This automatically inserts newlines where you'd probably want to type
1150 them yourself, e.g., after typing @samp{@}}s. Its action is suppressed
1151 when electric mode is disabled.
1152 @item hungry-delete mode
1153 This lets you delete a contiguous block of whitespace with a single
1154 key: for example, the newline and indentation just inserted by
1155 auto-newline when you want to back up and write a comment after the
1158 This mode makes basic word movement commands like @kbd{M-f}
1159 (@code{forward-word}) and @kbd{M-b} (@code{backward-word}) treat the
1160 parts of sillycapsed symbols as different words.
1161 E.g., @samp{NSGraphicsContext} is treated as three words @samp{NS},
1162 @samp{Graphics}, and @samp{Context}.
1163 @item syntactic-indentation mode
1164 When this is enabled (which it normally is), indentation commands such
1165 as @kbd{C-j} indent lines of code according to their syntactic
1166 structure. Otherwise, a line is simply indented to the same level as
1167 the previous one and @kbd{@key{TAB}} adjusts the indentation in steps
1168 of @code{c-basic-offset}.
1171 Full details on how these minor modes work are at @ref{Electric Keys},
1172 @ref{Auto-newlines}, @ref{Hungry WS Deletion}, @ref{Subword Movement},
1173 and @ref{Indentation Engine Basics}.
1175 You can toggle each of these minor modes on and off, and you can
1176 configure @ccmode{} so that it starts up with your favorite
1177 combination of them (@pxref{Sample Init File}). By default, when
1178 you initialize a buffer, the comment style is set to the default for
1179 the major mode, electric mode and syntactic-indentation mode are
1180 enabled, but the other three modes are disabled.
1182 @ccmode{} displays the current state of the first five of these minor
1183 modes on the mode line by appending characters to the major mode's
1184 name: @samp{/} or @samp{*} to indicate the comment style (respectively
1185 line or block), and one letter for each of the other minor modes which
1186 is enabled - @samp{l} for electric mode, @samp{a} for auto-newline
1187 mode, @samp{h} for hungry delete mode, and @samp{w} for subword mode.
1188 If the comment style was block and all the other modes were enabled,
1189 you'd see @samp{C/*lahw}@footnote{The @samp{C} would be replaced with
1190 the name of the language in question for the other languages @ccmode{}
1193 Here are the commands to toggle these modes:
1196 @item @kbd{C-c C-k} (@code{c-toggle-comment-style})
1198 @findex c-toggle-comment-style
1199 @findex toggle-comment-style @r{(c-)}
1200 Toggle the comment style between line style and block style. In modes
1201 (such as AWK Mode) which only have one of these styles, this function
1204 @item @kbd{C-c C-l} (@code{c-toggle-electric-state})
1206 @findex c-toggle-electric-state
1207 @findex toggle-electric-state @r{(c-)}
1208 Toggle electric minor mode. When the command turns the mode off, it
1209 also suppresses auto-newline mode.
1211 @item @kbd{C-c C-a} (@code{c-toggle-auto-newline})
1213 @findex c-toggle-auto-newline
1214 @findex toggle-auto-newline @r{(c-)}
1215 Toggle auto-newline minor mode. When the command turns the mode on,
1216 it also enables electric minor mode.
1218 @item @kbd{M-x c-toggle-hungry-state}@footnote{Prior to @ccmode{} 5.31, this command was bound to @kbd{C-c C-d}.}
1219 @findex c-toggle-hungry-state
1220 @findex toggle-hungry-state @r{(c-)}
1221 Toggle hungry-delete minor mode.
1223 @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}.}
1224 @findex c-toggle-auto-hungry-state
1225 @findex toggle-auto-hungry-state @r{(c-)}
1226 Toggle both auto-newline and hungry delete minor modes.
1228 @item @kbd{C-c C-w} (@code{M-x subword-mode})
1230 @findex subword-mode
1231 Toggle subword mode.
1233 @item @kbd{M-x c-toggle-syntactic-indentation}
1234 @findex c-toggle-syntactic-indentation
1235 @findex toggle-syntactic-indentation @r{(c-)}
1236 Toggle syntactic-indentation mode.
1239 Common to all the toggle functions above is that if they are called
1240 programmatically, they take an optional numerical argument. For
1241 @code{c-toggle-comment style}, a positive value will select block
1242 comments, a negative value will select line comments. For the other
1243 functions, a positive value will turn on the minor mode (or both of
1244 them in the case of @code{c-toggle-auto-hungry-state}) and a negative
1245 value will turn it (or them) off.
1248 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1249 @node Electric Keys, Auto-newlines, Minor Modes, Commands
1250 @comment node-name, next, previous, up
1251 @section Electric Keys and Keywords
1252 @cindex electric characters
1253 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1255 Most punctuation keys provide @dfn{electric} behavior: as well as
1256 inserting themselves they perform some other action, such as
1257 reindenting the line. This reindentation saves you from having to
1258 reindent a line manually after typing, say, a @samp{@}}. A few
1259 keywords, such as @code{else}, also trigger electric action.
1261 You can inhibit the electric behavior described here by disabling
1262 electric minor mode (@pxref{Minor Modes}).
1264 Common to all these keys is that they only behave electrically when
1265 used in normal code (as contrasted with getting typed in a string
1266 literal or comment). Those which cause re-indentation do so only when
1267 @code{c-syntactic-indentation} has a non-@code{nil} value (which it
1270 These keys and keywords are:
1271 @c ACM, 2004/8/24: c-electric-pound doesn't check c-s-i: this is more
1272 @c like a bug in the code than a bug in this document. It'll get
1273 @c fixed in the code sometime.
1278 @findex c-electric-pound
1279 @findex electric-pound @r{(c-)}
1280 @vindex c-electric-pound-behavior
1281 @vindex electric-pound-behavior @r{(c-)}
1282 Pound (bound to @code{c-electric-pound}) is electric when typed as the
1283 first non-whitespace character on a line and not within a macro
1284 definition. In this case, the variable @code{c-electric-pound-behavior}
1285 is consulted for the electric behavior. This variable takes a list
1286 value, although the only element currently defined is @code{alignleft},
1287 which tells this command to force the @samp{#} character into column
1288 zero. This is useful for entering preprocessor macro definitions.
1290 Pound is not electric in AWK buffers, where @samp{#} starts a comment,
1291 and is bound to @code{self-insert-command} like any typical printable
1293 @c ACM, 2004/8/24: Change this (and the code) to do AWK comment
1300 @findex c-electric-star
1301 @findex electric-star @r{(c-)}
1302 @findex c-electric-slash
1303 @findex electric-slash @r{(c-)}
1304 A star (bound to @code{c-electric-star}) or a slash
1305 (@code{c-electric-slash}) causes reindentation when you type it as the
1306 second component of a C style block comment opener (@samp{/*}) or a
1307 C++ line comment opener (@samp{//}) respectively, but only if the
1308 comment opener is the first thing on the line (i.e., there's only
1309 whitespace before it).
1311 Additionally, you can configure @ccmode{} so that typing a slash at
1312 the start of a line within a block comment will terminate the
1313 comment. You don't need to have electric minor mode enabled to get
1314 this behavior. @xref{Clean-ups}.
1316 In AWK mode, @samp{*} and @samp{/} do not delimit comments and are not
1323 @findex c-electric-lt-gt
1324 @findex electric-lt-gt @r{(c-)}
1325 A less-than or greater-than sign (bound to @code{c-electric-lt-gt}) is
1326 electric in two circumstances: when it is an angle bracket in a C++
1327 @samp{template} declaration (and similar constructs in other
1328 languages) and when it is the second of two @kbd{<} or @kbd{>}
1329 characters in a C++ style stream operator. In either case, the line
1330 is reindented. Angle brackets in C @samp{#include} directives are not
1337 @findex c-electric-paren
1338 @findex electric-paren @r{(c-)}
1339 The normal parenthesis characters @samp{(} and @samp{)} (bound to
1340 @code{c-electric-paren}) reindent the current line. This is useful
1341 for getting the closing parenthesis of an argument list aligned
1344 You can also configure @ccmode{} to insert a space automatically
1345 between a function name and the @samp{(} you've just typed, and to
1346 remove it automatically after typing @samp{)}, should the argument
1347 list be empty. You don't need to have electric minor mode enabled to
1348 get these actions. @xref{Clean-ups}.
1354 @findex c-electric-brace
1355 @findex electric-brace @r{(c-)}
1356 Typing a brace (bound to @code{c-electric-brace}) reindents the
1357 current line. Also, one or more newlines might be inserted if
1358 auto-newline minor mode is enabled. @xref{Auto-newlines}.
1359 Additionally, you can configure @ccmode{} to compact excess whitespace
1360 inserted by auto-newline mode in certain circumstances.
1365 @findex c-electric-colon
1366 @findex electric-colon @r{(c-)}
1367 Typing a colon (bound to @code{c-electric-colon}) reindents the
1368 current line. Additionally, one or more newlines might be inserted if
1369 auto-newline minor mode is enabled. @xref{Auto-newlines}. If you
1370 type a second colon immediately after such an auto-newline, by default
1371 the whitespace between the two colons is removed, leaving a C++ scope
1372 operator. @xref{Clean-ups}.
1374 If you prefer, you can insert @samp{::} in a single operation,
1375 avoiding all these spurious reindentations, newlines, and clean-ups.
1376 @xref{Other Commands}.
1382 @findex c-electric-semi&comma
1383 @findex electric-semi&comma @r{(c-)}
1384 Typing a semicolon or comma (bound to @code{c-electric-semi&comma})
1385 reindents the current line. Also, a newline might be inserted if
1386 auto-newline minor mode is enabled. @xref{Auto-newlines}.
1387 Additionally, you can configure @ccmode{} so that when auto-newline
1388 has inserted whitespace after a @samp{@}}, it will be removed again
1389 when you type a semicolon or comma just after it. @xref{Clean-ups}.
1393 @deffn Command c-electric-continued-statement
1394 @findex electric-continued-statement @r{(c-)}
1396 Certain keywords are electric, causing reindentation when they are
1397 preceded only by whitespace on the line. The keywords are those that
1398 continue an earlier statement instead of starting a new one:
1399 @code{else}, @code{while}, @code{catch} (only in C++ and Java) and
1400 @code{finally} (only in Java).
1406 for (i = 0; i < 17; i++)
1408 res += a[i]->offset;
1413 Here, the @code{else} should be indented like the preceding @code{if},
1414 since it continues that statement. @ccmode{} will automatically
1415 reindent it after the @code{else} has been typed in full, since only
1416 then is it possible to decide whether it's a new statement or a
1417 continuation of the preceding @code{if}.
1422 @ccmode{} uses Abbrev mode (@pxref{Abbrevs,,,@emacsman{}, @emacsmantitle{}})
1423 to accomplish this. It's therefore turned on by default in all language
1424 modes except IDL mode, since CORBA IDL doesn't have any statements.
1428 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1429 @node Auto-newlines, Hungry WS Deletion, Electric Keys, Commands
1430 @comment node-name, next, previous, up
1431 @section Auto-newline Insertion
1432 @cindex auto-newline
1433 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1435 When you have @dfn{Auto-newline minor mode} enabled (@pxref{Minor
1436 Modes}), @ccmode{} inserts newlines for you automatically (in certain
1437 syntactic contexts) when you type a left or right brace, a colon, a
1438 semicolon, or a comma. Sometimes a newline appears before the
1439 character you type, sometimes after it, sometimes both.
1441 Auto-newline only triggers when the following conditions hold:
1445 Auto-newline minor mode is enabled, as evidenced by the indicator
1446 @samp{a} after the mode name on the modeline (e.g., @samp{C/a} or
1450 The character was typed at the end of a line, or with only whitespace
1451 after it, and possibly a @samp{\} escaping the newline.
1454 The character is not on its own line already. (This applies only to
1455 insertion of a newline @emph{before} the character.)
1459 @cindex syntactic whitespace
1460 The character was not typed inside of a literal @footnote{A
1461 @dfn{literal} is defined as any comment, string, or preprocessor macro
1462 definition. These constructs are also known as @dfn{syntactic
1463 whitespace} since they are usually ignored when scanning C code.}.
1466 No numeric argument was supplied to the command (i.e., it was typed as
1467 normal, with no @kbd{C-u} prefix).
1470 You can configure the precise circumstances in which newlines get
1471 inserted (see @pxref{Custom Auto-newlines}). Typically, the style
1472 system (@pxref{Styles}) will have set this up for you, so you probably
1473 won't have to bother.
1475 Sometimes @ccmode{} inserts an auto-newline where you don't want one,
1476 such as after a @samp{@}} when you're about to type a @samp{;}.
1477 Hungry deletion can help here (@pxref{Hungry WS Deletion}), or you can
1478 activate an appropriate @dfn{clean-up}, which will remove the excess
1479 whitespace after you've typed the @samp{;}. See @ref{Clean-ups} for a
1480 full description. See also @ref{Electric Keys} for a summary of
1481 clean-ups listed by key.
1484 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1485 @node Hungry WS Deletion, Subword Movement, Auto-newlines, Commands
1486 @comment node-name, next, previous, up
1487 @section Hungry Deletion of Whitespace
1488 @cindex hungry-deletion
1489 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1491 If you want to delete an entire block of whitespace at point, you can
1492 use @dfn{hungry deletion}. This deletes all the contiguous whitespace
1493 either before point or after point in a single operation.
1494 ``Whitespace'' here includes tabs and newlines, but not comments or
1495 preprocessor commands. Hungry deletion can markedly cut down on the
1496 number of times you have to hit deletion keys when, for example,
1497 you've made a mistake on the preceding line and have already pressed
1500 Hungry deletion is a simple feature that some people find extremely
1501 useful. In fact, you might find yourself wanting it in @strong{all}
1504 Loosely speaking, in what follows, @dfn{@key{DEL}} means ``the
1505 backspace key'' and @dfn{@key{DELETE}} means ``the forward delete
1506 key''. This is discussed in more detail below.
1508 There are two different ways you can use hungry deletion:
1511 @item Using @dfn{Hungry Delete Mode} with @kbd{@key{DEL}} and @kbd{C-d}
1512 Here you toggle Hungry Delete minor mode with @kbd{M-x
1513 c-toggle-hungry-state}@footnote{Prior to @ccmode{} 5.31, this command
1514 was bound to @kbd{C-c C-d}. @kbd{C-c C-d} is now the default binding
1515 for @code{c-hungry-delete-forward}.} (@pxref{Minor Modes}.) This
1516 makes @kbd{@key{DEL}} and @kbd{C-d} do backwards and forward hungry
1520 @item @kbd{@key{DEL}} (@code{c-electric-backspace})
1522 @findex c-electric-backspace
1523 @findex electric-backspace @r{(c-)}
1524 This command is run by default when you hit the @kbd{@key{DEL}} key. When
1525 hungry delete mode is enabled, it deletes any amount of whitespace in
1526 the backwards direction. Otherwise, or when used with a prefix
1527 argument or in a literal (@pxref{Auto-newlines}), the command just
1528 deletes backwards in the usual way. (More precisely, it calls the
1529 function contained in the variable @code{c-backspace-function},
1530 passing it the prefix argument, if any.)
1532 @item @code{c-backspace-function}
1533 @vindex c-backspace-function
1534 @vindex backspace-function @r{(c-)}
1535 @findex backward-delete-char-untabify
1536 Hook that gets called by @code{c-electric-backspace} when it doesn't
1537 do an ``electric'' deletion of the preceding whitespace. The default
1538 value is @code{backward-delete-char-untabify}
1539 (@pxref{Deletion,,,@lispref{}, @lispreftitle{}}, the function which
1540 deletes a single character.
1542 @item @kbd{C-d} (@code{c-electric-delete-forward})
1544 @findex c-electric-delete-forward
1545 @findex electric-delete-forward @r{(c-)}
1546 This function, which is bound to @kbd{C-d} by default, works just like
1547 @code{c-electric-backspace} but in the forward direction. When it
1548 doesn't do an ``electric'' deletion of the following whitespace, it
1549 just does @code{delete-char}, more or less. (Strictly speaking, it
1550 calls the function in @code{c-delete-function} with the prefix
1553 @item @code{c-delete-function}
1554 @vindex c-delete-function
1555 @vindex delete-function @r{(c-)}
1557 Hook that gets called by @code{c-electric-delete-forward} when it
1558 doesn't do an ``electric'' deletion of the following whitespace. The
1559 default value is @code{delete-char}.
1562 @item Using Distinct Bindings
1563 The other (newer and recommended) way to use hungry deletion is to
1564 perform @code{c-hungry-delete-backwards} and
1565 @code{c-hungry-delete-forward} directly through their key sequences
1566 rather than using the minor mode toggling.
1569 @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}.}
1570 @kindex C-c C-Backspace
1571 @kindex C-c Backspace
1574 @findex c-hungry-delete-backwards
1575 @findex hungry-delete-backwards @r{(c-)}
1576 Delete any amount of whitespace in the backwards direction (regardless
1577 whether hungry-delete mode is enabled or not). This command is bound
1578 to both @kbd{C-c C-@key{DEL}} and @kbd{C-c @key{DEL}}, since the more
1579 natural one, @kbd{C-c C-@key{DEL}}, is sometimes difficult to type at
1580 a character terminal.
1582 @item @kbd{C-c C-d}, @kbd{C-c C-@key{DELETE}}, or @kbd{C-c @key{DELETE}} (@code{c-hungry-delete-forward})
1584 @kindex C-c C-Delete
1586 @findex c-hungry-delete-forward
1587 @findex hungry-delete-forward @r{(c-)}
1588 Delete any amount of whitespace in the forward direction (regardless
1589 whether hungry-delete mode is enabled or not). This command is bound
1590 to both @kbd{C-c C-@key{Delete}} and @kbd{C-c @key{Delete}} for the
1591 same reason as for @key{DEL} above.
1598 When we talk about @kbd{@key{DEL}}, and @kbd{@key{Delete}} above, we
1599 actually do so without connecting them to the physical keys commonly
1600 known as @key{Backspace} and @key{Delete}. The default bindings to
1601 those two keys depends on the flavor of (X)Emacs you are using.
1603 @findex c-electric-delete
1604 @findex electric-delete @r{(c-)}
1605 @findex c-hungry-delete
1606 @findex hungry-delete @r{(c-)}
1607 @vindex delete-key-deletes-forward
1608 In XEmacs 20.3 and beyond, the @key{Backspace} key is bound to
1609 @code{c-electric-backspace} and the @key{Delete} key is bound to
1610 @code{c-electric-delete}. You control the direction it deletes in by
1611 setting the variable @code{delete-key-deletes-forward}, a standard
1613 @c This variable is encapsulated by XEmacs's (defsubst delete-forward-p ...).
1614 When this variable is non-@code{nil}, @code{c-electric-delete} will do
1615 forward deletion with @code{c-electric-delete-forward}, otherwise it
1616 does backward deletion with @code{c-electric-backspace}. Similarly,
1617 @kbd{C-c @key{Delete}} and @kbd{C-c C-@key{Delete}} are bound to
1618 @code{c-hungry-delete} which is controlled in the same way by
1619 @code{delete-key-deletes-forward}.
1621 @findex normal-erase-is-backspace-mode
1623 Emacs 21 and later automatically binds @key{Backspace} and
1624 @key{Delete} to @kbd{DEL} and @kbd{C-d} according to your environment,
1625 and @ccmode{} extends those bindings to @kbd{C-c C-@key{Backspace}}
1626 etc. If you need to change the bindings through
1627 @code{normal-erase-is-backspace-mode} then @ccmode{} will also adapt
1628 its extended bindings accordingly.
1630 In earlier (X)Emacs versions, @ccmode{} doesn't bind either
1631 @key{Backspace} or @key{Delete} directly. Only the key codes
1632 @kbd{DEL} and @kbd{C-d} are bound, and it's up to the default bindings
1633 to map the physical keys to them. You might need to modify this
1634 yourself if the defaults are unsuitable.
1636 Getting your @key{Backspace} and @key{Delete} keys properly set up can
1637 sometimes be tricky. The information in @ref{DEL Does Not
1638 Delete,,,emacs, GNU Emacs Manual}, might be helpful if you're having
1639 trouble with this in GNU Emacs.
1642 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1643 @node Subword Movement, Other Commands, Hungry WS Deletion, Commands
1644 @comment node-name, next, previous, up
1645 @section Subword Movement and Editing
1646 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1648 @cindex nomenclature
1650 In spite of the GNU Coding Standards, it is popular to name a symbol
1651 by mixing uppercase and lowercase letters, e.g., @samp{GtkWidget},
1652 @samp{EmacsFrameClass}, or @samp{NSGraphicsContext}. Here we call
1653 these mixed case symbols @dfn{nomenclatures}. Also, each capitalized
1654 (or completely uppercase) part of a nomenclature is called a
1655 @dfn{subword}. Here are some examples:
1657 @multitable {@samp{NSGraphicsContext}} {@samp{NS}, @samp{Graphics}, and @samp{Context}}
1658 @c This could be converted to @headitem when we require Texinfo 4.7
1660 @item @b{Nomenclature}
1666 @item ---------------------------------------------------------
1668 @item @samp{GtkWindow}
1669 @tab @samp{Gtk} and @samp{Window}
1670 @item @samp{EmacsFrameClass}
1671 @tab @samp{Emacs}, @samp{Frame}, and @samp{Class}
1672 @item @samp{NSGraphicsContext}
1673 @tab @samp{NS}, @samp{Graphics}, and @samp{Context}
1676 The subword minor mode replaces the basic word oriented movement and
1677 editing commands with variants that recognize subwords in a
1678 nomenclature and treat them as separate words:
1680 @findex c-forward-subword
1681 @findex forward-subword @r{(c-)}
1682 @findex c-backward-subword
1683 @findex backward-subword @r{(c-)}
1684 @findex c-mark-subword
1685 @findex mark-subword @r{(c-)}
1686 @findex c-kill-subword
1687 @findex kill-subword @r{(c-)}
1688 @findex c-backward-kill-subword
1689 @findex backward-kill-subword @r{(c-)}
1690 @findex c-transpose-subwords
1691 @findex transpose-subwords @r{(c-)}
1692 @findex c-capitalize-subword
1693 @findex capitalize-subword @r{(c-)}
1694 @findex c-upcase-subword
1695 @findex upcase-subword @r{(c-)}
1696 @findex c-downcase-subword
1697 @findex downcase-subword @r{(c-)}
1698 @multitable @columnfractions .20 .40 .40
1699 @c This could be converted to @headitem when we require Texinfo 4.7
1701 @item @b{Key} @tab @b{Word oriented command} @tab @b{Subword oriented command}
1704 @item Key @tab Word oriented command @tab Subword oriented command
1705 @item ----------------------------------------------------------------------------
1707 @item @kbd{M-f} @tab @code{forward-word} @tab @code{c-forward-subword}
1708 @item @kbd{M-b} @tab @code{backward-word} @tab @code{c-backward-subword}
1709 @item @kbd{M-@@} @tab @code{mark-word} @tab @code{c-mark-subword}
1710 @item @kbd{M-d} @tab @code{kill-word} @tab @code{c-kill-subword}
1711 @item @kbd{M-@key{DEL}} @tab @code{backward-kill-word} @tab @code{c-backward-kill-subword}
1712 @item @kbd{M-t} @tab @code{transpose-words} @tab @code{c-transpose-subwords}
1713 @item @kbd{M-c} @tab @code{capitalize-word} @tab @code{c-capitalize-subword}
1714 @item @kbd{M-u} @tab @code{upcase-word} @tab @code{c-upcase-subword}
1715 @item @kbd{M-l} @tab @code{downcase-word} @tab @code{c-downcase-subword}
1718 Note that if you have changed the key bindings for the word oriented
1719 commands in your @file{.emacs} or a similar place, the keys you have
1720 configured are also used for the corresponding subword oriented
1723 Type @kbd{C-c C-w} to toggle subword mode on and off. To make the
1724 mode turn on automatically, put the following code in your
1728 (add-hook 'c-mode-common-hook
1729 (lambda () (subword-mode 1)))
1732 As a bonus, you can also use @code{subword-mode} in non-@ccmode{}
1733 buffers by typing @kbd{M-x subword-mode}.
1735 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1736 @node Other Commands, , Subword Movement, Commands
1737 @comment node-name, next, previous, up
1738 @section Other Commands
1739 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1741 Here are the various other commands that didn't fit anywhere else:
1744 @item @kbd{C-c .} (@code{c-set-style})
1747 @findex set-style @r{(c-)}
1748 Switch to the specified style in the current buffer. Use like this:
1751 @kbd{C-c . @var{style-name} @key{RET}}
1754 You can use the @key{TAB} in the normal way to do completion on the
1755 style name. Note that all style names are case insensitive, even the
1756 ones you define yourself.
1758 Setting a style in this way does @emph{not} automatically reindent your
1759 file. For commands that you can use to view the effect of your changes,
1760 see @ref{Indentation Commands} and @ref{Filling and Breaking}.
1762 For details of the @ccmode{} style system, see @ref{Styles}.
1764 @item @kbd{C-c :} (@code{c-scope-operator})
1766 @findex c-scope-operator
1767 @findex scope-operator @r{(c-)}
1768 In C++, it is also sometimes desirable to insert the double-colon scope
1769 operator without performing the electric behavior of colon insertion.
1770 @kbd{C-c :} does just this.
1772 @item @kbd{C-c C-z} (@code{c-display-defun-name})
1774 @findex c-display-defun-name
1775 @findex display-defun-name @r{(c-)}
1776 Display the current function name, if any, in the minibuffer.
1777 Additionally, if a prefix argument is given, push the function name to
1778 the kill ring. If there is no current function,
1779 @code{c-display-defun-name} does nothing. In Emacs, you can use this
1780 command in the middle of an interactive search if you set the
1781 customizable option @code{isearch-allow-scroll} to non-@code{nil}.
1782 @xref{Not Exiting Isearch,,,emacs, GNU Emacs Manual}.
1784 @item @kbd{C-c C-\} (@code{c-backslash-region})
1786 @findex c-backslash-region
1787 @findex backslash-region @r{(c-)}
1788 This function inserts and aligns or deletes end-of-line backslashes in
1789 the current region. These are typically used in multi-line macros.
1791 With no prefix argument, it inserts any missing backslashes and aligns
1792 them according to the @code{c-backslash-column} and
1793 @code{c-backslash-max-column} variables. With a prefix argument, it
1794 deletes any backslashes.
1796 The function does not modify blank lines at the start of the region. If
1797 the region ends at the start of a line, it always deletes the backslash
1798 (if any) at the end of the previous line.
1800 To customize the precise workings of this command, @ref{Custom Macros}.
1804 The recommended line breaking function, @code{c-context-line-break}
1805 (@pxref{Filling and Breaking}), is especially nice if you edit
1806 multiline macros frequently. When used inside a macro, it
1807 automatically inserts and adjusts the mandatory backslash at the end
1808 of the line to keep the macro together, and it leaves the point at the
1809 right indentation column for the code. Thus you can write code inside
1810 macros almost exactly as you can elsewhere, without having to bother
1811 with the trailing backslashes.
1814 @item @kbd{C-c C-e} (@code{c-macro-expand})
1816 @findex c-macro-expand
1817 @findex macro-expand @r{(c-)}
1818 This command expands C, C++, Objective C or Pike macros in the region,
1819 using an appropriate external preprocessor program. Normally it
1820 displays its output in a temporary buffer, but if you give it a prefix
1821 arg (with @kbd{C-u C-c C-e}) it will overwrite the original region
1824 The command does not work in any of the other modes, and the key
1825 sequence is not bound in these other modes.
1827 @code{c-macro-expand} isn't actually part of @ccmode{}, even though it
1828 is bound to a @ccmode{} key sequence. If you need help setting it up
1829 or have other problems with it, you can either read its source code or
1830 ask for help in the standard (X)Emacs forums.
1833 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1834 @node Font Locking, Config Basics, Commands, Top
1835 @comment node-name, next, previous, up
1836 @chapter Font Locking
1837 @cindex font locking
1838 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1840 @cindex Font Lock mode
1842 @ccmode{} provides font locking for its supported languages by
1843 supplying patterns for use with Font Lock mode. This means that you
1844 get distinct faces on the various syntactic parts such as comments,
1845 strings, keywords and types, which is very helpful in telling them
1846 apart at a glance and discovering syntactic errors. @xref{Font
1847 Lock,,, emacs, GNU Emacs Manual}, for ways to enable font locking in
1850 @strong{Please note:} The font locking in AWK mode is currently not
1851 integrated with the rest of @ccmode{}. Only the last section of this
1852 chapter, @ref{AWK Mode Font Locking}, applies to AWK@. The other
1853 sections apply to the other languages.
1856 * Font Locking Preliminaries::
1859 * Misc Font Locking::
1860 * AWK Mode Font Locking::
1864 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1865 @node Font Locking Preliminaries, Faces, Font Locking, Font Locking
1866 @comment node-name, next, previous, up
1867 @section Font Locking Preliminaries
1868 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1870 The font locking for most of the @ccmode{} languages were provided
1871 directly by the Font Lock package prior to version 5.30 of @ccmode{}.
1872 In the transition to @ccmode{} the patterns have been reworked
1873 completely and are applied uniformly across all the languages except AWK
1874 mode, just like the indentation rules (although each language still has
1875 some peculiarities of its own, of course). Since the languages
1876 previously had completely separate font locking patterns, this means
1877 that it's a bit different in most languages now.
1879 The main goal for the font locking in @ccmode{} is accuracy, to provide
1880 a dependable aid in recognizing the various constructs. Some, like
1881 strings and comments, are easy to recognize while others, like
1882 declarations and types, can be very tricky. @ccmode{} can go to great
1883 lengths to recognize declarations and casts correctly, especially when
1884 the types aren't recognized by standard patterns. This is a fairly
1885 demanding analysis which can be slow on older hardware, and it can
1886 therefore be disabled by choosing a lower decoration level with the
1887 variable @code{font-lock-maximum-decoration} (@pxref{Font Lock,,,
1888 emacs, GNU Emacs Manual}).
1890 @vindex font-lock-maximum-decoration
1892 The decoration levels are used as follows:
1897 Minimal font locking: Fontify only comments, strings and preprocessor
1898 directives (in the languages that use cpp).
1902 Fast font locking: In addition to level 1, fontify keywords, simple
1903 types and declarations that are easy to recognize. The variables
1904 @code{*-font-lock-extra-types} (where @samp{*} is the name of the
1905 language) are used to recognize types (see below). Documentation
1906 comments like Javadoc are fontified according to
1907 @code{c-doc-comment-style} (@pxref{Doc Comments}).
1909 Use this if you think the font locking is too slow. It's the closest
1910 corresponding level to level 3 in the old font lock patterns.
1914 Accurate font locking: Like level 2 but uses a different approach that
1915 can recognize types and declarations much more accurately. The
1916 @code{*-font-lock-extra-types} variables are still used, but user
1917 defined types are recognized correctly anyway in most cases. Therefore
1918 those variables should be fairly restrictive and not contain patterns
1921 @cindex Lazy Lock mode
1922 @cindex Just-in-time Lock mode
1924 This level is designed for fairly modern hardware and a font lock
1925 support mode like Lazy Lock or Just-in-time Lock mode that only
1926 fontifies the parts that are actually shown. Fontifying the whole
1927 buffer at once can easily get bothersomely slow even on contemporary
1928 hardware. @xref{Font Lock,,,@emacsman{}, @emacsmantitle{}}.
1931 @cindex user defined types
1932 @cindex types, user defined
1934 Since user defined types are hard to recognize you can provide
1935 additional regexps to match those you use:
1937 @defopt c-font-lock-extra-types
1938 @defoptx c++-font-lock-extra-types
1939 @defoptx objc-font-lock-extra-types
1940 @defoptx java-font-lock-extra-types
1941 @defoptx idl-font-lock-extra-types
1942 @defoptx pike-font-lock-extra-types
1943 For each language there's a variable @code{*-font-lock-extra-types},
1944 where @samp{*} stands for the language in question. It contains a list
1945 of regexps that matches identifiers that should be recognized as types,
1946 e.g., @samp{\\sw+_t} to recognize all identifiers ending with @samp{_t}
1947 as is customary in C code. Each regexp should not match more than a
1950 The default values contain regexps for many types in standard runtime
1951 libraries that are otherwise difficult to recognize, and patterns for
1952 standard type naming conventions like the @samp{_t} suffix in C and C++.
1953 Java, Objective-C and Pike have as a convention to start class names
1954 with capitals, so there are patterns for that in those languages.
1956 Despite the names of these variables, they are not only used for
1957 fontification but in other places as well where @ccmode{} needs to
1962 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1963 @node Faces, Doc Comments, Font Locking Preliminaries, Font Locking
1964 @comment node-name, next, previous, up
1967 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1969 @ccmode{} attempts to use the standard faces for programming languages
1970 in accordance with their intended purposes as far as possible. No extra
1971 faces are currently provided, with the exception of a replacement face
1972 @code{c-invalid-face} for emacsen that don't provide
1973 @code{font-lock-warning-face}.
1977 @vindex font-lock-comment-face
1978 Normal comments are fontified in @code{font-lock-comment-face}.
1981 @vindex font-lock-doc-face
1982 @vindex font-lock-doc-string-face
1983 @vindex font-lock-comment-face
1984 Comments that are recognized as documentation (@pxref{Doc Comments})
1985 get @code{font-lock-doc-face} (Emacs) or
1986 @code{font-lock-doc-string-face} (XEmacs) if those faces exist. If
1987 they don't then @code{font-lock-comment-face} is used.
1990 @vindex font-lock-string-face
1991 String and character literals are fontified in
1992 @code{font-lock-string-face}.
1995 @vindex font-lock-keyword-face
1996 Keywords are fontified with @code{font-lock-keyword-face}.
1999 @vindex font-lock-function-name-face
2000 @code{font-lock-function-name-face} is used for function names in
2001 declarations and definitions, and classes in those contexts. It's also
2002 used for preprocessor defines with arguments.
2005 @vindex font-lock-variable-name-face
2006 Variables in declarations and definitions, and other identifiers in such
2007 variable contexts, get @code{font-lock-variable-name-face}. It's also
2008 used for preprocessor defines without arguments.
2011 @vindex font-lock-constant-face
2012 @vindex font-lock-reference-face
2013 Builtin constants are fontified in @code{font-lock-constant-face} if it
2014 exists, @code{font-lock-reference-face} otherwise. As opposed to the
2015 preceding two faces, this is used on the names in expressions, and it's
2016 not used in declarations, even if there happen to be a @samp{const} in
2020 @vindex font-lock-type-face
2021 @code{font-lock-type-face} is put on types (both predefined and user
2022 defined) and classes in type contexts.
2025 @vindex font-lock-constant-face
2026 @vindex font-lock-reference-face
2027 Label identifiers get @code{font-lock-constant-face} if it exists,
2028 @code{font-lock-reference-face} otherwise.
2031 Name qualifiers and identifiers for scope constructs are fontified like
2035 Special markup inside documentation comments are also fontified like
2039 @vindex font-lock-preprocessor-face
2040 @vindex font-lock-builtin-face
2041 @vindex font-lock-reference-face
2042 Preprocessor directives get @code{font-lock-preprocessor-face} if it
2043 exists (i.e., XEmacs). In Emacs they get @code{font-lock-builtin-face}
2044 or @code{font-lock-reference-face}, for lack of a closer equivalent.
2047 @vindex font-lock-warning-face
2048 @vindex c-invalid-face
2049 @vindex invalid-face @r{(c-)}
2050 Some kinds of syntactic errors are fontified with
2051 @code{font-lock-warning-face} in Emacs. In older XEmacs versions
2052 there's no corresponding standard face, so there a special
2053 @code{c-invalid-face} is used, which is defined to stand out sharply by
2056 Note that it's not used for @samp{#error} or @samp{#warning} directives,
2057 since those aren't syntactic errors in themselves.
2061 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2062 @node Doc Comments, Misc Font Locking, Faces, Font Locking
2063 @comment node-name, next, previous, up
2064 @section Documentation Comments
2065 @cindex documentation comments
2066 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2068 There are various tools to supply documentation in the source as
2069 specially structured comments, e.g., the standard Javadoc tool in Java.
2070 @ccmode{} provides an extensible mechanism to fontify such comments and
2071 the special markup inside them.
2073 @defopt c-doc-comment-style
2074 @vindex doc-comment-style @r{(c-)}
2075 This is a style variable that specifies which documentation comment
2076 style to recognize, e.g., @code{javadoc} for Javadoc comments.
2078 The value may also be a list of styles, in which case all of them are
2079 recognized simultaneously (presumably with markup cues that don't
2082 The value may also be an association list to specify different comment
2083 styles for different languages. The symbol for the major mode is then
2084 looked up in the alist, and the value of that element is interpreted as
2085 above if found. If it isn't found then the symbol @code{other} is looked up
2086 and its value is used instead.
2088 The default value for @code{c-doc-comment-style} is
2089 @w{@code{((java-mode . javadoc) (pike-mode . autodoc) (c-mode . gtkdoc))}}.
2091 Note that @ccmode{} uses this variable to set other variables that
2092 handle fontification etc. That's done at mode initialization or when
2093 you switch to a style which sets this variable. Thus, if you change it
2094 in some other way, e.g., interactively in a CC Mode buffer, you will need
2095 to do @kbd{M-x java-mode} (or whatever mode you're currently using) to
2098 @findex c-setup-doc-comment-style
2099 @findex setup-doc-comment-style @r{(c-)}
2100 Note also that when @ccmode{} starts up, the other variables are
2101 modified before the mode hooks are run. If you change this variable in
2102 a mode hook, you'll have to call @code{c-setup-doc-comment-style}
2103 afterwards to redo that work.
2106 @ccmode{} currently provides handing of the following doc comment
2111 @cindex Javadoc markup
2112 Javadoc comments, the standard tool in Java.
2115 @cindex Pike autodoc markup
2116 For Pike autodoc markup, the standard in Pike.
2119 @cindex GtkDoc markup
2120 For GtkDoc markup, widely used in the Gnome community.
2123 The above is by no means complete. If you'd like to see support for
2124 other doc comment styles, please let us know (@pxref{Mailing Lists and
2127 You can also write your own doc comment fontification support to use
2128 with @code{c-doc-comment-style}: Supply a variable or function
2129 @code{*-font-lock-keywords} where @samp{*} is the name you want to use
2130 in @code{c-doc-comment-style}. If it's a variable, it's prepended to
2131 @code{font-lock-keywords}. If it's a function, it's called at mode
2132 initialization and the result is prepended. For an example, see
2133 @code{javadoc-font-lock-keywords} in @file{cc-fonts.el}.
2135 If you add support for another doc comment style, please consider
2136 contributing it: send a note to @email{bug-cc-mode@@gnu.org}.
2138 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2139 @node Misc Font Locking, AWK Mode Font Locking, Doc Comments, Font Locking
2140 @comment node-name, next, previous, up
2141 @section Miscellaneous Font Locking
2142 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2144 In some languages, particularly in C++, there are constructs which are
2145 syntactically ambiguous---they could be either declarations or
2146 expressions, and @ccmode{} cannot tell for sure which. Often such a
2147 construct is one of the operators @samp{*} or @samp{&} surrounded by
2150 Experience shows that very often when such a construct is a
2151 declaration it will be written with the operator touching exactly one
2152 of the identifiers, like:
2162 . Whether such code is fontified depends on the setting of
2163 @code{c-asymmetry-fontification-flag}.
2165 @defvar c-asymmetry-fontification-flag
2166 @vindex asymmetry-fontification-flag @r{(c-)}
2167 When @code{c-asymmetry-fontification-flag} is non-nil (which it is by
2168 default), code like the above, with white space either before or after
2169 the operator, but not both, is fontified as a declaration. When the
2170 variable is nil, such a construct gets the default face.
2173 When the construct is an expression there will often be white space
2174 both before and after the operator or there will be no white space
2175 around it at all, like:
2186 Such code is not fontified as a declaration. (Typically, the
2187 identifiers don't get a non-default face.)
2189 For clarity's sake, we emphasize that the ``asymmetry'' rule in this
2190 section only applies when CC Mode cannot disambiguate a construct in
2193 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2194 @node AWK Mode Font Locking, , Misc Font Locking, Font Locking
2195 @comment node-name, next, previous, up
2196 @section AWK Mode Font Locking
2197 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2199 The general appearance of font-locking in AWK mode is much like in any
2200 other programming mode. @xref{Faces for Font Lock,,,elisp, GNU Emacs
2201 Lisp Reference Manual}.
2203 The following faces are, however, used in a non-standard fashion in
2207 @item @code{font-lock-variable-name-face}
2208 This face was intended for variable declarations. Since variables are
2209 not declared in AWK, this face is used instead for AWK system
2210 variables (such as @code{NF}) and ``Special File Names'' (such as
2211 @code{"/dev/stderr"}).
2213 @item @code{font-lock-builtin-face} (Emacs)/@code{font-lock-preprocessor-face} (XEmacs)
2214 This face is normally used for preprocessor directives in @ccmode{}.
2215 There are no such things in AWK, so this face is used instead for
2216 standard functions (such as @code{match}).
2218 @item @code{font-lock-string-face}
2219 As well as being used for strings, including localizable strings,
2220 (delimited by @samp{"} and @samp{_"}), this face is also used for AWK
2221 regular expressions (delimited by @samp{/}).
2223 @item @code{font-lock-warning-face} (Emacs)/@code{c-invalid-face} (XEmacs)
2224 This face highlights the following syntactically invalid AWK
2229 An unterminated string or regular expression. Here the opening
2230 delimiter (@samp{"} or @samp{/} or @samp{_"}) is displayed in
2231 @code{font-lock-warning-face}. This is most noticeable when typing in a
2232 new string/regular expression into a buffer, when the warning-face
2233 serves as a continual reminder to terminate the construct.
2235 AWK mode fontifies unterminated strings/regular expressions
2236 differently from other modes: Only the text up to the end of the line
2237 is fontified as a string (escaped newlines being handled correctly),
2238 rather than the text up to the next string quote.
2241 A space between the function name and opening parenthesis when calling
2242 a user function. The last character of the function name and the
2243 opening parenthesis are highlighted. This font-locking rule will
2244 spuriously highlight a valid concatenation expression where an
2245 identifier precedes a parenthesized expression. Unfortunately.
2248 Whitespace following the @samp{\} in what otherwise looks like an
2249 escaped newline. The @samp{\} is highlighted.
2254 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2255 @node Config Basics, Custom Filling and Breaking, Font Locking, Top
2256 @comment node-name, next, previous, up
2257 @chapter Configuration Basics
2258 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2260 @cindex Emacs Initialization File
2261 @cindex Configuration
2262 You configure @ccmode{} by setting Lisp variables and calling (and
2263 perhaps writing) Lisp functions@footnote{DON'T PANIC!!! This isn't
2264 difficult.}, which is usually done by adding code to an Emacs
2265 initialization file. This file might be @file{site-start.el} or
2266 @file{.emacs} or @file{init.el} or @file{default.el} or perhaps some
2267 other file. @xref{Init File,,,@emacsman{}, @emacsmantitle{}}. For
2268 the sake of conciseness, we just call this file ``your @file{.emacs}''
2269 throughout the rest of the manual.
2271 Several of these variables (currently 16), are known collectively as
2272 @dfn{style variables}. @ccmode{} provides a special mechanism, known
2273 as @dfn{styles} to make it easier to set these variables as a group,
2274 to ``inherit'' settings from one style into another, and so on. Style
2275 variables remain ordinary Lisp variables, whose values can be read and
2276 changed independently of the style system. @xref{Style Variables}.
2278 There are several ways you can write the code, depending on the
2279 precise effect you want---they are described further down on this page.
2280 If you are new to @ccmode{}, we suggest you begin with the simplest
2281 method, ``Top-level commands or the customization interface''.
2283 If you make conflicting settings in several of these ways, the way
2284 that takes precedence is the one that appears latest in this list:
2289 @itemx File Style@footnote{In earlier versions of @ccmode{}, a File Style setting took precedence over any other setting apart from a File Local Variable setting.}
2290 @itemx Top-level command or ``customization interface''
2292 @itemx File Local Variable setting
2296 Here is a summary of the different ways of writing your configuration
2300 @item Top-level commands or the ``customization interface''
2301 Most simply, you can write @code{setq} and similar commands at the top
2302 level of your @file{.emacs} file. When you load a @ccmode{} buffer,
2303 it initializes its configuration from these global values (at least,
2304 for those settings you have given values to), so it makes sense to
2305 have these @code{setq} commands run @emph{before} @ccmode{} is first
2306 initialized---in particular, before any call to @code{desktop-read}
2307 (@pxref{Saving Emacs Sessions,,, emacs, GNU Emacs Manual}). For
2308 example, you might set c-basic-offset thus:
2311 (setq c-basic-offset 4)
2314 You can use the more user friendly Customization interface instead,
2315 but this manual does not cover in detail how that works. To do this,
2316 start by typing @kbd{M-x customize-group @key{RET} c @key{RET}}.
2317 @xref{Easy Customization,,,@emacsman{}, @emacsmantitle{}}.
2318 @c The following note really belongs in the Emacs manual.
2319 Emacs normally writes the customizations at the end of your
2320 @file{.emacs} file. If you use @code{desktop-read}, you should edit
2321 your @file{.emacs} to place the call to @code{desktop-read} @emph{after}
2324 The first initialization of @ccmode{} puts a snapshot of the
2325 configuration settings into the special style @code{user}.
2326 @xref{Built-in Styles}.
2328 For basic use of Emacs, either of these ways of configuring is
2329 adequate. However, the settings are then the same in all @ccmode{}
2330 buffers and it can be clumsy to communicate them between programmers.
2331 For more flexibility, you'll want to use one (or both) of @ccmode{}'s
2332 more sophisticated facilities, hooks and styles.
2335 An Emacs @dfn{hook} is a place to put Lisp functions that you want
2336 Emacs to execute later in specific circumstances.
2337 @xref{Hooks,,,@lispref{}, @lispreftitle{}}. @ccmode{} supplies a main
2338 hook and a language-specific hook for each language it supports; any
2339 functions you put onto these hooks get executed as the last part of a
2340 buffer's initialization. Typically you put most of your customization
2341 within the main hook, and use the language-specific hooks to vary the
2342 customization settings between language modes. For example, if you
2343 wanted different (non-standard) values of @code{c-basic-offset} in C
2344 Mode and Java Mode buffers, you could do it like this:
2348 (defun my-c-mode-hook ()
2349 (setq c-basic-offset 3))
2350 (add-hook 'c-mode-hook 'my-c-mode-hook)
2352 (defun my-java-mode-hook ()
2353 (setq c-basic-offset 6))
2354 (add-hook 'java-mode-hook 'my-java-mode-hook)
2358 See @ref{CC Hooks} for more details on the use of @ccmode{} hooks.
2361 A @ccmode{} @dfn{style} is a coherent collection of customizations
2362 with a name. At any time, exactly one style is active in each
2363 @ccmode{} buffer, either the one you have selected or a default.
2364 @ccmode{} is delivered with several existing styles. Additionally,
2365 you can create your own styles, possibly based on these existing
2366 styles. If you worked in a programming team called the ``Free
2367 Group'', which had its own coding standards, you might well have this
2368 in your @file{.emacs} file:
2371 (setq c-default-style '((java-mode . "java")
2373 (other . "free-group-style")))
2376 See @ref{Styles} for fuller details on using @ccmode{} styles and how
2379 @item File Local Variable setting
2380 A @dfn{file local variable setting} is a setting which applies to an
2381 individual source file. You put this in a @dfn{local variables list},
2382 a special block at the end of the source file (@pxref{Specifying File
2383 Variables,,,@emacsman{}}).
2386 A @dfn{file style} is a rarely used variant of the ``style'' mechanism
2387 described above, which applies to an individual source file.
2388 @xref{File Styles}. You use this by setting certain special variables
2389 in a local variables list (@pxref{Specifying File
2390 Variables,,,@emacsman{}}).
2392 @item Hooks with Styles
2393 For ultimate flexibility, you can use hooks and styles together. For
2394 example, if your team were developing a product which required a
2395 Linux driver, you'd probably want to use the ``linux'' style for the
2396 driver, and your own team's style for the rest of the code. You
2397 could achieve this with code like this in your @file{.emacs}:
2401 (defun my-c-mode-hook ()
2403 (if (and (buffer-file-name)
2404 (string-match "/usr/src/linux" (buffer-file-name)))
2406 "free-group-style")))
2407 (add-hook 'c-mode-hook 'my-c-mode-hook)
2411 In a programming team, a hook is also a good place for each member
2412 to put his own personal preferences. For example, you might be the
2413 only person in your team who likes Auto-newline minor mode. You could
2414 have it enabled by default by placing the following in your
2419 (defun my-turn-on-auto-newline ()
2420 (c-toggle-auto-newline 1))
2421 (add-hook 'c-mode-common-hook 'my-turn-on-auto-newline)
2432 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2433 @node CC Hooks, Style Variables, Config Basics, Config Basics
2434 @comment node-name, next, previous, up
2437 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2438 @c The node name is "CC Hooks" rather than "Hooks" because of a bug in
2439 @c some older versions of Info, e.g., the info.el in GNU Emacs 21.3.
2440 @c If you go to "Config Basics" and hit <CR> on the xref to "CC
2441 @c Hooks" the function Info-follow-reference searches for "*Note: CC
2442 @c Hooks" from the beginning of the page. If this node were instead
2443 @c named "Hooks", that search would spuriously find "*Note:
2444 @c Hooks(elisp)" and go to the wrong node.
2446 @ccmode{} provides several hooks that you can use to customize the
2447 mode for your coding style. The main hook is
2448 @code{c-mode-common-hook}; typically, you'll put the bulk of your
2449 customizations here. In addition, each language mode has its own
2450 hook, allowing you to fine tune your settings individually for the
2451 different @ccmode{} languages, and there is a package initialization
2452 hook. Finally, there is @code{c-special-indent-hook}, which enables
2453 you to solve anomalous indentation problems. It is described in
2454 @ref{Other Indentation}, not here. All these hooks adhere to the
2455 standard Emacs conventions.
2457 When you open a buffer, @ccmode{} first initializes it with the
2458 currently active style (@pxref{Styles}). Then it calls
2459 @code{c-mode-common-hook}, and finally it calls the language-specific
2460 hook. Thus, any style settings done in these hooks will override
2461 those set by @code{c-default-style}.
2463 @defvar c-initialization-hook
2464 @vindex initialization-hook @r{(c-)}
2465 Hook run only once per Emacs session, when @ccmode{} is initialized.
2466 This is a good place to change key bindings (or add new ones) in any
2467 of the @ccmode{} key maps. @xref{Sample Init File}.
2470 @defvar c-mode-common-hook
2471 @vindex mode-common-hook @r{(c-)}
2472 Common hook across all languages. It's run immediately before the
2473 language specific hook.
2477 @defvarx c++-mode-hook
2478 @defvarx objc-mode-hook
2479 @defvarx java-mode-hook
2480 @defvarx idl-mode-hook
2481 @defvarx pike-mode-hook
2482 @defvarx awk-mode-hook
2483 The language specific mode hooks. The appropriate one is run as the
2484 last thing when you enter that language mode.
2487 Although these hooks are variables defined in @ccmode{}, you can give
2488 them values before @ccmode{}'s code is loaded---indeed, this is the
2489 only way to use @code{c-initialization-hook}. Their values aren't
2490 overwritten when @ccmode{} gets loaded.
2492 Here's a simplified example of what you can add to your @file{.emacs}
2493 file to do things whenever any @ccmode{} language is edited. See the
2494 Emacs manuals for more information on customizing Emacs via hooks.
2495 @xref{Sample Init File}, for a more complete sample @file{.emacs}
2499 (defun my-c-mode-common-hook ()
2500 ;; my customizations for all of c-mode and related modes
2501 (no-case-fold-search)
2503 (add-hook 'c-mode-common-hook 'my-c-mode-common-hook)
2506 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2507 @node Style Variables, Styles, CC Hooks, Config Basics
2508 @comment node-name, next, previous, up
2509 @section Style Variables
2511 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2513 @cindex style variables
2514 The variables that @ccmode{}'s style system control are called
2515 @dfn{style variables}. Note that style variables are ordinary Lisp
2516 variables, which the style system initializes; you can change their
2517 values at any time (e.g., in a hook function). The style system can
2518 also set other variables, to some extent. @xref{Styles}.
2520 @dfn{Style variables} are handled specially in several ways:
2524 Style variables are by default buffer-local variables. However, they
2525 can instead be made global by setting
2526 @code{c-style-variables-are-local-p} to @code{nil} before @ccmode{} is
2530 @vindex c-old-style-variable-behavior
2531 @vindex old-style-variable-behavior @r{(c-)}
2532 The default global binding of any style variable (with two exceptions
2533 - see below) is the special symbol @code{set-from-style}. When the
2534 style system initializes a buffer-local copy of a style variable for a
2535 @ccmode{} buffer, if its global binding is still that symbol then it
2536 will be set from the current style. Otherwise it will retain its
2537 global default@footnote{This is a big change from versions of
2538 @ccmode{} earlier than 5.26, where such settings would get overridden
2539 by the style system unless special precautions were taken. That was
2540 changed since it was counterintuitive and confusing, especially to
2541 novice users. If your configuration depends on the old overriding
2542 behavior, you can set the variable
2543 @code{c-old-style-variable-behavior} to non-@code{nil}.}. This
2544 ``otherwise'' happens, for example, when you've set the variable with
2545 @code{setq} at the top level of your @file{.emacs} (@pxref{Config
2549 The style variable @code{c-offsets-alist} (@pxref{c-offsets-alist}) is
2550 an association list with an element for each syntactic symbol. It's
2551 handled a little differently from the other style variables. It's
2552 default global binding is the empty list @code{nil}, rather than
2553 @code{set-from-style}. Before the style system is initialized, you
2554 can add individual elements to @code{c-offsets-alist} by calling
2555 @code{c-set-offset} (@pxref{c-offsets-alist}) just like you would set
2556 other style variables with @code{setq}. Those elements will then
2557 prevail when the style system later initializes a buffer-local copy of
2558 @code{c-offsets-alist}.
2561 The style variable @code{c-special-indent-hook} is also handled in a
2562 special way. Styles can only add functions to this hook, not remove
2563 them, so any global settings you put on it are always
2564 preserved@footnote{This did not change in version 5.26.}. The value
2565 you give this variable in a style definition can be either a function
2566 or a list of functions.
2569 The global bindings of the style variables get captured in the special
2570 @code{user} style when the style system is first initialized.
2571 @xref{Built-in Styles}, for details.
2574 The style variables are:@*
2575 @code{c-indent-comment-alist},
2576 @code{c-indent-comments-syntactically-p} (@pxref{Indentation
2578 @code{c-doc-comment-style} (@pxref{Doc Comments});@*
2579 @code{c-block-comment-prefix}, @code{c-comment-prefix-regexp}
2580 (@pxref{Custom Filling and Breaking});@*
2581 @code{c-hanging-braces-alist} (@pxref{Hanging Braces});@*
2582 @code{c-hanging-colons-alist} (@pxref{Hanging Colons});@*
2583 @code{c-hanging-semi&comma-criteria} (@pxref{Hanging Semicolons and
2585 @code{c-cleanup-list} (@pxref{Clean-ups});@*
2586 @code{c-basic-offset} (@pxref{Customizing Indentation});@*
2587 @code{c-offsets-alist} (@pxref{c-offsets-alist});@*
2588 @code{c-comment-only-line-offset} (@pxref{Comment Line-Up});@*
2589 @code{c-special-indent-hook}, @code{c-label-minimum-indentation}
2590 (@pxref{Other Indentation});@*
2591 @code{c-backslash-column}, @code{c-backslash-max-column}
2592 (@pxref{Custom Macros}).
2594 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2595 @node Styles, , Style Variables, Config Basics
2596 @comment node-name, next, previous, up
2599 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2601 By @dfn{style} we mean the layout of the code---things like how many
2602 columns to indent a block of code, whether an opening brace gets
2603 indented to the level of the code it encloses, or of the construct
2604 that introduces it, or ``hangs'' at the end of a line.
2606 Most people only need to edit code formatted in just a few well-defined
2607 and consistent styles. For example, their organization might impose a
2608 ``blessed'' style that all its programmers must conform to. Similarly,
2609 people who work on GNU software will have to use the GNU coding style.
2610 Some shops are more lenient, allowing a variety of coding styles, and as
2611 programmers come and go, there could be a number of styles in use. For
2612 this reason, @ccmode{} makes it convenient for you to set up logical
2613 groupings of customizations called @dfn{styles}, associate a single name
2614 for any particular style, and pretty easily start editing new or
2615 existing code using these styles.
2617 As an alternative to writing a style definition yourself, you can have
2618 @ccmode{} @dfn{guess} (at least part of) your style by looking at an
2619 already formatted piece of your code, @ref{Guessing the Style}.
2623 * Choosing a Style::
2625 * Guessing the Style::
2629 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2630 @node Built-in Styles, Choosing a Style, Styles, Styles
2631 @comment node-name, next, previous, up
2632 @subsection Built-in Styles
2633 @cindex styles, built-in
2634 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2636 If you're lucky, one of @ccmode{}'s built-in styles might be just
2637 what you're looking for. These are:
2642 Coding style blessed by the Free Software Foundation
2643 for C code in GNU programs.
2647 The classic Kernighan and Ritchie style for C code. If you're looking
2648 for the style used in the 2nd edition of their book ``The C
2649 Programming Language'', then check out the @code{stroustrup} style.
2653 Also known as ``Allman style'' after Eric Allman.
2656 @cindex Whitesmith style
2657 Popularized by the examples that came with Whitesmiths C, an early
2658 commercial C compiler.
2661 @cindex Stroustrup style
2662 The classic Stroustrup style for C++ code.
2665 @cindex Ellemtel style
2666 Popular C++ coding standards as defined by ``Programming in C++, Rules
2667 and Recommendations,'' Erik Nyquist and Mats Henricson,
2668 Ellemtel@footnote{This document is available at
2669 @uref{http://www.doc.ic.ac.uk/lab/cplus/c++.rules/} among other
2671 @c N.B. This URL was still valid at 2005/8/28 (ACM).
2675 C coding standard for Linux (the kernel).
2678 @cindex Python style
2679 C coding standard for Python extension modules@footnote{Python is a
2680 high level scripting language with a C/C++ foreign function interface.
2681 For more information, see @uref{http://www.python.org/}.}.
2685 The style for editing Java code. Note that the default
2686 value for @code{c-default-style} installs this style when you enter
2691 The style for editing AWK code. Note that the default value for
2692 @code{c-default-style} installs this style when you enter
2697 This is a special style created by you. It consists of the factory
2698 defaults for all the style variables as modified by the customizations
2699 you do either with the Customization interface or by writing
2700 @code{setq}s and @code{c-set-offset}s at the top level of your
2701 @file{.emacs} file (@pxref{Config Basics}). The style system creates
2702 this style as part of its initialization and doesn't modify it
2707 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2708 @node Choosing a Style, Adding Styles, Built-in Styles, Styles
2709 @comment node-name, next, previous, up
2710 @subsection Choosing a Style
2711 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2713 When you create a new buffer, its style will be set from
2714 @code{c-default-style}. The factory default is the style @code{gnu},
2715 except in Java and AWK modes where it's @code{java} and @code{awk}.
2717 Remember that if you set a style variable with the Customization
2718 interface or at the top level of your @file{.emacs} file before the
2719 style system is initialized (@pxref{Config Basics}), this setting will
2720 override the one that the style system would have given the variable.
2722 To set a buffer's style interactively, use the command @kbd{C-c .}
2723 (@pxref{Other Commands}). To set it from a file's local variable
2724 list, @ref{File Styles}.
2726 @defopt c-default-style
2727 @vindex default-style @r{(c-)}
2728 This variable specifies which style to install by default in new
2729 buffers. It takes either a style name string, or an association list
2730 of major mode symbols to style names:
2734 When @code{c-default-style} is a string, it must be an existing style
2735 name. This style is then used for all modes.
2738 When @code{c-default-style} is an association list, the mode language
2739 is looked up to find a style name string.
2742 If @code{c-default-style} is an association list where the mode
2743 language mode isn't found then the special symbol @samp{other} is
2744 looked up. If it's found then the associated style is used.
2747 If @samp{other} is not found then the @samp{gnu} style is used.
2750 In all cases, the style described in @code{c-default-style} is installed
2751 @emph{before} the language hooks are run, so you can always override
2752 this setting by including an explicit call to @code{c-set-style} in your
2753 language mode hook, or in @code{c-mode-common-hook}.
2755 The standard value of @code{c-default-style} is @w{@code{((java-mode
2756 . "java") (awk-mode . "awk") (other . "gnu"))}}.
2759 @defvar c-indentation-style
2760 @vindex indentation-style @r{(c-)}
2761 This variable always contains the buffer's current style name, as a
2765 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2766 @node Adding Styles, Guessing the Style, Choosing a Style, Styles
2767 @comment node-name, next, previous, up
2768 @subsection Adding and Amending Styles
2769 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2771 If none of the built-in styles is appropriate, you'll probably want to
2772 create a new @dfn{style definition}, possibly based on an existing
2773 style. To do this, put the new style's settings into a list with the
2774 following format; the list can then be passed as an argument to the
2775 function @code{c-add-style}. You can see an example of a style
2776 definition in @ref{Sample Init File}.
2778 @cindex style definition
2779 @c @defvr {List} style definition
2781 @item Structure of a Style Definition List
2782 ([@var{base-style}] [(@var{variable} . @var{value}) @dots{}])
2784 Optional @var{base-style}, if present, must be a string which is the
2785 name of the @dfn{base style} from which this style inherits. At most
2786 one @var{base-style} is allowed in a style definition. If
2787 @var{base-style} is not specified, the style inherits from the table
2788 of factory default values@footnote{This table is stored internally in
2789 the variable c-fallback-style.} instead. All styles eventually
2790 inherit from this internal table. Style loops generate errors. The
2791 list of pre-existing styles can be seen in @ref{Built-in Styles}.
2793 The dotted pairs (@var{variable} . @var{value}) each consist of a
2794 variable and the value it is to be set to when the style is later
2795 activated.@footnote{Note that if the variable has been given a value
2796 by the Customization interface or a @code{setq} at the top level of
2797 your @file{.emacs}, this value will override the one the style system
2798 tries to give it. @xref{Config Basics}.} The variable can be either a
2799 @ccmode{} style variable or an arbitrary Emacs variable. In the
2800 latter case, it is @emph{not} made buffer-local by the @ccmode{} style
2804 Two variables are treated specially in the dotted pair list:
2807 @item c-offsets-alist
2808 The value is in turn a list of dotted pairs of the form
2811 (@r{@var{syntactic-symbol}} . @r{@var{offset}})
2814 as described in @ref{c-offsets-alist}. These are passed to
2815 @code{c-set-offset} so there is no need to set every syntactic symbol
2816 in your style, only those that are different from the inherited style.
2818 @item c-special-indent-hook
2819 The value is added to @code{c-special-indent-hook} using
2820 @code{add-hook}, so any functions already on it are kept. If the value
2821 is a list, each element of the list is added with @code{add-hook}.
2825 Styles are kept in the @code{c-style-alist} variable, but you
2826 should never modify this variable directly. Instead, @ccmode{}
2827 provides the function @code{c-add-style} for this purpose.
2829 @defun c-add-style stylename description &optional set-p
2830 @findex add-style @r{(c-)}
2831 Add or update a style called @var{stylename}, a string.
2832 @var{description} is the new style definition in the form described
2833 above. If @var{stylename} already exists in @code{c-style-alist} then
2834 it is replaced by @var{description}. (Note, this replacement is
2835 total. The old style is @emph{not} merged into the new one.)
2836 Otherwise, a new style is added.
2838 If the optional @var{set-p} is non-@code{nil} then the new style is
2839 applied to the current buffer as well. The use of this facility is
2840 deprecated and it might be removed from @ccmode{} in a future release.
2841 You should use @code{c-set-style} instead.
2843 The sample @file{.emacs} file provides a concrete example of how a new
2844 style can be added and automatically set. @xref{Sample Init File}.
2847 @defvar c-style-alist
2848 @vindex style-alist @r{(c-)}
2849 This is the variable that holds the definitions for the styles. It
2850 should not be changed directly; use @code{c-add-style} instead.
2853 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2854 @node Guessing the Style, File Styles, Adding Styles, Styles
2855 @comment node-name, next, previous, up
2856 @subsection Guessing the Style
2857 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2859 Instead of specifying a style, you can get @ccmode{} to @dfn{guess}
2860 your style by examining an already formatted code buffer. @ccmode{}
2861 then determines the ''most frequent'' offset (@pxref{c-offsets-alist})
2862 for each of the syntactic symbols (@pxref{Indentation Engine Basics})
2863 encountered in the buffer, and the ''most frequent'' value of
2864 c-basic-offset (@pxref{Customizing Indentation}), then merges the
2865 current style with these ''guesses'' to form a new style. This
2866 combined style is known as the @dfn{guessed style}.
2868 To do this, call @code{c-guess} (or one of the other 5 guessing
2869 commands) on your sample buffer. The analysis of your code may take
2872 You can then set the guessed style in any @ccmode{} buffer with
2873 @code{c-guess-install}. You can display the style with
2874 @code{c-guess-view}, and preserve it by copying it into your
2875 @file{.emacs} for future use, preferably after editing it.
2878 @item @kbd{M-x c-guess-no-install}
2879 @itemx @kbd{M-x c-guess-buffer-no-install}
2880 @itemx @kbd{M-x c-guess-region-no-install}
2881 @findex c-guess-no-install
2882 @findex c-guess-buffer-no-install
2883 @findex c-guess-region-no-install
2884 @findex guess-no-install @r{(c-)}
2885 @findex guess-buffer-no-install @r{(c-)}
2886 @findex guess-region-no-install @r{(c-)}
2887 These commands analyze a part of the current buffer and guess the
2890 The part of the buffer examined is either the region
2891 (@code{c-guess-region-no-install}), the entire buffer
2892 (@code{c-guess-buffer-no-install}), or the first
2893 @code{c-guess-region-max} bytes (@code{c-guess-no-install}).
2895 Each of these commands can be given an optional prefix argument. This
2896 instructs @ccmode{} to combine the new guesses with the current
2897 guesses before forming the guessed style.
2901 @item @kbd{M-x c-guess}
2902 @itemx @kbd{M-x c-guess-buffer}
2903 @itemx @kbd{M-x c-guess-region}
2905 @findex c-guess-buffer
2906 @findex c-guess-region
2907 @findex guess @r{(c-)}
2908 @findex guess-buffer @r{(c-)}
2909 @findex guess-region @r{(c-)}
2910 These commands analyze a part of the current buffer, guess the style
2911 from it, then install the guessed style on the buffer. The guessed
2912 style is given a name based on the buffer's absolute file name, and
2913 you can then set this style on any @ccmode{} buffer with @kbd{C-c .}.
2915 The part of the buffer examined is either the region
2916 (@code{c-guess-region}), the entire buffer (@code{c-guess-buffer}), or
2917 the first @code{c-guess-region-max} bytes (@code{c-guess}).
2919 Each of these commands can be given an optional prefix argument. This
2920 instructs @ccmode{} to combine the new guesses with the current
2921 guesses before forming the guessed style.
2924 @defopt c-guess-region-max
2925 @vindex guess-region-max @r{(c-)}
2926 This variable, default 50000, is the size in bytes of the buffer
2927 portion examined by c-guess and c-guess-no-install. If set to
2928 @code{nil}, the entire buffer is examined.
2931 @defopt c-guess-offset-threshold
2932 @vindex guess-offset-threshold @r{(c-)}
2933 This variable, default 10, is the maximum offset, either outwards or
2934 inwards, which will be taken into account by the analysis process.
2935 Any offset bigger than this will be ignored. For no limit, set this
2936 variable to a large number.
2940 @item @kbd{M-x c-guess-install}
2941 @findex c-guess-install
2942 @findex guess-install @r{(c-)}
2944 Set the current buffer's style to the guessed style. This prompts you
2945 to enter an optional new style name to give to the guessed style. By
2946 default, this name is based on the buffer's absolute file name. You
2947 can then use this style like any other.
2949 @item @kbd{M-x c-guess-view}
2950 @findex c-guess-view
2951 @findex guess-view @r{(c-)}
2952 Display the most recently guessed style in a temporary buffer. This
2953 display is in the form of a @code{c-add-style} form (@pxref{Adding
2954 Styles}) which can be easily copied to your @file{.emacs}. You will
2955 probably want to edit it first.
2957 The display of the guessed style contains these elements:
2960 @item Placeholder Name
2961 You should replace this with a style name of your own.
2963 The style current when the guessing began, from which the guessed
2964 style inherits (@pxref{Config Basics}) the settings which weren't
2966 @item Guessed Offsets
2967 These are the core result of the guessing process. Each of them is
2968 marked by a comment.
2969 @item Inherited Offsets
2970 These are syntactic offsets which have been taken over from the parent
2971 style. To avoid possible future conflicts, you should remove either
2972 these offsets or the parent style name.
2976 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2977 @node File Styles, , Guessing the Style, Styles
2978 @comment node-name, next, previous, up
2979 @subsection File Styles
2980 @cindex styles, file local
2981 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2983 @cindex file local variables
2985 The Emacs manual describes how you can customize certain variables on a
2986 per-file basis by including a @dfn{file local variable} block at the end
2987 of the file (@pxref{File Variables,, Local Variables in Files,@emacsman{},
2990 So far, you've only seen a functional interface for setting styles in
2991 @ccmode{}, and this can't be used here. @ccmode{} fills the gap by
2992 providing two variables for use in a file's local variable list.
2993 Don't use them anywhere else! These allow you to customize the style
2994 on a per-file basis:
2996 @defvar c-file-style
2997 @vindex file-style @r{(c-)}
2998 Set this variable to a style name string in the Local Variables list.
2999 From now on, when you visit the file, @ccmode{} will automatically set
3000 the file's style to this one using @code{c-set-style}.
3003 @defvar c-file-offsets
3004 @vindex file-offsets @r{(c-)}
3005 Set this variable (in the Local Variables list) to an association list
3006 of the same format as @code{c-offsets-alist}. From now on, when you
3007 visit the file, @ccmode{} will automatically institute these offsets
3008 using @code{c-set-offset}.
3011 Note that file style settings (i.e., @code{c-file-style}) are applied
3012 before file offset settings
3013 (i.e., @code{c-file-offsets})@footnote{Also, if either of these are set
3014 in a file's local variable section, all the style variable values are
3015 made local to that buffer, even if
3016 @code{c-style-variables-are-local-p} is @code{nil}. Since this
3017 variable is virtually always non-@code{nil} anyhow, you're unlikely to
3018 notice this effect.}.
3020 If you set any variable by the file local variables mechanism, that
3021 setting takes priority over all other settings, even those in your
3022 mode hooks (@pxref{CC Hooks}). Any individual setting of a variable
3023 will override one made through @code{c-file-style} or
3024 @code{c-file-offsets}.
3025 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3026 @node Custom Filling and Breaking, Custom Auto-newlines, Config Basics, Top
3027 @comment node-name, next, previous, up
3028 @chapter Customizing Filling and Line Breaking
3029 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3031 Since there's a lot of normal text in comments and string literals,
3032 @ccmode{} provides features to edit these like in text mode. It does
3033 this by hooking in on the different line breaking functions and tuning
3034 relevant variables as necessary.
3036 @vindex c-comment-prefix-regexp
3037 @vindex comment-prefix-regexp @r{(c-)}
3038 @cindex comment line prefix
3039 @vindex comment-start
3041 @vindex comment-start-skip
3042 @vindex paragraph-start
3043 @vindex paragraph-separate
3044 @vindex paragraph-ignore-fill-prefix
3045 @vindex adaptive-fill-mode
3046 @vindex adaptive-fill-regexp
3047 @vindex adaptive-fill-first-line-regexp
3048 To make Emacs recognize comments and treat text in them as normal
3049 paragraphs, @ccmode{} makes several standard
3050 variables@footnote{@code{comment-start}, @code{comment-end},
3051 @code{comment-start-skip}, @code{paragraph-start},
3052 @code{paragraph-separate}, @code{paragraph-ignore-fill-prefix},
3053 @code{adaptive-fill-mode}, @code{adaptive-fill-regexp}, and
3054 @code{adaptive-fill-first-line-regexp}.} buffer-local and modifies them
3055 according to the language syntax and the comment line prefix.
3057 @defopt c-comment-prefix-regexp
3058 @vindex comment-prefix-regexp @r{(c-)}
3059 This style variable contains the regexp used to recognize the
3060 @dfn{comment line prefix}, which is the line decoration that starts
3061 every line in a comment. The variable is either the comment line
3062 prefix itself, or (more usually) an association list with different
3063 values for different languages. The symbol for the major mode is
3064 looked up in the alist to get the regexp for the language, and if it
3065 isn't found then the special symbol @samp{other} is looked up instead.
3067 When a comment line gets divided by @kbd{M-j} or the like, @ccmode{}
3068 inserts the comment line prefix from a neighboring line at the start
3069 of the new line. The default value of c-comment-prefix-regexp is
3070 @samp{//+\\|\\**}, which matches C++ style line comments like
3077 with two or more slashes in front of them, and the second and
3078 subsequent lines of C style block comments like
3089 with zero or more stars at the beginning of every line. If you change
3090 this variable, please make sure it still matches the comment starter
3091 (i.e., @code{//}) of line comments @emph{and} the line prefix inside
3094 @findex c-setup-paragraph-variables
3095 @findex setup-paragraph-variables @r{(c-)}
3096 Also note that since @ccmode{} uses the value of
3097 @code{c-comment-prefix-regexp} to set up several other variables at
3098 mode initialization, there won't be any effect if you just change it
3099 inside a @ccmode{} buffer. You need to call the command
3100 @code{c-setup-paragraph-variables} too, to update those other
3101 variables. That's also the case if you modify
3102 @code{c-comment-prefix-regexp} in a mode hook, since @ccmode{} will
3103 already have set up these variables before calling the hook.
3106 In comments, @ccmode{} uses @code{c-comment-prefix-regexp} to adapt
3107 the line prefix from the other lines in the comment.
3109 @vindex adaptive-fill-mode
3110 @cindex Adaptive Fill mode
3111 @ccmode{} uses adaptive fill mode (@pxref{Adaptive Fill,,, emacs, GNU
3112 Emacs Manual}) to make Emacs correctly keep the line prefix when
3113 filling paragraphs. That also makes Emacs preserve the text
3114 indentation @emph{inside} the comment line prefix. E.g., in the
3115 following comment, both paragraphs will be filled with the left
3116 margins of the texts kept intact:
3120 /* Make a balanced b-tree of the nodes in the incoming
3121 * stream. But, to quote the famous words of Donald E.
3124 * Beware of bugs in the above code; I have only
3125 * proved it correct, not tried it.
3130 @findex c-setup-filladapt
3131 @findex setup-filladapt @r{(c-)}
3132 @findex filladapt-mode
3133 @vindex filladapt-mode
3134 @cindex Filladapt mode
3135 It's also possible to use other adaptive filling packages, notably Kyle
3136 E. Jones' Filladapt package@footnote{It's available from
3137 @uref{http://www.wonderworks.com/}. As of version 2.12, it does however
3138 lack a feature that makes it work suboptimally when
3139 @code{c-comment-prefix-regexp} matches the empty string (which it does
3140 by default). A patch for that is available from
3141 @uref{http://cc-mode.sourceforge.net/,, the CC Mode web site}.},
3142 @c 2005/11/22: The above is still believed to be the case.
3143 which handles things like bulleted lists nicely. There's a convenience
3144 function @code{c-setup-filladapt} that tunes the relevant variables in
3145 Filladapt for use in @ccmode{}. Call it from a mode hook, e.g., with
3146 something like this in your @file{.emacs}:
3149 (defun my-c-mode-common-hook ()
3152 (add-hook 'c-mode-common-hook 'my-c-mode-common-hook)
3155 @defopt c-block-comment-prefix
3156 @vindex block-comment-prefix @r{(c-)}
3157 @vindex c-comment-continuation-stars
3158 @vindex comment-continuation-stars @r{(c-)}
3159 Normally the comment line prefix inserted for a new line inside a
3160 comment is deduced from other lines in it. However there's one
3161 situation when there's no hint about what the prefix should look like,
3162 namely when a block comment is broken for the first time. This style
3163 variable@footnote{In versions before 5.26, this variable was called
3164 @code{c-comment-continuation-stars}. As a compatibility measure,
3165 @ccmode{} still uses the value on that variable if it's set.} is used
3166 then as the comment prefix. It defaults to @samp{*
3167 }@footnote{Actually, this default setting of
3168 @code{c-block-comment-prefix} typically gets overridden by the default
3169 style @code{gnu}, which sets it to blank. You can see the line
3170 splitting effect described here by setting a different style,
3171 e.g., @code{k&r} @xref{Choosing a Style}.}, which makes a comment
3174 /* Got O(n^2) here, which is a Bad Thing. */
3182 /* Got O(n^2) here, which
3183 * is a Bad Thing. */
3187 Note that it won't work to adjust the indentation by putting leading
3188 spaces in @code{c-block-comment-prefix}, since @ccmode{} still uses the
3189 normal indentation engine to indent the line. Thus, the right way to
3190 fix the indentation is by customizing the @code{c} syntactic symbol. It
3191 defaults to @code{c-lineup-C-comments}, which handles the indentation of
3192 most common comment styles, see @ref{Line-Up Functions}.
3195 @defopt c-ignore-auto-fill
3196 @vindex ignore-auto-fill @r{(c-)}
3197 When auto fill mode is enabled, @ccmode{} can selectively ignore it
3198 depending on the context the line break would occur in, e.g., to never
3199 break a line automatically inside a string literal. This variable
3200 takes a list of symbols for the different contexts where auto-filling
3205 Inside a string or character literal.
3207 Inside a C style block comment.
3209 Inside a C++ style line comment.
3211 Inside a preprocessor directive.
3213 Anywhere else, i.e., in normal code.
3216 By default, @code{c-ignore-auto-fill} is set to @code{(string cpp
3217 code)}, which means that when auto-fill mode is activated,
3218 auto-filling only occurs in comments. In literals, it's often
3219 desirable to have explicit control over newlines. In preprocessor
3220 directives, the necessary @samp{\} escape character before the newline
3221 is not automatically inserted, so an automatic line break would
3222 produce invalid code. In normal code, line breaks are normally
3223 dictated by some logical structure in the code rather than the last
3224 whitespace character, so automatic line breaks there will produce poor
3225 results in the current implementation.
3228 @vindex comment-multi-line
3229 If inside a comment and @code{comment-multi-line} (@pxref{Auto
3230 Fill,,,@emacsman{}, @emacsmantitle{}} is non-@code{nil}, the
3232 line prefix are preserved. If inside a comment and
3233 @code{comment-multi-line} is @code{nil}, a new comment of the same
3234 type is started on the next line and indented as appropriate for
3237 Note that @ccmode{} sets @code{comment-multi-line} to @code{t} at
3238 startup. The reason is that @kbd{M-j} could otherwise produce sequences
3239 of single line block comments for texts that should logically be treated
3240 as one comment, and the rest of the paragraph handling code
3241 (e.g., @kbd{M-q} and @kbd{M-a}) can't cope with that, which would lead to
3242 inconsistent behavior.
3244 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3245 @node Custom Auto-newlines, Clean-ups, Custom Filling and Breaking, Top
3246 @comment node-name, next, previous, up
3247 @chapter Customizing Auto-newlines
3248 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3250 @ccmode{} determines whether to insert auto-newlines in two basically
3251 different ways, depending on the character just typed:
3254 @item Braces and Colons
3255 @ccmode{} first determines the syntactic context of the brace or colon
3256 (@pxref{Syntactic Symbols}), then looks for a corresponding element in
3257 an alist. This element specifies where to put newlines: this is any
3258 combination of before and after the brace or colon. If no alist
3259 element is found, newlines are inserted both before and after a brace,
3260 but none are inserted around a colon. See @ref{Hanging Braces} and
3261 @ref{Hanging Colons}.
3263 @item Semicolons and Commas
3264 The variable @code{c-hanging-semi&comma-criteria} contains a list of
3265 functions which determine whether to insert a newline after a newly
3266 typed semicolon or comma. @xref{Hanging Semicolons and Commas}.
3269 The names of these configuration variables contain @samp{hanging}
3270 because they let you @dfn{hang} the pertinent characters. A character
3271 which introduces a C construct is said to @dfn{hang on the right} when
3272 it appears at the end of a line after other code, being separated by a
3273 line break from the construct it introduces, like the opening brace in:
3285 A character @dfn{hangs on the left} when it appears at the start of
3286 the line after the construct it closes off, like the above closing
3289 The next chapter, ``Clean-ups'', describes how to configure @ccmode{}
3290 to remove these automatically added newlines in certain specific
3291 circumstances. @xref{Clean-ups}.
3296 * Hanging Semicolons and Commas::
3300 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3301 @node Hanging Braces, Hanging Colons, Custom Auto-newlines, Custom Auto-newlines
3302 @comment node-name, next, previous, up
3303 @section Hanging Braces
3304 @cindex hanging braces
3305 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3307 To specify which kinds of braces you want auto-newlines put around,
3308 you set the style variable @code{c-hanging-braces-alist}. Its
3309 structure and semantics are described in this section. Details of how
3310 to set it up, and its relationship to CC Mode's style system are given
3311 in @ref{Style Variables}.
3313 Say you wanted an auto-newline after (but not before) the following
3321 First you need to find the @dfn{syntactic context} of the brace---type
3322 a @key{RET} before the brace to get it on a line of its
3323 own@footnote{Also insert a @samp{\} at the end of the previous line if
3324 you're in AWK Mode.}, then type @kbd{C-c C-s}. That will tell you
3328 ((substatement-open 1061))
3332 So here you need to put the entry @code{(substatement-open . (after))}
3333 into @code{c-hanging-braces-alist}.
3335 If you don't want any auto-newlines for a particular syntactic symbol,
3336 put this into @code{c-hanging-braces-alist}:
3342 If some brace syntactic symbol is not in @code{c-hanging-brace-alist},
3343 its entry is taken by default as @code{(before after)}---insert a
3344 newline both before and after the brace. In place of a
3345 ``before/after'' list you can specify a function in this alist---this
3346 is useful when the auto newlines depend on the code around the brace.
3348 @defopt c-hanging-braces-alist
3349 @vindex hanging-braces-alist @r{(c-)}
3351 This variable is an association list which maps syntactic symbols to
3352 lists of places to insert a newline. @xref{Association
3353 Lists,,,@lispref{}, @lispreftitle{}}. The key of each element is the
3354 syntactic symbol, the associated value is either @code{nil}, a list,
3358 @item The Key: the syntactic symbol
3359 The syntactic symbols that are useful as keys in this list are
3360 @code{brace-list-intro}, @code{statement-cont},
3361 @code{inexpr-class-open}, @code{inexpr-class-close}, and all the
3362 @code{*-open} and @code{*-close} symbols. @xref{Syntactic Symbols},
3363 for a more detailed description of these syntactic symbols, except for
3364 @code{inexpr-class-open} and @code{inexpr-class-close}, which aren't
3365 actual syntactic symbols. Elements with any other value as a key get
3368 The braces of anonymous inner classes in Java are given the special
3369 symbols @code{inexpr-class-open} and @code{inexpr-class-close}, so that
3370 they can be distinguished from the braces of normal classes@footnote{The
3371 braces of anonymous classes produce a combination of
3372 @code{inexpr-class}, and @code{class-open} or @code{class-close} in
3373 normal indentation analysis.}.
3375 Note that the aggregate constructs in Pike mode, @samp{(@{}, @samp{@})},
3376 @samp{([}, @samp{])}, and @samp{(<}, @samp{>)}, do not count as brace
3377 lists in this regard, even though they do for normal indentation
3378 purposes. It's currently not possible to set automatic newlines on
3381 @item The associated value: the ``ACTION'' list or function
3382 The value associated with each syntactic symbol in this association
3383 list is called an @var{action}, which can be either a list or a
3384 function which returns a list. @xref{Custom Braces}, for how to use
3385 a function as a brace hanging @var{action}.
3387 The list @var{action} (or the list returned by @var{action} when it's
3388 a function) contains some combination of the symbols @code{before} and
3389 @code{after}, directing @ccmode{} where to put newlines in
3390 relationship to the brace being inserted. Thus, if the list contains
3391 only the symbol @code{after}, then the brace hangs on the right side
3395 // here, open braces always 'hang'
3396 void spam( int i ) @{
3403 When the list contains both @code{after} and @code{before}, the braces
3404 will appear on a line by themselves, as shown by the close braces in
3405 the above example. The list can also be empty, in which case newlines
3406 are added neither before nor after the brace.
3409 If a syntactic symbol is missing entirely from
3410 @code{c-hanging-braces-alist}, it's treated in the same way as an
3411 @var{action} with a list containing @code{before} and @code{after}, so
3412 that braces by default end up on their own line.
3414 For example, the default value of @code{c-hanging-braces-alist} is:
3420 (substatement-open after)
3421 (block-close . c-snug-do-while)
3422 (extern-lang-open after)
3423 (namespace-open after)
3425 (composition-open after)
3426 (inexpr-class-open after)
3427 (inexpr-class-close before))
3430 @noindent which says that @code{brace-list-open},
3431 @code{brace-entry-open} and @code{statement-cont}@footnote{Brace lists
3432 inside statements, such as initializers for static array variables
3433 inside functions in C, are recognized as @code{statement-cont}. All
3434 normal substatement blocks are recognized with other symbols.} braces
3435 should both hang on the right side and allow subsequent text to follow
3436 on the same line as the brace. Also, @code{substatement-open},
3437 @code{extern-lang-open}, and @code{inexpr-class-open} braces should hang
3438 on the right side, but subsequent text should follow on the next line.
3439 The opposite holds for @code{inexpr-class-close} braces; they won't
3440 hang, but the following text continues on the same line. Here, in the
3441 @code{block-close} entry, you also see an example of using a function as
3442 an @var{action}. In all other cases, braces are put on a line by
3450 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3451 @node Custom Braces, , Hanging Braces, Hanging Braces
3452 @comment node-name, next, previous, up
3453 @subsection Custom Brace Hanging
3454 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3456 @vindex c-hanging-braces-alist
3457 @vindex hanging-braces-alist @r{(c-)}
3458 @cindex action functions
3459 Syntactic symbols aren't the only place where you can customize
3460 @ccmode{} with the lisp equivalent of callback functions. Remember
3461 that @var{action}s are usually a list containing some combination of
3462 the symbols @code{before} and @code{after} (@pxref{Hanging Braces}).
3463 For more flexibility, you can instead specify brace ``hanginess'' by
3464 giving a syntactic symbol an @dfn{action function} in
3465 @code{c-hanging-braces-alist}; this function determines the
3466 ``hanginess'' of a brace, usually by looking at the code near it.
3468 @cindex customization, brace hanging
3469 An action function is called with two arguments: the syntactic symbol
3470 for the brace (e.g., @code{substatement-open}), and the buffer position
3471 where the brace has been inserted. Point is undefined on entry to an
3472 action function, but the function must preserve it (e.g., by using
3473 @code{save-excursion}). The return value should be a list containing
3474 some combination of @code{before} and @code{after}, including neither
3475 of them (i.e., @code{nil}).
3477 @defvar c-syntactic-context
3478 @vindex syntactic-context @r{(c-)}
3479 During the call to the indentation or brace hanging @var{action}
3480 function, this variable is bound to the full syntactic analysis list.
3481 This might be, for example, @samp{((block-close 73))}. Don't ever
3482 give @code{c-syntactic-context} a value yourself---this would disrupt
3483 the proper functioning of @ccmode{}.
3485 This variable is also bound in three other circumstances:
3486 (i)@w{ }when calling a c-hanging-semi&comma-criteria function
3487 (@pxref{Hanging Semicolons and Commas}); (ii)@w{ }when calling a
3488 line-up function (@pxref{Custom Line-Up}); (iii)@w{ }when calling a
3489 c-special-indent-hook function (@pxref{Other Indentation}).
3492 As an example, @ccmode{} itself uses this feature to dynamically
3493 determine the hanginess of braces which close ``do-while''
3497 void do_list( int count, char** atleast_one_string )
3501 handle_string( atleast_one_string[i] );
3503 @} while( i < count );
3507 @ccmode{} assigns the @code{block-close} syntactic symbol to the
3508 brace that closes the @code{do} construct, and normally we'd like the
3509 line that follows a @code{block-close} brace to begin on a separate
3510 line. However, with ``do-while'' constructs, we want the
3511 @code{while} clause to follow the closing brace. To do this, we
3512 associate the @code{block-close} symbol with the @var{action} function
3513 @code{c-snug-do-while}:
3516 (defun c-snug-do-while (syntax pos)
3517 "Dynamically calculate brace hanginess for do-while statements."
3520 (if (and (eq syntax 'block-close)
3521 (setq langelem (assq 'block-close c-syntactic-context))
3522 (progn (goto-char (cdr langelem))
3523 (if (= (following-char) ?@{)
3525 (looking-at "\\<do\\>[^_]")))
3530 @findex c-snug-do-while
3531 @findex snug-do-while @r{(c-)}
3532 This function simply looks to see if the brace closes a ``do-while''
3533 clause and if so, returns the list @samp{(before)} indicating
3534 that a newline should be inserted before the brace, but not after it.
3535 In all other cases, it returns the list @samp{(before after)} so
3536 that the brace appears on a line by itself.
3538 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3539 @node Hanging Colons, Hanging Semicolons and Commas, Hanging Braces, Custom Auto-newlines
3540 @comment node-name, next, previous, up
3541 @section Hanging Colons
3542 @cindex hanging colons
3543 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3545 @cindex customization, colon hanging
3546 @vindex c-hanging-colons-alist
3547 @vindex hanging-colons-alist @r{(c-)}
3549 Using a mechanism similar to brace hanging (@pxref{Hanging Braces}),
3550 colons can also be made to hang using the style variable
3551 @code{c-hanging-colons-alist}: when a colon is typed, @ccmode
3552 determines its syntactic context, looks this up in the alist
3553 @code{c-changing-colons-alist} and inserts up to two newlines
3554 accordingly. Here, however, If @ccmode fails to find an entry for a
3555 syntactic symbol in the alist, no newlines are inserted around the
3558 @defopt c-hanging-colons-alist
3559 @vindex hanging-colons-alist @r{(c-)}
3562 @item The Key: the syntactic symbol
3563 The syntactic symbols appropriate as keys in this association list
3564 are: @code{case-label}, @code{label}, @code{access-label},
3565 @code{member-init-intro}, and @code{inher-intro}. @xref{Syntactic
3566 Symbols}. Elements with any other value as a key get ignored.
3568 @item The associated value: the ``ACTION'' list
3569 The @var{action} here is simply a list containing a combination of the
3570 symbols @code{before} and @code{after}. Unlike in
3571 @code{c-hanging-braces-alist}, functions as @var{actions} are not
3572 supported; there doesn't seem to be any need for them.
3576 In C++, double-colons are used as a scope operator but because these
3577 colons always appear right next to each other, newlines before and after
3578 them are controlled by a different mechanism, called @dfn{clean-ups} in
3579 @ccmode{}. @xref{Clean-ups}, for details.
3581 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3582 @node Hanging Semicolons and Commas, , Hanging Colons, Custom Auto-newlines
3583 @comment node-name, next, previous, up
3584 @section Hanging Semicolons and Commas
3585 @cindex hanging semicolons
3586 @cindex hanging commas
3587 @cindex customization, semicolon newlines
3588 @cindex customization, comma newlines
3589 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3591 @defopt c-hanging-semi&comma-criteria
3592 @vindex hanging-semi&comma-criteria @r{(c-)}
3593 This style variable takes a list of functions; these get called when
3594 you type a semicolon or comma. The functions are called in order
3595 without arguments. When these functions are entered, point is just
3596 after the newly inserted @samp{;} or @samp{,} and they must preserve
3597 point (e.g., by using @code{save-excursion}). During the call, the
3598 variable @code{c-syntactic-context} is bound to the syntactic context
3599 of the current line@footnote{This was first introduced in @ccmode{}
3600 5.31.} @pxref{Custom Braces}. These functions don't insert newlines
3601 themselves, rather they direct @ccmode{} whether or not to do so.
3602 They should return one of the following values:
3606 A newline is to be inserted after the @samp{;} or @samp{,}, and no
3607 more functions from the list are to be called.
3609 No more functions from the list are to be called, and no newline is to
3612 No determination has been made, and the next function in the list is
3616 Note that auto-newlines are never inserted @emph{before} a semicolon
3617 or comma. If every function in the list is called without a
3618 determination being made, then no newline is added.
3620 In AWK mode, this variable is set by default to @code{nil}. In the
3621 other modes, the default value is a list containing a single function,
3622 @code{c-semi&comma-inside-parenlist}. This inserts newlines after all
3623 semicolons, apart from those separating @code{for}-clause statements.
3626 @defun c-semi&comma-no-newlines-before-nonblanks
3627 @findex semi&comma-no-newlines-before-nonblanks @r{(c-)}
3628 This is an example of a criteria function, provided by @ccmode{}. It
3629 prevents newlines from being inserted after semicolons when there is a
3630 non-blank following line. Otherwise, it makes no determination. To
3631 use, add this function to the front of the
3632 @code{c-hanging-semi&comma-criteria} list.
3635 (defun c-semi&comma-no-newlines-before-nonblanks ()
3637 (if (and (= (c-last-command-char) ?\;)
3638 (zerop (forward-line 1))
3639 (bolp) ; forward-line has funny behavior at eob.
3640 (not (looking-at "^[ \t]*$")))
3646 @defun c-semi&comma-inside-parenlist
3647 @findex semi&comma-inside-parenlist @r{(c-)}
3648 @defunx c-semi&comma-no-newlines-for-oneline-inliners
3649 @findex semi&comma-no-newlines-for-oneline-inliners @r{(c-)}
3650 The function @code{c-semi&comma-inside-parenlist} is what prevents
3651 newlines from being inserted inside the parenthesis list of @code{for}
3652 statements. In addition to
3653 @code{c-semi&comma-no-newlines-before-nonblanks} described above,
3654 @ccmode{} also comes with the criteria function
3655 @code{c-semi&comma-no-newlines-for-oneline-inliners}, which suppresses
3656 newlines after semicolons inside one-line inline method definitions
3657 (e.g., in C++ or Java).
3661 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3662 @node Clean-ups, Indentation Engine Basics, Custom Auto-newlines, Top
3663 @comment node-name, next, previous, up
3666 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3668 @dfn{Clean-ups} are mechanisms which remove (or exceptionally, add)
3669 whitespace in specific circumstances and are complementary to colon
3670 and brace hanging. You enable a clean-up by adding its symbol into
3671 @code{c-cleanup-list}, e.g., like this:
3674 (add-to-list 'c-cleanup-list 'space-before-funcall)
3677 On the surface, it would seem that clean-ups overlap the functionality
3678 provided by the @code{c-hanging-*-alist} variables. Clean-ups,
3679 however, are used to adjust code ``after-the-fact'', i.e., to adjust
3680 the whitespace in constructs later than when they were typed.
3682 Most of the clean-ups remove automatically inserted newlines, and are
3683 only active when auto-newline minor mode is turned on. Others will
3684 work all the time. Note that clean-ups are only performed when there
3685 is nothing but whitespace appearing between the individual components
3686 of the construct, and (apart from @code{comment-close-slash}) when the
3687 construct does not occur within a literal (@pxref{Auto-newlines}).
3689 @defopt c-cleanup-list
3690 @vindex cleanup-list @r{(c-)}
3693 You configure @ccmode{}'s clean-ups by setting the style variable
3694 @code{c-cleanup-list}, which is a list of clean-up symbols. By
3695 default, @ccmode{} cleans up only the @code{scope-operator} construct,
3696 which is necessary for proper C++ support.
3699 These are the clean-ups that are only active when electric and
3700 auto-newline minor modes are enabled:
3702 @c TBD: Would like to use some sort of @deffoo here; @table indents a
3703 @c bit too much in dvi output.
3705 @item brace-else-brace
3706 Clean up @samp{@} else @{} constructs by placing the entire construct on
3707 a single line. Clean up occurs when the open brace after the
3708 @samp{else} is typed. So for example, this:
3723 appears like this after the last open brace is typed:
3735 @item brace-elseif-brace
3736 Similar to the @code{brace-else-brace} clean-up, but this cleans up
3737 @samp{@} else if (...) @{} constructs. For example:
3752 appears like this after the last open parenthesis is typed:
3765 and like this after the last open brace is typed:
3773 @} else if( i==3 ) @{
3777 @item brace-catch-brace
3778 Analogous to @code{brace-elseif-brace}, but cleans up @samp{@} catch
3779 (...) @{} in C++ and Java mode.
3781 @item empty-defun-braces
3782 Clean up braces following a top-level function or class definition that
3783 contains no body. Clean up occurs when the closing brace is typed.
3795 is transformed into this when the close brace is typed:
3804 @item defun-close-semi
3805 Clean up the terminating semicolon on top-level function or class
3806 definitions when they follow a close brace. Clean up occurs when the
3807 semicolon is typed. So for example, the following:
3820 is transformed into this when the semicolon is typed:
3831 @item list-close-comma
3832 Clean up commas following braces in array and aggregate initializers.
3833 Clean up occurs when the comma is typed. The space before the comma
3834 is zapped just like the space before the semicolon in
3835 @code{defun-close-semi}.
3837 @item scope-operator
3838 Clean up double colons which might designate a C++ scope operator split
3839 across multiple lines@footnote{Certain C++ constructs introduce
3840 ambiguous situations, so @code{scope-operator} clean-ups might not
3841 always be correct. This usually only occurs when scoped identifiers
3842 appear in switch label tags.}. Clean up occurs when the second colon is
3843 typed. You will always want @code{scope-operator} in the
3844 @code{c-cleanup-list} when you are editing C++ code.
3846 @item one-liner-defun
3847 Clean up a single line of code enclosed by defun braces by removing
3848 the whitespace before and after the code. The clean-up happens when
3849 the closing brace is typed. If the variable
3850 @code{c-max-one-liner-length} is set, the cleanup is only done if the
3851 resulting line would be no longer than the value of that variable.
3853 For example, consider this AWK code:
3858 FS = "\t" # use <TAB> as a field separator
3864 It gets compacted to the following when the closing brace is typed:
3868 BEGIN @{FS = "\t"@} # use <TAB> as a field separator
3872 @defopt c-max-one-liner-length
3873 @vindex max-one-liner-length @r{(c-)}
3874 The maximum length of the resulting line for which the clean-up
3875 @code{one-liner-defun} will be triggered. This length is that of the entire
3876 line, including any leading whitespace and any trailing comment. Its
3877 default value is 80. If the value is zero or @code{nil}, no limit
3882 The following clean-ups are always active when they occur on
3883 @code{c-cleanup-list}, regardless of whether Electric minor mode or
3884 Auto-newline minor mode are enabled:
3887 @item space-before-funcall
3888 Insert a space between the function name and the opening parenthesis
3889 of a function call. This produces function calls in the style
3890 mandated by the GNU coding standards, e.g., @samp{signal@w{ }(SIGINT,
3891 SIG_IGN)} and @samp{abort@w{ }()}. Clean up occurs when the opening
3892 parenthesis is typed. This clean-up should never be active in AWK
3893 Mode, since such a space is syntactically invalid for user defined
3896 @item compact-empty-funcall
3897 Clean up any space between the function name and the opening parenthesis
3898 of a function call that has no arguments. This is typically used
3899 together with @code{space-before-funcall} if you prefer the GNU function
3900 call style for functions with arguments but think it looks ugly when
3901 it's only an empty parenthesis pair. I.e., you will get @samp{signal
3902 (SIGINT, SIG_IGN)}, but @samp{abort()}. Clean up occurs when the
3903 closing parenthesis is typed.
3905 @item comment-close-slash
3906 When inside a block comment, terminate the comment when you type a slash
3907 at the beginning of a line (i.e., immediately after the comment prefix).
3908 This clean-up removes whitespace preceding the slash and if needed,
3909 inserts a star to complete the token @samp{*/}. Type @kbd{C-q /} in this
3910 situation if you just want a literal @samp{/} inserted.
3914 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3915 @node Indentation Engine Basics, Customizing Indentation, Clean-ups, Top
3916 @comment node-name, next, previous, up
3917 @chapter Indentation Engine Basics
3918 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3920 This chapter will briefly cover how @ccmode{} indents lines of code.
3921 It is helpful to understand the indentation model being used so that
3922 you will know how to customize @ccmode{} for your personal coding
3923 style. All the details are in @ref{Customizing Indentation}.
3925 @ccmode{} has an indentation engine that provides a flexible and
3926 general mechanism for customizing indentation. When @ccmode{} indents
3927 a line of code, it separates its calculations into two steps:
3931 @cindex syntactic symbol
3932 @cindex anchor position
3933 It analyzes the line to determine its @dfn{syntactic symbol(s)} (the
3934 kind of language construct it's looking at) and its @dfn{anchor
3935 position} (the position earlier in the file that @ccmode{} will indent
3936 the line relative to). The anchor position might be the location of
3937 an opening brace in the previous line, for example. @xref{Syntactic
3941 @cindex indentation offset specifications
3942 It looks up the syntactic symbol(s) in the configuration to get the
3943 corresponding @dfn{offset(s)}. The symbol @code{+}, which means
3944 ``indent this line one more level'' is a typical offset. @ccmode{}
3945 then applies these offset(s) to the anchor position, giving the
3946 indentation for the line. The different sorts of offsets are
3947 described in @ref{c-offsets-alist}.
3950 In exceptional circumstances, the syntax directed indentation
3951 described here may be a nuisance rather than a help. You can disable
3952 it by setting @code{c-syntactic-indentation} to @code{nil}. (To set
3953 the variable interactively, @ref{Minor Modes}).
3955 @defopt c-syntactic-indentation
3956 @vindex syntactic-indentation @r{(c-)}
3957 When this is non-@code{nil} (which it is by default), the indentation
3958 of code is done according to its syntactic structure. When it's
3959 @code{nil}, every line is just indented to the same level as the
3960 previous one, and @kbd{TAB} (@code{c-indent-command}) adjusts the
3961 indentation in steps of @code{c-basic-offset}. The current style
3962 (@pxref{Config Basics}) then has no effect on indentation, nor do any
3963 of the variables associated with indentation, not even
3964 @code{c-special-indent-hook}.
3968 * Syntactic Analysis::
3969 * Syntactic Symbols::
3970 * Indentation Calculation::
3974 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3975 @node Syntactic Analysis, Syntactic Symbols, Indentation Engine Basics, Indentation Engine Basics
3976 @comment node-name, next, previous, up
3977 @section Syntactic Analysis
3978 @cindex syntactic analysis
3979 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3981 @cindex syntactic element
3982 @cindex syntactic context
3983 The first thing @ccmode{} does when indenting a line of code, is to
3984 analyze the line by calling @code{c-guess-basic-syntax}, determining
3985 the syntactic context of the (first) construct on that line. Although
3986 this function is mainly used internally, it can sometimes be useful in
3987 Line-up functions (@pxref{Custom Line-Up}) or in functions on
3988 @code{c-special-indent-hook} (@pxref{Other Indentation}).
3990 @defun c-guess-basic-syntax
3991 @findex guess-basic-syntax @r{(c-)}
3992 Determine the syntactic context of the current line.
3995 The @dfn{syntactic context} is a list of @dfn{syntactic elements},
3996 where each syntactic element in turn is a list@footnote{In
3997 @ccmode 5.28 and earlier, a syntactic element was a dotted pair; the
3998 cons was the syntactic symbol and the cdr was the anchor position.
3999 For compatibility's sake, the parameter passed to a line-up function
4000 still has this dotted pair form (@pxref{Custom Line-Up}).} Here is a
4001 brief and typical example:
4004 ((defun-block-intro 1959))
4007 @cindex syntactic symbol
4009 The first thing inside each syntactic element is always a
4010 @dfn{syntactic symbol}. It describes the kind of construct that was
4011 recognized, e.g., @code{statement}, @code{substatement},
4012 @code{class-open}, @code{class-close}, etc. @xref{Syntactic Symbols},
4013 for a complete list of currently recognized syntactic symbols and
4014 their semantics. The remaining entries are various data associated
4015 with the recognized construct; there might be zero or more.
4017 @cindex anchor position
4018 Conceptually, a line of code is always indented relative to some
4019 position higher up in the buffer (typically the indentation of the
4020 previous line). That position is the @dfn{anchor position} in the
4021 syntactic element. If there is an entry after the syntactic symbol in
4022 the syntactic element list then it's either @code{nil} or that anchor position.
4024 Here is an example. Suppose we had the following code as the only thing
4025 in a C++ buffer @footnote{The line numbers in this and future examples
4026 don't actually appear in the buffer, of course!}:
4029 1: void swap( int& a, int& b )
4038 We can use @kbd{C-c C-s} (@code{c-show-syntactic-information}) to
4039 report what the syntactic analysis is for the current line:
4042 @item @kbd{C-c C-s} (@code{c-show-syntactic-information})
4044 @findex c-show-syntactic-information
4045 @findex show-syntactic-information @r{(c-)}
4046 This command calculates the syntactic analysis of the current line and
4047 displays it in the minibuffer. The command also highlights the anchor
4051 Running this command on line 4 of this example, we'd see in the echo
4052 area@footnote{With a universal argument (i.e., @kbd{C-u C-c C-s}) the
4053 analysis is inserted into the buffer as a comment on the current
4061 and the @samp{i} of @code{int} on line 3 would be highlighted. This
4062 tells us that the line is a statement and it is indented relative to
4063 buffer position 35, the highlighted position. If you were to move
4064 point to line 3 and hit @kbd{C-c C-s}, you would see:
4067 ((defun-block-intro 29))
4071 This indicates that the @samp{int} line is the first statement in a top
4072 level function block, and is indented relative to buffer position 29,
4073 which is the brace just after the function header.
4075 Here's another example:
4078 1: int add( int val, int incr, int doit )
4082 5: return( val + incr );
4089 Hitting @kbd{C-c C-s} on line 4 gives us:
4092 ((substatement-open 46))
4095 @cindex substatement
4096 @cindex substatement block
4098 which tells us that this is a brace that @emph{opens} a substatement
4099 block.@footnote{A @dfn{substatement} is the line after a
4100 conditional statement, such as @code{if}, @code{else}, @code{while},
4101 @code{do}, @code{switch}, etc. A @dfn{substatement
4102 block} is a brace block following one of these conditional statements.}
4104 @cindex comment-only line
4105 Syntactic contexts can contain more than one element, and syntactic
4106 elements need not have anchor positions. The most common example of
4107 this is a @dfn{comment-only line}:
4110 1: void draw_list( List<Drawables>& drawables )
4112 3: // call the virtual draw() method on each element in list
4113 4: for( int i=0; i < drawables.count(), ++i )
4115 6: drawables[i].draw();
4121 Hitting @kbd{C-c C-s} on line 3 of this example gives:
4124 ((comment-intro) (defun-block-intro 46))
4128 and you can see that the syntactic context contains two syntactic
4129 elements. Notice that the first element, @samp{(comment-intro)}, has no
4133 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4134 @node Syntactic Symbols, Indentation Calculation, Syntactic Analysis, Indentation Engine Basics
4135 @comment node-name, next, previous, up
4136 @section Syntactic Symbols
4137 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4139 @cindex syntactic symbols, brief list
4140 @vindex c-offsets-alist
4141 @vindex offsets-alist @r{(c-)}
4142 This section is a complete list of the syntactic symbols which appear
4143 in the @code{c-offsets-alist} style variable, along with brief
4144 descriptions. The previous section (@pxref{Syntactic Analysis})
4145 states what syntactic symbols are and how the indentation engine uses
4148 More detailed descriptions of these symbols, together with snippets of
4149 source code to which they apply, appear in the examples in the
4150 subsections below. Note that, in the interests of brevity, the anchor
4151 position associated with most syntactic symbols is @emph{not}
4152 specified. In cases of doubt, type @kbd{C-c C-s} on a pertinent
4153 line---this highlights the anchor position.
4155 @ssindex -open symbols
4156 @ssindex -close symbols
4157 @ssindex -block-intro symbols
4158 The syntactic symbols which indicate brace constructs follow a general
4159 naming convention. When a line begins with an open or close brace,
4160 its syntactic symbol will contain the suffix @code{-open} or
4161 @code{-close} respectively. The first line within the brace block
4162 construct will contain the suffix @code{-block-intro}.
4164 @ssindex -intro symbols
4165 @ssindex -cont symbols
4166 In constructs which can span several lines, a distinction is usually
4167 made between the first line that introduces the construct and the
4168 lines that continue it. The syntactic symbols that indicate these
4169 lines will contain the suffixes @code{-intro} or @code{-cont}
4172 The best way to understand how all this works is by looking at some
4173 examples. Remember that you can see the syntax of any source code
4174 line by using @kbd{C-c C-s}.
4178 Inside a multiline string. @ref{Literal Symbols}.
4180 Inside a multiline C style block comment. @ref{Literal Symbols}.
4182 Brace that opens a top-level function definition. @ref{Function
4185 Brace that closes a top-level function definition. @ref{Function
4187 @item defun-block-intro
4188 The first line in a top-level defun. @ref{Function Symbols}.
4190 Brace that opens a class definition. @ref{Class Symbols}.
4192 Brace that closes a class definition. @ref{Class Symbols}.
4194 Brace that opens an in-class inline method. @ref{Class Symbols}.
4196 Brace that closes an in-class inline method. @ref{Class Symbols}.
4197 @item func-decl-cont
4198 The region between a function definition's argument list and the
4199 function opening brace (excluding K&R argument declarations). In C,
4200 you cannot put anything but whitespace and comments in this region,
4201 however in C++ and Java, @code{throws} declarations and other things
4202 can appear here. @ref{Literal Symbols}. @c @emph{FIXME!!! Can it not
4203 @c go somewhere better?}
4204 @item knr-argdecl-intro
4205 First line of a K&R C argument declaration. @ref{K&R Symbols}.
4207 Subsequent lines in a K&R C argument declaration. @ref{K&R Symbols}.
4209 The first line in a ``topmost'' definition. @ref{Function Symbols}.
4210 @item topmost-intro-cont
4211 Topmost definition continuation lines. This is only used in the parts
4212 that aren't covered by other symbols such as @code{func-decl-cont} and
4213 @code{knr-argdecl}. @ref{Function Symbols}.
4214 @item annotation-top-cont
4215 Topmost definition continuation lines where all previous items are
4216 annotations. @ref{Java Symbols}.
4217 @item member-init-intro
4218 First line in a member initialization list. @ref{Class Symbols}.
4219 @item member-init-cont
4220 Subsequent member initialization list lines. @ref{Class Symbols}.
4222 First line of a multiple inheritance list. @ref{Class Symbols}.
4224 Subsequent multiple inheritance lines. @ref{Class Symbols}.
4226 Statement block open brace. @ref{Literal Symbols}.
4228 Statement block close brace. @ref{Conditional Construct Symbols}.
4229 @item brace-list-open
4230 Open brace of an enum or static array list. @ref{Brace List Symbols}.
4231 @item brace-list-close
4232 Close brace of an enum or static array list. @ref{Brace List Symbols}.
4233 @item brace-list-intro
4234 First line after the opening @samp{@{} in an enum or static array
4235 list. @ref{Brace List Symbols}.
4236 @item brace-list-entry
4237 Subsequent lines in an enum or static array list. @ref{Brace List
4239 @item brace-entry-open
4240 Subsequent lines in an enum or static array list where the line begins
4241 with an open brace. @ref{Brace List Symbols}.
4243 A statement. @ref{Function Symbols}.
4244 @item statement-cont
4245 A continuation of a statement. @ref{Function Symbols}.
4246 @item annotation-var-cont
4247 A continuation of a statement where all previous items are
4248 annotations. @ref{Java Symbols}.
4249 @item statement-block-intro
4250 The first line in a new statement block. @ref{Conditional Construct
4252 @item statement-case-intro
4253 The first line in a case block. @ref{Switch Statement Symbols}.
4254 @item statement-case-open
4255 The first line in a case block that starts with a brace. @ref{Switch
4258 The first line after a conditional or loop construct.
4259 @ref{Conditional Construct Symbols}.
4260 @item substatement-open
4261 The brace that opens a substatement block. @ref{Conditional Construct
4263 @item substatement-label
4264 The first line after a conditional or loop construct if it's a label.
4265 @ref{Conditional Construct Symbols}.
4267 A label in a @code{switch} block. @ref{Switch Statement Symbols}.
4269 C++ access control label. @ref{Class Symbols}.
4271 Any other label. @ref{Literal Symbols}.
4272 @item do-while-closure
4273 The @code{while} line that ends a @code{do}-@code{while} construct.
4274 @ref{Conditional Construct Symbols}.
4276 The @code{else} line of an @code{if}-@code{else} construct.
4277 @ref{Conditional Construct Symbols}.
4279 The @code{catch} or @code{finally} (in Java) line of a
4280 @code{try}-@code{catch} construct. @ref{Conditional Construct
4283 A line containing only a comment introduction. @ref{Literal Symbols}.
4285 The first line in an argument list. @ref{Paren List Symbols}.
4287 Subsequent argument list lines when no arguments follow on the same
4288 line as the arglist opening paren. @ref{Paren List Symbols}.
4289 @item arglist-cont-nonempty
4290 Subsequent argument list lines when at least one argument follows on
4291 the same line as the arglist opening paren. @ref{Paren List Symbols}.
4293 The solo close paren of an argument list. @ref{Paren List Symbols}.
4295 Lines continuing a stream operator (C++ only). @ref{Literal
4296 Symbols}. @c @emph{FIXME!!! Can this not be moved somewhere better?}
4298 The line is nested inside a class definition. @ref{Class Symbols}.
4300 The start of a preprocessor macro definition. @ref{Literal Symbols}.
4301 @item cpp-define-intro
4302 The first line inside a multiline preprocessor macro if
4303 @code{c-syntactic-indentation-in-macros} is set. @ref{Multiline Macro
4305 @item cpp-macro-cont
4306 All lines inside multiline preprocessor macros if
4307 @code{c-syntactic-indentation-in-macros} is @code{nil}.
4308 @ref{Multiline Macro Symbols}.
4310 A C++ friend declaration. @ref{Class Symbols}.
4311 @item objc-method-intro
4312 The first line of an Objective-C method definition. @ref{Objective-C
4314 @item objc-method-args-cont
4315 Lines continuing an Objective-C method definition. @ref{Objective-C
4317 @item objc-method-call-cont
4318 Lines continuing an Objective-C method call. @ref{Objective-C Method
4320 @item extern-lang-open
4321 Brace that opens an @code{extern} block (e.g., @code{extern "C"
4322 @{...@}}). @ref{External Scope Symbols}.
4323 @item extern-lang-close
4324 Brace that closes an @code{extern} block. @ref{External Scope
4327 Analogous to @code{inclass} syntactic symbol, but used inside
4328 @code{extern} blocks. @ref{External Scope Symbols}.
4329 @item namespace-open
4330 @itemx namespace-close
4332 These are analogous to the three @code{extern-lang} symbols above, but
4333 are returned for C++ namespace blocks. @ref{External Scope Symbols}.
4337 Analogous to the above, but for CORBA IDL @code{module} blocks.
4338 @ref{External Scope Symbols}.
4339 @item composition-open
4340 @itemx composition-close
4341 @itemx incomposition
4342 Analogous to the above, but for CORBA CIDL @code{composition} blocks.
4343 @ref{External Scope Symbols}.
4344 @item template-args-cont
4345 C++ template argument list continuations. @ref{Class Symbols}.
4347 Analogous to @code{inclass} syntactic symbol, but used inside lambda
4348 (i.e., anonymous) functions. Used in C++ and Pike modes.
4349 @ref{Statement Block Symbols}.
4350 @item lambda-intro-cont
4351 Lines continuing the header of a lambda function, i.e., between the
4352 @code{lambda} keyword and the function body. Only used in Pike mode.
4353 @ref{Statement Block Symbols}.
4354 @item inexpr-statement
4355 A statement block inside an expression. The gcc C and C++ extension
4356 for this is recognized. It's also used for the special functions that
4357 take a statement block as an argument in Pike. @ref{Statement Block
4360 A class definition inside an expression. This is used for anonymous
4361 classes in Java. It's also used for anonymous array initializers in
4362 Java. @ref{Java Symbols}.
4366 * Function Symbols::
4368 * Conditional Construct Symbols::
4369 * Switch Statement Symbols::
4370 * Brace List Symbols::
4371 * External Scope Symbols::
4372 * Paren List Symbols::
4374 * Multiline Macro Symbols::
4375 * Objective-C Method Symbols::
4377 * Statement Block Symbols::
4381 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4382 @node Function Symbols, Class Symbols, Syntactic Symbols, Syntactic Symbols
4383 @comment node-name, next, previous, up
4384 @subsection Function Symbols
4385 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4387 This example shows a typical function declaration.
4391 2: swap( int& a, int& b )
4401 @ssindex topmost-intro
4402 @ssindex topmost-intro-cont
4404 @ssindex defun-close
4405 @ssindex defun-block-intro
4406 Line 1 shows a @code{topmost-intro} since it is the first line that
4407 introduces a top-level construct. Line 2 is a continuation of the
4408 top-level construct introduction so it has the syntax
4409 @code{topmost-intro-cont}. Line 3 shows a @code{defun-open} since it is
4410 the brace that opens a top-level function definition. Line 9 is the
4412 @code{defun-close} since it contains the brace that closes the top-level
4413 function definition. Line 4 is a @code{defun-block-intro}, i.e., it is
4414 the first line of a brace-block, enclosed in a
4415 top-level function definition.
4418 @ssindex statement-cont
4419 Lines 5, 6, and 7 are all given @code{statement} syntax since there
4420 isn't much special about them. Note however that line 8 is given
4421 @code{statement-cont} syntax since it continues the statement begun
4422 on the previous line.
4424 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4425 @node Class Symbols, Conditional Construct Symbols, Function Symbols, Syntactic Symbols
4426 @comment node-name, next, previous, up
4427 @subsection Class related Symbols
4428 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4430 Here's an example which illustrates some C++ class syntactic symbols:
4435 3: public Amplifiable
4439 7: : eString( new BassString( 0.105 )),
4440 8: aString( new BassString( 0.085 )),
4441 9: dString( new BassString( 0.065 )),
4442 10: gString( new BassString( 0.045 ))
4444 12: eString.tune( 'E' );
4445 13: aString.tune( 'A' );
4446 14: dString.tune( 'D' );
4447 15: gString.tune( 'G' );
4449 17: friend class Luthier;
4454 @ssindex class-close
4455 As in the previous example, line 1 has the @code{topmost-intro} syntax.
4456 Here however, the brace that opens a C++ class definition on line 4 is
4457 assigned the @code{class-open} syntax. Note that in C++, classes,
4458 structs, and unions are essentially equivalent syntactically (and are
4459 very similar semantically), so replacing the @code{class} keyword in the
4460 example above with @code{struct} or @code{union} would still result in a
4461 syntax of @code{class-open} for line 4 @footnote{This is the case even
4462 for C and Objective-C@. For consistency, structs in all supported
4463 languages are syntactically equivalent to classes. Note however that
4464 the keyword @code{class} is meaningless in C and Objective-C.}.
4465 Similarly, line 18 is assigned @code{class-close} syntax.
4467 @ssindex inher-intro
4469 Line 2 introduces the inheritance list for the class so it is assigned
4470 the @code{inher-intro} syntax, and line 3, which continues the
4471 inheritance list is given @code{inher-cont} syntax.
4473 @ssindex access-label
4475 Hitting @kbd{C-c C-s} on line 5 shows the following analysis:
4478 ((inclass 58) (access-label 58))
4482 The primary syntactic symbol for this line is @code{access-label} as
4483 this is a label keyword that specifies access protection in C++. However,
4484 because this line is also a top-level construct inside a class
4485 definition, the analysis actually shows two syntactic symbols. The
4486 other syntactic symbol assigned to this line is @code{inclass}.
4487 Similarly, line 6 is given both @code{inclass} and @code{topmost-intro}
4491 ((inclass 58) (topmost-intro 60))
4494 @ssindex member-init-intro
4495 @ssindex member-init-cont
4496 Line 7 introduces a C++ member initialization list and as such is given
4497 @code{member-init-intro} syntax. Note that in this case it is
4498 @emph{not} assigned @code{inclass} since this is not considered a
4499 top-level construct. Lines 8 through 10 are all assigned
4500 @code{member-init-cont} since they continue the member initialization
4501 list started on line 7.
4503 @cindex in-class inline methods
4504 @ssindex inline-open
4505 @ssindex inline-close
4506 Line 11's analysis is a bit more complicated:
4509 ((inclass 58) (inline-open))
4512 This line is assigned a syntax of both @code{inline-open} and
4513 @code{inclass} because it opens an @dfn{in-class} C++ inline method
4514 definition. This is distinct from, but related to, the C++ notion of an
4515 inline function in that its definition occurs inside an enclosing class
4516 definition, which in C++ implies that the function should be inlined.
4517 However, if the definition of the @code{Bass} constructor appeared
4518 outside the class definition, the construct would be given the
4519 @code{defun-open} syntax, even if the keyword @code{inline} appeared
4520 before the method name, as in:
4525 3: public Amplifiable
4533 11: : eString( new BassString( 0.105 )),
4534 12: aString( new BassString( 0.085 )),
4535 13: dString( new BassString( 0.065 )),
4536 14: gString( new BassString( 0.045 ))
4538 16: eString.tune( 'E' );
4539 17: aString.tune( 'A' );
4540 18: dString.tune( 'D' );
4541 19: gString.tune( 'G' );
4546 Returning to the previous example, line 16 is given @code{inline-close}
4547 syntax, while line 12 is given @code{defun-block-open} syntax, and lines
4548 13 through 15 are all given @code{statement} syntax. Line 17 is
4549 interesting in that its syntactic analysis list contains three
4553 ((inclass 58) (topmost-intro 380) (friend))
4556 The @code{friend} and @code{inline-open} syntactic symbols are
4557 modifiers that do not have anchor positions.
4559 @ssindex template-args-cont
4560 Template definitions introduce yet another syntactic symbol:
4563 1: ThingManager <int,
4564 2: Framework::Callback *,
4565 3: Mutex> framework_callbacks;
4568 Here, line 1 is analyzed as a @code{topmost-intro}, but lines 2 and 3
4569 are both analyzed as @code{template-args-cont} lines.
4571 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4572 @node Conditional Construct Symbols, Switch Statement Symbols, Class Symbols, Syntactic Symbols
4573 @comment node-name, next, previous, up
4574 @subsection Conditional Construct Symbols
4575 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4577 Here is a (totally contrived) example which illustrates how syntax is
4578 assigned to various conditional constructs:
4581 1: void spam( int index )
4583 3: for( int i=0; i<index; i++ )
4586 6: do_something_special();
4589 9: do_something( i );
4592 12: another_thing( i-- );
4598 Only the lines that illustrate new syntactic symbols will be discussed.
4600 @ssindex substatement-open
4601 @ssindex statement-block-intro
4602 @ssindex block-close
4603 Line 4 has a brace which opens a conditional's substatement block. It
4604 is thus assigned @code{substatement-open} syntax, and since line 5 is
4605 the first line in the substatement block, it is assigned
4606 @code{statement-block-intro} syntax. Line 10 contains the brace
4607 that closes the inner substatement block, and is therefore given the
4608 syntax @code{block-close}@footnote{@code{block-open} is used only for
4609 ``free-standing'' blocks, and is somewhat rare (@pxref{Literal
4610 Symbols} for an example.)}. Line 13 is treated the same way.
4612 @ssindex substatement
4613 Lines 6 and 9 are also substatements of conditionals, but since they
4614 don't start blocks they are given @code{substatement} syntax
4615 instead of @code{substatement-open}.
4617 @ssindex substatement-label
4618 Line 8 contains a label, which is normally given @code{label} syntax.
4619 This one is however a bit special since it's between a conditional and
4620 its substatement. It's analyzed as @code{substatement-label} to let you
4621 handle this rather odd case differently from normal labels.
4623 @ssindex else-clause
4624 @ssindex catch-clause
4625 Line 7 start with an @code{else} that matches the @code{if} statement on
4626 line 5. It is therefore given the @code{else-clause} syntax and is
4627 anchored on the matching @code{if}. The @code{try}-@code{catch}
4628 constructs in C++ and Java are treated this way too, except that
4629 @code{catch} and (in Java) @code{finally}, are marked with
4630 @code{catch-clause}.
4632 @ssindex do-while-closure
4633 The @code{while} construct on line 14 that closes a @code{do}
4634 conditional is given the special syntax @code{do-while-closure} if it
4635 appears on a line by itself. Note that if the @code{while} appeared on
4636 the same line as the preceding close brace, that line would still have
4637 @code{block-close} syntax.
4639 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4640 @node Switch Statement Symbols, Brace List Symbols, Conditional Construct Symbols, Syntactic Symbols
4641 @comment node-name, next, previous, up
4642 @subsection Switch Statement Symbols
4643 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4645 Switch statements have their own set of syntactic symbols. Here's an
4649 1: void spam( enum Ingredient i )
4656 8: drink_some_water();
4668 @ssindex statement-case-intro
4669 @ssindex statement-case-open
4670 Here, lines 4, 7, and 10 are all assigned @code{case-label} syntax,
4671 while lines 5 and 8 are assigned @code{statement-case-intro}. Line 11
4672 is treated slightly differently since it contains a brace that opens a
4673 block; it is given @code{statement-case-open} syntax.
4675 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4676 @node Brace List Symbols, External Scope Symbols, Switch Statement Symbols, Syntactic Symbols
4677 @comment node-name, next, previous, up
4678 @subsection Brace List Symbols
4679 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4682 There are a set of syntactic symbols that are used to recognize
4683 constructs inside of brace lists. A brace list is defined as an
4684 @code{enum} or aggregate initializer list, such as might statically
4685 initialize an array of structs. The three special aggregate constructs
4686 in Pike, @code{(@{ @})}, @code{([ ])} and @code{(< >)}, are treated as
4687 brace lists too. An example:
4690 1: static char* ingredients[] =
4698 @ssindex brace-list-open
4699 @ssindex brace-list-intro
4700 @ssindex brace-list-close
4701 @ssindex brace-list-entry
4702 Following convention, line 2 in this example is assigned
4703 @code{brace-list-open} syntax, and line 3 is assigned
4704 @code{brace-list-intro} syntax. Likewise, line 6 is assigned
4705 @code{brace-list-close} syntax. Lines 4 and 5 however, are assigned
4706 @code{brace-list-entry} syntax, as would all subsequent lines in this
4709 @ssindex brace-entry-open
4710 Your static initializer might be initializing nested structures, for
4714 1: struct intpairs[] =
4727 Here, you've already seen the analysis of lines 1, 2, 3, and 11. On
4728 line 4, things get interesting; this line is assigned
4729 @code{brace-entry-open} syntactic symbol because it's a bracelist
4730 entry line that starts with an open brace. Lines 5 and 6 are pretty
4731 standard, and line 7 is a @code{brace-list-close} as you'd expect.
4732 Once again, line 8 is assigned as @code{brace-entry-open} as is line
4733 10. Line 9 is assigned two syntactic elements, @code{brace-list-intro}
4734 with anchor point at the @samp{@{} of line 8@footnote{This extra
4735 syntactic element was introduced in @ccmode{} 5.33.1 to allow extra
4736 flexibility in indenting the second line of such a construct. You can
4737 preserve the behavior resulting from the former syntactic analysis by
4738 giving @code{brace-list-entry} an offset of
4739 @code{c-lineup-under-anchor} (@pxref{Misc Line-Up}).}, and
4740 @code{brace-list-entry} anchored on the @samp{1} of line 8.
4742 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4743 @node External Scope Symbols, Paren List Symbols, Brace List Symbols, Syntactic Symbols
4744 @comment node-name, next, previous, up
4745 @subsection External Scope Symbols
4746 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4748 External language definition blocks also have their own syntactic
4749 symbols. In this example:
4754 3: int thing_one( int );
4755 4: int thing_two( double );
4759 @ssindex extern-lang-open
4760 @ssindex extern-lang-close
4761 @ssindex inextern-lang
4764 line 2 is given the @code{extern-lang-open} syntax, while line 5 is given
4765 the @code{extern-lang-close} syntax. The analysis for line 3 yields:
4768 ((inextern-lang) (topmost-intro 14))
4772 where @code{inextern-lang} is a modifier similar in purpose to
4775 There are various other top level blocks like @code{extern}, and they
4776 are all treated in the same way except that the symbols are named after
4777 the keyword that introduces the block. E.g., C++ namespace blocks get
4778 the three symbols @code{namespace-open}, @code{namespace-close} and
4779 @code{innamespace}. The currently recognized top level blocks are:
4782 @item @code{extern-lang-open}, @code{extern-lang-close}, @code{inextern-lang}
4783 @code{extern} blocks in C and C++.@footnote{These should logically be
4784 named @code{extern-open}, @code{extern-close} and @code{inextern}, but
4785 that isn't the case for historical reasons.}
4787 @item @code{namespace-open}, @code{namespace-close}, @code{innamespace}
4788 @ssindex namespace-open
4789 @ssindex namespace-close
4790 @ssindex innamespace
4791 @code{namespace} blocks in C++.
4793 @item @code{module-open}, @code{module-close}, @code{inmodule}
4794 @ssindex module-open
4795 @ssindex module-close
4797 @code{module} blocks in CORBA IDL.
4799 @item @code{composition-open}, @code{composition-close}, @code{incomposition}
4800 @ssindex composition-open
4801 @ssindex composition-close
4802 @ssindex incomposition
4803 @code{composition} blocks in CORBA CIDL.
4806 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4807 @node Paren List Symbols, Literal Symbols, External Scope Symbols, Syntactic Symbols
4808 @comment node-name, next, previous, up
4809 @subsection Parenthesis (Argument) List Symbols
4810 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4812 A number of syntactic symbols are associated with parenthesis lists,
4813 a.k.a argument lists, as found in function declarations and function
4814 calls. This example illustrates these:
4817 1: void a_function( int line1,
4820 4: void a_longer_function(
4825 9: void call_them( int line1, int line2 )
4832 16: a_longer_function( line1,
4837 @ssindex arglist-intro
4838 @ssindex arglist-close
4839 Lines 5 and 12 are assigned @code{arglist-intro} syntax since they are
4840 the first line following the open parenthesis, and lines 7 and 14 are
4841 assigned @code{arglist-close} syntax since they contain the parenthesis
4842 that closes the argument list.
4844 @ssindex arglist-cont-nonempty
4845 @ssindex arglist-cont
4846 Lines that continue argument lists can be assigned one of two syntactic
4847 symbols. For example, Lines 2 and 17
4848 are assigned @code{arglist-cont-nonempty} syntax. What this means
4849 is that they continue an argument list, but that the line containing the
4850 parenthesis that opens the list is @emph{not empty} following the open
4851 parenthesis. Contrast this against lines 6 and 13 which are assigned
4852 @code{arglist-cont} syntax. This is because the parenthesis that opens
4853 their argument lists is the last character on that line.
4855 Syntactic elements with @code{arglist-intro},
4856 @code{arglist-cont-nonempty}, and @code{arglist-close} contain two
4857 buffer positions: the anchor position (the beginning of the
4858 declaration or statement) and the position of the open parenthesis.
4859 The latter position can be used in a line-up function (@pxref{Line-Up
4862 Note that there is no @code{arglist-open} syntax. This is because any
4863 parenthesis that opens an argument list, appearing on a separate line,
4864 is assigned the @code{statement-cont} syntax instead.
4866 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4867 @node Literal Symbols, Multiline Macro Symbols, Paren List Symbols, Syntactic Symbols
4868 @comment node-name, next, previous, up
4869 @subsection Comment String Label and Macro Symbols
4870 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4872 A few miscellaneous syntactic symbols that haven't been previously
4873 covered are illustrated by this C++ example:
4876 1: void Bass::play( int volume )
4879 4: /* this line starts a multiline
4880 5: * comment. This line should get 'c' syntax */
4882 7: char* a_multiline_string = "This line starts a multiline \
4883 8: string. This line should get 'string' syntax.";
4891 16: cout << "I played "
4897 The lines to note in this example include:
4901 @ssindex func-decl-cont
4902 Line 2 is assigned the @code{func-decl-cont} syntax.
4905 @ssindex comment-intro
4906 Line 4 is assigned both @code{defun-block-intro} @emph{and}
4907 @code{comment-intro} syntax. A syntactic element with
4908 @code{comment-intro} has no anchor point. It is always accompanied
4909 by another syntactic element which does have one.
4913 Line 5 is assigned @code{c} syntax.
4916 @cindex syntactic whitespace
4917 Line 6 which, even though it contains nothing but whitespace, is
4918 assigned @code{defun-block-intro}. Note that the appearance of the
4919 comment on lines 4 and 5 do not cause line 6 to be assigned
4920 @code{statement} syntax because comments are considered to be
4921 @dfn{syntactic whitespace}, which are ignored when analyzing
4926 Line 8 is assigned @code{string} syntax.
4930 Line 10 is assigned @code{label} syntax.
4934 Line 11 is assigned @code{block-open} as well as @code{statement}
4935 syntax. A @code{block-open} syntactic element doesn't have an anchor
4936 position, since it always appears with another syntactic element which
4941 Lines 12 and 14 are assigned @code{cpp-macro} syntax in addition to the
4942 normal syntactic symbols (@code{statement-block-intro} and
4943 @code{statement}, respectively). Normally @code{cpp-macro} is
4944 configured to cancel out the normal syntactic context to make all
4945 preprocessor directives stick to the first column, but that's easily
4946 changed if you want preprocessor directives to be indented like the rest
4947 of the code. Like @code{comment-intro}, a syntactic element with
4948 @code{cpp-macro} doesn't contain an anchor position.
4952 Line 17 is assigned @code{stream-op} syntax.
4955 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4956 @node Multiline Macro Symbols, Objective-C Method Symbols, Literal Symbols, Syntactic Symbols
4957 @comment node-name, next, previous, up
4958 @subsection Multiline Macro Symbols
4959 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4961 @cindex multiline macros
4962 @cindex syntactic whitespace
4963 @ssindex cpp-define-intro
4964 @ssindex cpp-macro-cont
4965 Multiline preprocessor macro definitions are normally handled just like
4966 other code, i.e., the lines inside them are indented according to the
4967 syntactic analysis of the preceding lines inside the macro. The first
4968 line inside a macro definition (i.e., the line after the starting line of
4969 the cpp directive itself) gets @code{cpp-define-intro}. In this example:
4972 1: #define LIST_LOOP(cons, listp) \
4973 2: for (cons = listp; !NILP (cons); cons = XCDR (cons)) \
4974 3: if (!CONSP (cons)) \
4975 4: signal_error ("Invalid list format", listp); \
4980 line 1 is given the syntactic symbol @code{cpp-macro}. The first line
4981 of a cpp directive is always given that symbol. Line 2 is given
4982 @code{cpp-define-intro}, so that you can give the macro body as a whole
4983 some extra indentation. Lines 3 through 5 are then analyzed as normal
4984 code, i.e., @code{substatement} on lines 3 and 4, and @code{else-clause}
4987 The syntactic analysis inside macros can be turned off with
4988 @code{c-syntactic-indentation-in-macros} (@pxref{Custom Macros}). In
4989 that case, lines 2 through 5 would all be given @code{cpp-macro-cont}
4990 with an anchor position pointing to the @code{#} which starts the cpp
4991 directive@footnote{This is how @ccmode{} 5.28 and earlier analyzed
4994 @xref{Custom Macros}, for more info about the treatment of macros.
4996 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4997 @node Objective-C Method Symbols, Java Symbols, Multiline Macro Symbols, Syntactic Symbols
4998 @comment node-name, next, previous, up
4999 @subsection Objective-C Method Symbols
5000 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5002 In Objective-C buffers, there are three additional syntactic symbols
5003 assigned to various message calling constructs. Here's an example
5007 1: - (void)setDelegate:anObject
5010 4: [delegate masterWillRebind:self
5011 5: toDelegate:anObject
5012 6: withExtraStuff:stuff];
5016 @ssindex objc-method-intro
5017 @ssindex objc-method-args-cont
5018 @ssindex objc-method-call-cont
5019 Here, line 1 is assigned @code{objc-method-intro} syntax, and line 2 is
5020 assigned @code{objc-method-args-cont} syntax. Lines 5 and 6 are both
5021 assigned @code{objc-method-call-cont} syntax.
5023 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5024 @node Java Symbols, Statement Block Symbols, Objective-C Method Symbols, Syntactic Symbols
5025 @comment node-name, next, previous, up
5026 @subsection Java Symbols
5027 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5029 Java has a concept of anonymous classes which can look something like
5034 2: public void watch(Observable o) @{
5036 4: Observer obs = new Observer() @{
5037 5: public void update(Observable o, Object arg) @{
5038 6: history.addElement(arg);
5041 9: o.addObserver(obs);
5045 @ssindex inexpr-class
5046 The brace following the @code{new} operator opens the anonymous class.
5047 Lines 5 and 8 are assigned the @code{inexpr-class} syntax, besides the
5048 @code{inclass} symbol used in normal classes. Thus, the class will be
5049 indented just like a normal class, with the added indentation given to
5050 @code{inexpr-class}. An @code{inexpr-class} syntactic element doesn't
5051 have an anchor position.
5053 @ssindex annotation-top-cont
5054 @ssindex annotation-var-cont
5055 Line 2 is assigned the @code{annotation-top-cont} syntax, due to it being a
5056 continuation of a topmost introduction with an annotation symbol preceding
5057 the current line. Similarly, line 4 is assigned the @code{annotation-var-cont}
5058 syntax due to it being a continuation of a variable declaration where preceding
5059 the declaration is an annotation.
5061 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5062 @node Statement Block Symbols, K&R Symbols, Java Symbols, Syntactic Symbols
5063 @comment node-name, next, previous, up
5064 @subsection Statement Block Symbols
5065 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5067 There are a few occasions where a statement block might be used inside
5068 an expression. One is in C or C++ code using the gcc extension for
5073 2: int y = foo (); int z;
5074 3: if (y > 0) z = y; else z = - y;
5079 @ssindex inexpr-statement
5080 Lines 2 and 5 get the @code{inexpr-statement} syntax, besides the
5081 symbols they'd get in a normal block. Therefore, the indentation put on
5082 @code{inexpr-statement} is added to the normal statement block
5083 indentation. An @code{inexpr-statement} syntactic element doesn't
5084 contain an anchor position.
5086 C++11's lambda expressions involve a block inside a statement. For
5090 1: std::for_each(someList.begin(), someList.end(), [&total](int x) @{
5095 Here a lambda expressions begins at the open bracket on line 1 and
5096 ends at the closing brace on line 3. Line 2, in addition to the
5097 familiar @code{defun-block-intro} syntactic element, is also prefixed
5098 by an @code{inlambda} element, which is typically used to indent the
5099 entire lambda expression to under the opening bracket.
5101 In Pike code, there are a few other situations where blocks occur inside
5102 statements, as illustrated here:
5107 3: string s = map (backtrace()[-2][3..],
5111 7: return sprintf ("%t", arg);
5112 8: @}) * ", " + "\n";
5114 10: write (s + "\n");
5120 @ssindex lambda-intro-cont
5121 Lines 4 through 8 contain a lambda function, which @ccmode{} recognizes
5122 by the @code{lambda} keyword. If the function argument list is put
5123 on a line of its own, as in line 5, it gets the @code{lambda-intro-cont}
5124 syntax. The function body is handled as an inline method body, with the
5125 addition of the @code{inlambda} syntactic symbol. This means that line
5126 6 gets @code{inlambda} and @code{inline-open}, and line 8 gets
5127 @code{inline-close}@footnote{You might wonder why it doesn't get
5128 @code{inlambda} too. It's because the closing brace is relative to the
5129 opening brace, which stands on its own line in this example. If the
5130 opening brace was hanging on the previous line, then the closing brace
5131 would get the @code{inlambda} syntax too to be indented correctly.}.
5133 @ssindex inexpr-statement
5134 On line 9, @code{catch} is a special function taking a statement block
5135 as its argument. The block is handled as an in-expression statement
5136 with the @code{inexpr-statement} syntax, just like the gcc extended C
5137 example above. The other similar special function, @code{gauge}, is
5138 handled like this too.
5140 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5141 @node K&R Symbols, , Statement Block Symbols, Syntactic Symbols
5142 @comment node-name, next, previous, up
5143 @subsection K&R Symbols
5144 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5146 @ssindex knr-argdecl-intro
5147 @ssindex knr-argdecl
5148 Two other syntactic symbols can appear in old style, non-prototyped C
5149 code @footnote{a.k.a.@: K&R C, or Kernighan & Ritchie C}:
5152 1: int add_three_integers(a, b, c)
5157 6: return a + b + c;
5161 Here, line 2 is the first line in an argument declaration list and so is
5162 given the @code{knr-argdecl-intro} syntactic symbol. Subsequent lines
5163 (i.e., lines 3 and 4 in this example), are given @code{knr-argdecl}
5167 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5168 @node Indentation Calculation, , Syntactic Symbols, Indentation Engine Basics
5169 @comment node-name, next, previous, up
5170 @section Indentation Calculation
5172 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5174 Indentation for a line is calculated from the syntactic context
5175 (@pxref{Syntactic Analysis}).
5177 First, a buffer position is found whose column will be the base for the
5178 indentation calculation. It's the anchor position in the first
5179 syntactic element that provides one that is used. If no syntactic
5180 element has an anchor position then column zero is used.
5182 Second, the syntactic symbols in each syntactic element are looked up
5183 in the @code{c-offsets-alist} style variable
5184 (@pxref{c-offsets-alist}), which is an association list of syntactic
5185 symbols and the offsets to apply for those symbols. These offsets are
5186 added together with the base column to produce the new indentation
5189 Let's use our two code examples above to see how this works. Here is
5190 our first example again:
5193 1: void swap( int& a, int& b )
5201 Let's say point is on line 3 and we hit the @key{TAB} key to reindent
5202 the line. The syntactic context for that line is:
5205 ((defun-block-intro 29))
5209 Since buffer position 29 is the first and only anchor position in the
5210 list, @ccmode{} goes there and asks for the current column. This brace
5211 is in column zero, so @ccmode{} uses @samp{0} as the base column.
5213 Next, @ccmode{} looks up @code{defun-block-intro} in the
5214 @code{c-offsets-alist} style variable. Let's say it finds the value
5215 @samp{4}; it adds this to the base column @samp{0}, yielding a running
5216 total indentation of 4 spaces.
5218 Since there is only one syntactic element on the list for this line,
5219 indentation calculation is complete, and the total indentation for the
5222 Here's another example:
5225 1: int add( int val, int incr, int doit )
5229 5: return( val + incr );
5235 If we were to hit @kbd{TAB} on line 4 in the above example, the same
5236 basic process is performed, despite the differences in the syntactic
5237 context. The context for this line is:
5240 ((substatement-open 46))
5243 Here, @ccmode{} goes to buffer position 46, which is the @samp{i} in
5244 @code{if} on line 3. This character is in the fourth column on that
5245 line so the base column is @samp{4}. Then @ccmode{} looks up the
5246 @code{substatement-open} symbol in @code{c-offsets-alist}. Let's say it
5247 finds the value @samp{4}. It's added with the base column and yields an
5248 indentation for the line of 8 spaces.
5252 Actually, it's a bit more complicated than that since the entries on
5253 @code{c-offsets-alist} can be much more than plain offsets.
5254 @xref{c-offsets-alist}, for the full story.
5256 Anyway, the mode usually just does The Right Thing without you having to
5257 think about it in this much detail. But when customizing indentation,
5258 it's helpful to understand the general indentation model being used.
5260 As you configure @ccmode{}, you might want to set the variable
5261 @code{c-echo-syntactic-information-p} to non-@code{nil} so that the
5262 syntactic context and calculated offset always is echoed in the
5263 minibuffer when you hit @kbd{TAB}.
5266 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5267 @node Customizing Indentation, Custom Macros, Indentation Engine Basics, Top
5268 @comment node-name, next, previous, up
5269 @chapter Customizing Indentation
5270 @cindex customization, indentation
5272 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5274 The principal variable for customizing indentation is the style
5275 variable @code{c-offsets-alist}, which gives an @dfn{offset} (an
5276 indentation rule) for each syntactic symbol. Its structure and
5277 semantics are completely described in @ref{c-offsets-alist}. The
5278 various ways you can set the variable, including the use of the
5279 @ccmode{} style system, are described in @ref{Config Basics} and its
5280 sections, in particular @ref{Style Variables}.
5282 The simplest and most used kind of ``offset'' setting in
5283 @code{c-offsets-alist} is in terms of multiples of
5284 @code{c-basic-offset}:
5286 @defopt c-basic-offset
5287 @vindex basic-offset @r{(c-)}
5288 This style variable holds the basic offset between indentation levels.
5289 It's factory default is 4, but all the built-in styles set it
5290 themselves, to some value between 2 (for @code{gnu} style) and 8 (for
5291 @code{bsd}, @code{linux}, and @code{python} styles).
5294 The most flexible ``offset'' setting you can make in
5295 @code{c-offsets-alist} is a line-up function (or even a list of them),
5296 either one supplied by @ccmode{} (@pxref{Line-Up Functions}) or one
5297 you write yourself (@pxref{Custom Line-Up}).
5299 Finally, in @ref{Other Indentation} you'll find the tool of last
5300 resort: a hook which is called after a line has been indented. You
5301 can install functions here to make ad-hoc adjustments to any line's
5306 * Interactive Customization::
5307 * Line-Up Functions::
5309 * Other Indentation::
5313 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5314 @node c-offsets-alist, Interactive Customization, Customizing Indentation, Customizing Indentation
5315 @comment node-name, next, previous, up
5316 @section c-offsets-alist
5317 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5319 This section explains the structure and semantics of the style
5320 variable @code{c-offsets-alist}, the principal variable for configuring
5321 indentation. Details of how to set it up, and its relationship to
5322 @ccmode{}'s style system are given in @ref{Style Variables}.
5324 @defopt c-offsets-alist
5325 @vindex offsets-alist @r{(c-)}
5326 This is an alist which associates an offset with each syntactic
5327 symbol. This @dfn{offset} is a rule specifying how to indent a line
5328 whose syntactic context matches the symbol. @xref{Syntactic
5331 Note that the buffer-local binding of this alist in a @ccmode{} buffer
5332 contains an entry for @emph{every} syntactic symbol. Its global
5333 binding and its settings within style specifications usually contain
5334 only a few entries. @xref{Style Variables}.
5336 The offset specification associated with any particular syntactic
5337 symbol can be an integer, a variable name, a vector, a function or
5338 lambda expression, a list, or one of the following special symbols:
5339 @code{+}, @code{-}, @code{++}, @code{--}, @code{*}, or @code{/}. The
5340 meanings of these values are described in detail below.
5342 Here is an example fragment of a @code{c-offsets-alist}, showing some
5343 of these kinds of offsets:
5349 (topmost-intro-cont . c-lineup-topmost-intro-cont)
5350 (statement-block-intro . (add c-lineup-whitesmith-in-block
5351 c-indent-multi-line-block))
5357 @deffn Command c-set-offset (@kbd{C-c C-o})
5358 @findex set-offset @r{(c-)}
5360 This command changes the entry for a syntactic symbol in the current
5361 binding of @code{c-offsets-alist}, or it inserts a new entry if there
5362 isn't already one for that syntactic symbol.
5364 You can use @code{c-set-offset} interactively within a @ccmode{}
5365 buffer to make experimental changes to your indentation settings.
5366 @kbd{C-c C-o} prompts you for the syntactic symbol to change
5367 (defaulting to that of the current line) and the new offset
5368 (defaulting to the current offset).
5370 @code{c-set-offset} takes two arguments when used programmatically:
5371 @var{symbol}, the syntactic element symbol to change and @var{offset},
5372 the new offset for that syntactic element. You can call the command
5373 in your @file{.emacs} to change the global binding of
5374 @code{c-offsets-alist} (@pxref{Style Variables}); you can use it in a
5375 hook function to make changes from the current style. @ccmode{}
5376 itself uses this function when initializing styles.
5379 @cindex offset specification
5380 The ``offset specifications'' in @code{c-offsets-alist} can be any of
5385 The integer specifies a relative offset. All relative
5386 offsets@footnote{The syntactic context @code{@w{((defun-block-intro
5387 2724) (comment-intro))}} would likely have two relative offsets.} will
5388 be added together and used to calculate the indentation relative to an
5389 anchor position earlier in the buffer. @xref{Indentation
5390 Calculation}, for details. Most of the time, it's probably better to
5391 use one of the special symbols like @code{+} than an integer (apart
5394 @item One of the symbols @code{+}, @code{-}, @code{++}, @code{--}, @code{*}, or @code{/}
5395 These special symbols describe a relative offset in multiples of
5396 @code{c-basic-offset}:
5398 By defining a style's indentation in terms of @code{c-basic-offset},
5399 you can change the amount of whitespace given to an indentation level
5400 while maintaining the same basic shape of your code. Here are the
5401 values that the special symbols correspond to:
5405 @code{c-basic-offset} times 1
5407 @code{c-basic-offset} times @minus{}1
5409 @code{c-basic-offset} times 2
5411 @code{c-basic-offset} times @minus{}2
5413 @code{c-basic-offset} times 0.5
5415 @code{c-basic-offset} times @minus{}0.5
5419 The first element of the vector, an integer, sets the absolute
5420 indentation column. This will override any previously calculated
5421 indentation, but won't override relative indentation calculated from
5422 syntactic elements later on in the syntactic context of the line being
5423 indented. @xref{Indentation Calculation}. Any elements in the vector
5424 beyond the first will be ignored.
5426 @item A function or lambda expression
5427 The function will be called and its return value will in turn be
5428 evaluated as an offset specification. Functions are useful when more
5429 context than just the syntactic symbol is needed to get the desired
5430 indentation. @xref{Line-Up Functions}, and @ref{Custom Line-Up}, for
5433 @item A symbol with a variable binding
5434 If the symbol also has a function binding, the function takes
5435 precedence over the variable. Otherwise the value of the variable is
5436 used. It must be an integer (which is used as relative offset) or a
5437 vector (an absolute offset).
5440 The offset can also be a list containing several offset
5441 specifications; these are evaluated recursively and combined. A list
5442 is typically only useful when some of the offsets are line-up
5443 functions. A common strategy is calling a sequence of functions in
5444 turn until one of them recognizes that it is appropriate for the
5445 source line and returns a non-@code{nil} value.
5447 @code{nil} values are always ignored when the offsets are combined.
5448 The first element of the list specifies the method of combining the
5449 non-@code{nil} offsets from the remaining elements:
5453 Use the first offset that doesn't evaluate to @code{nil}. Subsequent
5454 elements of the list don't get evaluated.
5456 Use the minimum of all the offsets. All must be either relative or
5457 absolute; they can't be mixed.
5459 Use the maximum of all the offsets. All must be either relative or
5460 absolute; they can't be mixed.
5462 Add all the evaluated offsets together. Exactly one of them may be
5463 absolute, in which case the result is absolute. Any relative offsets
5464 that preceded the absolute one in the list will be ignored in that case.
5467 As a compatibility measure, if the first element is none of the above
5468 then it too will be taken as an offset specification and the whole list
5469 will be combined according to the method @code{first}.
5472 @vindex c-strict-syntax-p
5473 @vindex strict-syntax-p @r{(c-)}
5474 If an offset specification evaluates to @code{nil}, then a relative
5475 offset of 0 (zero) is used@footnote{There is however a variable
5476 @code{c-strict-syntax-p} that when set to non-@code{nil} will cause an
5477 error to be signaled in that case. It's now considered obsolete since
5478 it doesn't work well with some of the alignment functions that return
5479 @code{nil} instead of zero. You should therefore leave
5480 @code{c-strict-syntax-p} set to @code{nil}.}.
5482 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5483 @node Interactive Customization, Line-Up Functions, c-offsets-alist, Customizing Indentation
5484 @comment node-name, next, previous, up
5485 @section Interactive Customization
5486 @cindex customization, interactive
5487 @cindex interactive customization
5488 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5490 As an example of how to customize indentation, let's change the
5491 style of this example@footnote{In this and subsequent examples, the
5492 original code is formatted using the @samp{gnu} style unless otherwise
5493 indicated. @xref{Styles}.}:
5497 1: int add( int val, int incr, int doit )
5501 5: return( val + incr );
5513 1: int add( int val, int incr, int doit )
5517 5: return( val + incr );
5524 In other words, we want to change the indentation of braces that open a
5525 block following a condition so that the braces line up under the
5526 conditional, instead of being indented. Notice that the construct we
5527 want to change starts on line 4. To change the indentation of a line,
5528 we need to see which syntactic symbols affect the offset calculations
5529 for that line. Hitting @kbd{C-c C-s} on line 4 yields:
5532 ((substatement-open 44))
5536 so we know that to change the offset of the open brace, we need to
5537 change the indentation for the @code{substatement-open} syntactic
5540 To do this interactively, just hit @kbd{C-c C-o}. This prompts
5541 you for the syntactic symbol to change, providing a reasonable default.
5542 In this case, the default is @code{substatement-open}, which is just the
5543 syntactic symbol we want to change!
5545 After you hit return, @ccmode{} will then prompt you for the new
5546 offset value, with the old value as the default. The default in this
5547 case is @samp{+}, but we want no extra indentation so enter
5548 @samp{0} and @kbd{RET}. This will associate the offset 0 with the
5549 syntactic symbol @code{substatement-open}.
5551 To check your changes quickly, just hit @kbd{C-c C-q}
5552 (@code{c-indent-defun}) to reindent the entire function. The example
5553 should now look like:
5557 1: int add( int val, int incr, int doit )
5561 5: return( val + incr );
5568 Notice how just changing the open brace offset on line 4 is all we
5569 needed to do. Since the other affected lines are indented relative to
5570 line 4, they are automatically indented the way you'd expect. For more
5571 complicated examples, this might not always work. The general approach
5572 to take is to always start adjusting offsets for lines higher up in the
5573 file, then reindent and see if any following lines need further
5576 @c Move this bit to "Styles" (2005/10/7)
5577 @deffn Command c-set-offset symbol offset
5578 @findex set-offset @r{(c-)}
5580 This is the command bound to @kbd{C-c C-o}. It provides a convenient
5581 way to set offsets on @code{c-offsets-alist} both interactively (see
5582 the example above) and from your mode hook.
5584 It takes two arguments when used programmatically: @var{symbol} is the
5585 syntactic element symbol to change and @var{offset} is the new offset
5586 for that syntactic element.
5588 @c End of MOVE THIS BIT.
5590 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5591 @node Line-Up Functions, Custom Line-Up, Interactive Customization, Customizing Indentation
5592 @comment node-name, next, previous, up
5593 @section Line-Up Functions
5594 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5596 @cindex line-up function
5597 @cindex indentation function
5598 Often there are cases when a simple offset setting on a syntactic
5599 symbol isn't enough to get the desired indentation---for example, you
5600 might want to line up a closing parenthesis with the matching opening
5601 one rather than indenting relative to its ``anchor point''. @ccmode{}
5602 provides this flexibility with @dfn{line-up functions}.
5604 The way you associate a line-up function with a syntactic symbol is
5605 described in @ref{c-offsets-alist}. @ccmode{} comes with many
5606 predefined line-up functions for common situations. If none of these
5607 does what you want, you can write your own. @xref{Custom Line-Up}.
5608 Sometimes, it is easier to tweak the standard indentation by adding a
5609 function to @code{c-special-indent-hook} (@pxref{Other Indentation}).
5611 The line-up functions haven't been adapted for AWK buffers or tested
5612 with them. Some of them might work serendipitously. There shouldn't be
5613 any problems writing custom line-up functions for AWK mode.
5615 The calling convention for line-up functions is described fully in
5616 @ref{Custom Line-Up}. Roughly speaking, the return value is either an
5617 offset itself (such as @code{+} or @code{[0]}) or it's @code{nil},
5618 meaning ``this function is inappropriate in this case; try a
5619 different one''. @xref{c-offsets-alist}.
5621 The subsections below describe all the standard line-up functions,
5622 categorized by the sort of token the lining-up centers around. For
5623 each of these functions there is a ``works with'' list that indicates
5624 which syntactic symbols the function is intended to be used with.
5627 @emph{Works with:@ }
5636 @macro sssTBasicOffset
5637 <--> @i{c-basic-offset}
5640 @macro sssTsssTBasicOffset
5641 <--><--> @i{c-basic-offset}
5648 @c The TeX backend seems to insert extra spaces around the argument. :P
5657 * Brace/Paren Line-Up::
5659 * Operator Line-Up::
5664 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5665 @node Brace/Paren Line-Up, List Line-Up, Line-Up Functions, Line-Up Functions
5666 @comment node-name, next, previous, up
5667 @subsection Brace and Parenthesis Line-Up Functions
5668 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5670 The line-up functions here calculate the indentation for braces,
5671 parentheses and statements within brace blocks.
5673 @defun c-lineup-close-paren
5674 @findex lineup-close-paren @r{(c-)}
5675 Line up the closing paren under its corresponding open paren if the
5676 open paren is followed by code. If the open paren ends its line, no
5677 indentation is added. E.g.:
5683 ) @hereFn{c-lineup-close-paren}
5694 ) @hereFn{c-lineup-close-paren}
5698 As a special case, if a brace block is opened at the same line as the
5699 open parenthesis of the argument list, the indentation is
5700 @code{c-basic-offset} instead of the open paren column. See
5701 @code{c-lineup-arglist} for further discussion of this ``DWIM'' measure.
5703 @workswith All @code{*-close} symbols.
5706 @comment ------------------------------------------------------------
5708 @anchor{c-lineup-arglist-close-under-paren}
5709 @defun c-lineup-arglist-close-under-paren
5710 @findex lineup-arglist-close-under-paren @r{(c-)}
5711 Set your @code{arglist-close} syntactic symbol to this line-up function
5712 so that parentheses that close argument lists will line up under the
5713 parenthesis that opened the argument list. It can also be used with
5714 @code{arglist-cont} and @code{arglist-cont-nonempty} to line up all
5715 lines inside a parenthesis under the open paren.
5717 As a special case, if a brace block is opened at the same line as the
5718 open parenthesis of the argument list, the indentation is
5719 @code{c-basic-offset} only. See @code{c-lineup-arglist} for further
5720 discussion of this ``DWIM'' measure.
5722 @workswith Almost all symbols, but are typically most useful on
5723 @code{arglist-close}, @code{brace-list-close}, @code{arglist-cont} and
5724 @code{arglist-cont-nonempty}.
5727 @comment ------------------------------------------------------------
5729 @defun c-indent-one-line-block
5730 @findex indent-one-line-block @r{(c-)}
5731 Indent a one line block @code{c-basic-offset} extra. E.g.:
5736 @{m+=n; n=0;@} @hereFn{c-indent-one-line-block}
5747 @{ @hereFn{c-indent-one-line-block}
5753 The block may be surrounded by any kind of parenthesis characters.
5754 @code{nil} is returned if the line doesn't start with a one line block,
5755 which makes the function usable in list expressions.
5757 @workswith Almost all syntactic symbols, but most useful on the
5758 @code{-open} symbols.
5761 @comment ------------------------------------------------------------
5763 @defun c-indent-multi-line-block
5764 @findex indent-multi-line-block @r{(c-)}
5765 Indent a multiline block @code{c-basic-offset} extra. E.g.:
5771 @{17@}, @hereFn{c-indent-multi-line-block}
5782 @{ @hereFn{c-indent-multi-line-block}
5789 The block may be surrounded by any kind of parenthesis characters.
5790 @code{nil} is returned if the line doesn't start with a multiline
5791 block, which makes the function usable in list expressions.
5793 @workswith Almost all syntactic symbols, but most useful on the
5794 @code{-open} symbols.
5797 @comment ------------------------------------------------------------
5799 @defun c-lineup-runin-statements
5800 @findex lineup-runin-statements @r{(c-)}
5801 Line up statements for coding standards which place the first statement
5802 in a block on the same line as the block opening brace@footnote{Run-in
5803 style doesn't really work too well. You might need to write your own
5804 custom line-up functions to better support this style.}. E.g.:
5810 return 0; @hereFn{c-lineup-runin-statements}
5815 If there is no statement after the opening brace to align with,
5816 @code{nil} is returned. This makes the function usable in list
5819 @workswith The @code{statement} syntactic symbol.
5822 @comment ------------------------------------------------------------
5824 @defun c-lineup-inexpr-block
5825 @findex lineup-inexpr-block @r{(c-)}
5826 This can be used with the in-expression block symbols to indent the
5827 whole block to the column where the construct is started. E.g., for Java
5828 anonymous classes, this lines up the class under the @samp{new} keyword,
5829 and in Pike it lines up the lambda function body under the @samp{lambda}
5830 keyword. Returns @code{nil} if the block isn't part of such a
5833 @workswith @code{inlambda}, @code{inexpr-statement},
5834 @code{inexpr-class}.
5837 @comment ------------------------------------------------------------
5839 @defun c-lineup-after-whitesmith-blocks
5840 @findex lineup-after-whitesmith-blocks @r{(c-)}
5841 Compensate for Whitesmith style indentation of blocks. Due to the way
5842 @ccmode{} calculates anchor positions for normal lines inside blocks,
5843 this function is necessary for those lines to get correct Whitesmith
5844 style indentation. Consider the following examples:
5851 x; @hereFn{c-lineup-after-whitesmith-blocks}
5862 x; @hereFn{c-lineup-after-whitesmith-blocks}
5866 The fact that the line with @code{x} is preceded by a Whitesmith style
5867 indented block in the latter case and not the first should not affect
5868 its indentation. But since CC Mode in cases like this uses the
5869 indentation of the preceding statement as anchor position, the @code{x}
5870 would in the second case be indented too much if the offset for
5871 @code{statement} was set simply to zero.
5873 This lineup function corrects for this situation by detecting if the
5874 anchor position is at an open paren character. In that case, it instead
5875 indents relative to the surrounding block just like
5876 @code{c-lineup-whitesmith-in-block}.
5878 @workswith @code{brace-list-entry}, @code{brace-entry-open},
5879 @code{statement}, @code{arglist-cont}.
5882 @comment ------------------------------------------------------------
5884 @defun c-lineup-whitesmith-in-block
5885 @findex lineup-whitesmith-in-block @r{(c-)}
5886 Line up lines inside a block in Whitesmith style. It's done in a way
5887 that works both when the opening brace hangs and when it doesn't. E.g.:
5893 foo; @hereFn{c-lineup-whitesmith-in-block}
5904 foo; @hereFn{c-lineup-whitesmith-in-block}
5910 In the first case the indentation is kept unchanged, in the second
5911 @code{c-basic-offset} is added.
5913 @workswith @code{defun-close}, @code{defun-block-intro},
5914 @code{inline-close}, @code{block-close}, @code{brace-list-close},
5915 @code{brace-list-intro}, @code{statement-block-intro},
5916 @code{arglist-intro}, @code{arglist-cont-nonempty},
5917 @code{arglist-close}, and all @code{in*} symbols, e.g., @code{inclass}
5918 and @code{inextern-lang}.
5921 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5922 @node List Line-Up, Operator Line-Up, Brace/Paren Line-Up, Line-Up Functions
5923 @comment node-name, next, previous, up
5924 @subsection List Line-Up Functions
5925 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5927 The line-up functions here calculate the indentation for lines which
5928 form lists of items, usually separated by commas.
5930 The function @ref{c-lineup-arglist-close-under-paren}, which is mainly
5931 for indenting a close parenthesis, is also useful for the lines
5932 contained within parentheses.
5934 @defun c-lineup-arglist
5935 @findex lineup-arglist @r{(c-)}
5936 Line up the current argument line under the first argument.
5938 As a special case, if an argument on the same line as the open
5939 parenthesis starts with a brace block opener, the indentation is
5940 @code{c-basic-offset} only. This is intended as a ``DWIM'' measure in
5941 cases like macros that contain statement blocks, e.g.:
5945 A_VERY_LONG_MACRO_NAME (@{
5946 some (code, with + long, lines * in[it]);
5952 This is motivated partly because it's more in line with how code
5953 blocks are handled, and partly since it approximates the behavior of
5954 earlier CC Mode versions, which due to inaccurate analysis tended to
5955 indent such cases this way.
5957 @workswith @code{arglist-cont-nonempty}, @code{arglist-close}.
5960 @comment ------------------------------------------------------------
5962 @defun c-lineup-arglist-intro-after-paren
5963 @findex lineup-arglist-intro-after-paren @r{(c-)}
5964 Line up a line to just after the open paren of the surrounding paren or
5967 @workswith @code{defun-block-intro}, @code{brace-list-intro},
5968 @code{statement-block-intro}, @code{statement-case-intro},
5969 @code{arglist-intro}.
5972 @comment ------------------------------------------------------------
5974 @defun c-lineup-multi-inher
5975 @findex lineup-multi-inher @r{(c-)}
5976 Line up the classes in C++ multiple inheritance clauses and member
5977 initializers under each other. E.g.:
5981 Foo::Foo (int a, int b):
5983 Bar (b) @hereFn{c-lineup-multi-inher}
5994 public Bar @hereFn{c-lineup-multi-inher}
6003 Foo::Foo (int a, int b)
6005 , Bar (b) @hereFn{c-lineup-multi-inher}
6009 @workswith @code{inher-cont}, @code{member-init-cont}.
6012 @comment ------------------------------------------------------------
6014 @defun c-lineup-java-inher
6015 @findex lineup-java-inher @r{(c-)}
6016 Line up Java implements and extends declarations. If class names
6017 follow on the same line as the @samp{implements}/@samp{extends}
6018 keyword, they are lined up under each other. Otherwise, they are
6019 indented by adding @code{c-basic-offset} to the column of the keyword.
6026 Bar @hereFn{c-lineup-java-inher}
6038 Bar @hereFn{c-lineup-java-inher}
6042 @workswith @code{inher-cont}.
6045 @comment ------------------------------------------------------------
6047 @defun c-lineup-java-throws
6048 @findex lineup-java-throws @r{(c-)}
6049 Line up Java throws declarations. If exception names follow on the
6050 same line as the throws keyword, they are lined up under each other.
6051 Otherwise, they are indented by adding @code{c-basic-offset} to the
6052 column of the @samp{throws} keyword. The @samp{throws} keyword itself
6053 is also indented by @code{c-basic-offset} from the function declaration
6054 start if it doesn't hang. E.g.:
6059 throws @hereFn{c-lineup-java-throws}
6060 Bar @hereFn{c-lineup-java-throws}
6061 @sssTsssTBasicOffset{}
6070 int foo() throws Cyphr,
6071 Bar, @hereFn{c-lineup-java-throws}
6072 Vlod @hereFn{c-lineup-java-throws}
6076 @workswith @code{func-decl-cont}.
6079 @comment ------------------------------------------------------------
6081 @defun c-lineup-template-args
6082 @findex lineup-template-args @r{(c-)}
6083 Line up the arguments of a template argument list under each other, but
6084 only in the case where the first argument is on the same line as the
6087 To allow this function to be used in a list expression, @code{nil} is
6088 returned if there's no template argument on the first line.
6090 @workswith @code{template-args-cont}.
6093 @comment ------------------------------------------------------------
6095 @defun c-lineup-ObjC-method-call
6096 @findex lineup-ObjC-method-call @r{(c-)}
6097 For Objective-C code, line up selector args as Emacs Lisp mode does
6098 with function args: go to the position right after the message receiver,
6099 and if you are at the end of the line, indent the current line
6100 c-basic-offset columns from the opening bracket; otherwise you are
6101 looking at the first character of the first method call argument, so
6102 lineup the current line with it.
6104 @workswith @code{objc-method-call-cont}.
6107 @comment ------------------------------------------------------------
6109 @defun c-lineup-ObjC-method-args
6110 @findex lineup-ObjC-method-args @r{(c-)}
6111 For Objective-C code, line up the colons that separate args. The colon
6112 on the current line is aligned with the one on the first line.
6114 @workswith @code{objc-method-args-cont}.
6117 @comment ------------------------------------------------------------
6119 @defun c-lineup-ObjC-method-args-2
6120 @findex lineup-ObjC-method-args-2 @r{(c-)}
6121 Similar to @code{c-lineup-ObjC-method-args} but lines up the colon on
6122 the current line with the colon on the previous line.
6124 @workswith @code{objc-method-args-cont}.
6127 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6128 @node Operator Line-Up, Comment Line-Up, List Line-Up, Line-Up Functions
6129 @comment node-name, next, previous, up
6130 @subsection Operator Line-Up Functions
6131 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6133 The line-up functions here calculate the indentation for lines which
6134 start with an operator, by lining it up with something on the previous
6137 @defun c-lineup-argcont
6138 @findex lineup-argcont @r{(c-)}
6139 Line up a continued argument. E.g.:
6143 foo (xyz, aaa + bbb + ccc
6144 + ddd + eee + fff); @hereFn{c-lineup-argcont}
6148 Only continuation lines like this are touched, @code{nil} is returned on
6149 lines which are the start of an argument.
6151 Within a gcc @code{asm} block, @code{:} is recognized as an argument
6152 separator, but of course only between operand specifications, not in the
6153 expressions for the operands.
6155 @workswith @code{arglist-cont}, @code{arglist-cont-nonempty}.
6158 @comment ------------------------------------------------------------
6160 @defun c-lineup-arglist-operators
6161 @findex lineup-arglist-operators @r{(c-)}
6162 Line up lines starting with an infix operator under the open paren.
6163 Return @code{nil} on lines that don't start with an operator, to leave
6164 those cases to other line-up functions. Example:
6169 || at_limit (x, @hereFn{c-lineup-arglist-operators}
6170 list) @hereFn{c-lineup-arglist-operators@r{ returns nil}}
6175 Since this function doesn't do anything for lines without an infix
6176 operator you typically want to use it together with some other lineup
6177 settings, e.g., as follows (the @code{arglist-close} setting is just a
6178 suggestion to get a consistent style):
6181 (c-set-offset 'arglist-cont
6182 '(c-lineup-arglist-operators 0))
6183 (c-set-offset 'arglist-cont-nonempty
6184 '(c-lineup-arglist-operators c-lineup-arglist))
6185 (c-set-offset 'arglist-close
6186 '(c-lineup-arglist-close-under-paren))
6189 @workswith @code{arglist-cont}, @code{arglist-cont-nonempty}.
6192 @comment ------------------------------------------------------------
6194 @defun c-lineup-assignments
6195 @findex lineup-assignments @r{(c-)}
6196 Line up the current line after the assignment operator on the first line
6197 in the statement. If there isn't any, return @code{nil} to allow stacking with
6198 other line-up functions. If the current line contains an assignment
6199 operator too, try to align it with the first one.
6201 @workswith @code{topmost-intro-cont}, @code{statement-cont},
6202 @code{arglist-cont}, @code{arglist-cont-nonempty}.
6206 @comment ------------------------------------------------------------
6208 @defun c-lineup-math
6209 @findex lineup-math @r{(c-)}
6210 Like @code{c-lineup-assignments} but indent with @code{c-basic-offset}
6211 if no assignment operator was found on the first line. I.e., this
6212 function is the same as specifying a list @code{(c-lineup-assignments
6213 +)}. It's provided for compatibility with old configurations.
6215 @workswith @code{topmost-intro-cont}, @code{statement-cont},
6216 @code{arglist-cont}, @code{arglist-cont-nonempty}.
6219 @comment ------------------------------------------------------------
6221 @defun c-lineup-cascaded-calls
6222 @findex lineup-cascaded-calls @r{(c-)}
6223 Line up ``cascaded calls'' under each other. If the line begins with
6224 @code{->} or @code{.} and the preceding line ends with one or more
6225 function calls preceded by the same token, then the arrow is lined up
6226 with the first of those tokens. E.g.:
6230 r = proc->add(17)->add(18)
6231 ->add(19) + @hereFn{c-lineup-cascaded-calls}
6232 offset; @hereFn{c-lineup-cascaded-calls@r{ (inactive)}}
6236 In any other situation @code{nil} is returned to allow use in list
6239 @workswith @code{topmost-intro-cont}, @code{statement-cont},
6240 @code{arglist-cont}, @code{arglist-cont-nonempty}.
6243 @comment ------------------------------------------------------------
6245 @defun c-lineup-streamop
6246 @findex lineup-streamop @r{(c-)}
6247 Line up C++ stream operators (i.e., @samp{<<} and @samp{>>}).
6249 @workswith @code{stream-op}.
6252 @comment ------------------------------------------------------------
6254 @defun c-lineup-string-cont
6255 @findex lineup-string-cont @r{(c-)}
6256 Line up a continued string under the one it continues. A continued
6257 string in this sense is where a string literal follows directly after
6262 result = prefix + "A message "
6263 "string."; @hereFn{c-lineup-string-cont}
6267 @code{nil} is returned in other situations, to allow stacking with other
6270 @workswith @code{topmost-intro-cont}, @code{statement-cont},
6271 @code{arglist-cont}, @code{arglist-cont-nonempty}.
6275 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6276 @node Comment Line-Up, Misc Line-Up, Operator Line-Up, Line-Up Functions
6277 @comment node-name, next, previous, up
6278 @subsection Comment Line-Up Functions
6279 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6281 The lineup functions here calculate the indentation for several types
6282 of comment structure.
6284 @defun c-lineup-C-comments
6285 @findex lineup-C-comments @r{(c-)}
6286 Line up C block comment continuation lines. Various heuristics are used
6287 to handle most of the common comment styles. Some examples:
6300 text ** text ** text
6307 /**************************************************
6309 *************************************************/
6313 @vindex comment-start-skip
6316 /**************************************************
6317 Free form text comments:
6318 In comments with a long delimiter line at the
6319 start, the indentation is kept unchanged for lines
6320 that start with an empty comment line prefix. The
6321 delimiter line is whatever matches the
6322 @code{comment-start-skip} regexp.
6323 **************************************************/
6327 The style variable @code{c-comment-prefix-regexp} is used to recognize
6328 the comment line prefix, e.g., the @samp{*} that usually starts every
6329 line inside a comment.
6331 @workswith The @code{c} syntactic symbol.
6334 @comment ------------------------------------------------------------
6336 @defun c-lineup-comment
6337 @findex lineup-comment @r{(c-)}
6338 Line up a comment-only line according to the style variable
6339 @code{c-comment-only-line-offset}. If the comment is lined up with a
6340 comment starter on the previous line, that alignment is preserved.
6342 @defopt c-comment-only-line-offset
6343 @vindex comment-only-line-offset @r{(c-)}
6344 This style variable specifies the extra offset for the line. It can
6345 contain an integer or a cons cell of the form
6348 (@r{@var{non-anchored-offset}} . @r{@var{anchored-offset}})
6352 where @var{non-anchored-offset} is the amount of offset given to
6353 non-column-zero anchored lines, and @var{anchored-offset} is the amount
6354 of offset to give column-zero anchored lines. Just an integer as value
6355 is equivalent to @code{(@r{@var{value}} . -1000)}.
6358 @workswith @code{comment-intro}.
6361 @comment ------------------------------------------------------------
6363 @defun c-lineup-knr-region-comment
6364 @findex lineup-knr-region-comment @r{(c-)}
6365 Line up a comment in the ``K&R region'' with the declaration. That is
6366 the region between the function or class header and the beginning of the
6372 /* Called at startup. */ @hereFn{c-lineup-knr-region-comment}
6379 Return @code{nil} if called in any other situation, to be useful in list
6382 @workswith @code{comment-intro}.
6385 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6386 @node Misc Line-Up, , Comment Line-Up, Line-Up Functions
6387 @comment node-name, next, previous, up
6388 @subsection Miscellaneous Line-Up Functions
6389 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6391 The line-up functions here are the odds and ends which didn't fit into
6392 any earlier category.
6394 @defun c-lineup-dont-change
6395 @findex lineup-dont-change @r{(c-)}
6396 This lineup function makes the line stay at whatever indentation it
6397 already has; think of it as an identity function for lineups.
6399 @workswith Any syntactic symbol.
6402 @comment ------------------------------------------------------------
6404 @defun c-lineup-under-anchor
6406 Line up a line directly underneath its anchor point. This is like
6407 @samp{0}, except any previously calculated offset contributions are
6410 @workswith Any syntactic symbol which has an anchor point.
6413 @comment ------------------------------------------------------------
6415 @defun c-lineup-cpp-define
6416 @findex lineup-cpp-define @r{(c-)}
6417 Line up macro continuation lines according to the indentation of the
6418 construct preceding the macro. E.g.:
6422 const char msg[] = @hereFn{@r{The beginning of the preceding construct.}}
6426 do @{ \ @hereFn{c-lineup-cpp-define}
6438 if (!running) @hereFn{@r{The beginning of the preceding construct.}}
6439 error(\"Not running!\");
6442 do @{ \ @hereFn{c-lineup-cpp-define}
6448 If @code{c-syntactic-indentation-in-macros} is non-@code{nil}, the
6449 function returns the relative indentation to the macro start line to
6450 allow accumulation with other offsets. E.g., in the following cases,
6451 @code{cpp-define-intro} is combined with the
6452 @code{statement-block-intro} that comes from the @samp{do @{} that hangs
6453 on the @samp{#define} line:
6460 #define X(A, B) do @{ \
6461 printf (A, B); \ @hereFn{c-lineup-cpp-define}
6463 @} while (0) @hereFn{c-lineup-cpp-define}
6474 error(\"Not running!\");
6476 #define X(A, B) do @{ \
6477 printf (A, B); \ @hereFn{c-lineup-cpp-define}
6479 @} while (0) @hereFn{c-lineup-cpp-define}
6483 The relative indentation returned by @code{c-lineup-cpp-define} is zero
6484 and two, respectively, on the two lines in each of these examples. They
6485 are then added to the two column indentation that
6486 @code{statement-block-intro} gives in both cases here.
6488 If the relative indentation is zero, then @code{nil} is returned
6489 instead. That is useful in a list expression to specify the default
6490 indentation on the top level.
6492 If @code{c-syntactic-indentation-in-macros} is @code{nil} then this
6493 function keeps the current indentation, except for empty lines (ignoring
6494 the ending backslash) where it takes the indentation from the closest
6495 preceding nonempty line in the macro. If there's no such line in the
6496 macro then the indentation is taken from the construct preceding it, as
6499 @workswith @code{cpp-define-intro}.
6502 @comment ------------------------------------------------------------
6504 @defun c-lineup-gcc-asm-reg
6505 @findex lineup-gcc-asm-reg @r{(c-)}
6506 Line up a gcc asm register under one on a previous line.
6519 The @samp{x} line is aligned to the text after the @samp{:} on the
6520 @samp{w} line, and similarly @samp{z} under @samp{y}.
6522 This is done only in an @samp{asm} or @samp{__asm__} block, and only to
6523 those lines mentioned. Anywhere else @code{nil} is returned. The usual
6524 arrangement is to have this routine as an extra feature at the start of
6525 arglist lineups, e.g.:
6528 (c-lineup-gcc-asm-reg c-lineup-arglist)
6531 @workswith @code{arglist-cont}, @code{arglist-cont-nonempty}.
6534 @comment ------------------------------------------------------------
6536 @defun c-lineup-topmost-intro-cont
6537 @findex lineup-topmost-intro-cont @r{(c-)}
6538 Line up declaration continuation lines zero or one indentation
6539 step@footnote{This function is mainly provided to mimic the behavior of
6540 CC Mode 5.28 and earlier where this case wasn't handled consistently so
6541 that those lines could be analyzed as either topmost-intro-cont or
6542 statement-cont. It's used for @code{topmost-intro-cont} by default, but
6543 you might consider using @code{+} instead.}. For lines preceding a
6544 definition, zero is used. For other lines, @code{c-basic-offset} is
6545 added to the indentation. E.g.:
6550 neg (int i) @hereFn{c-lineup-topmost-intro-cont}
6563 larch @hereFn{c-lineup-topmost-intro-cont}
6567 the_larch, @hereFn{c-lineup-topmost-intro-cont}
6568 another_larch; @hereFn{c-lineup-topmost-intro-cont}
6579 the_larch, @hereFn{c-lineup-topmost-intro-cont}
6580 another_larch; @hereFn{c-lineup-topmost-intro-cont}
6584 @workswith @code{topmost-intro-cont}.
6587 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6588 @node Custom Line-Up, Other Indentation, Line-Up Functions, Customizing Indentation
6589 @comment node-name, next, previous, up
6590 @section Custom Line-Up Functions
6591 @cindex customization, indentation functions
6592 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6594 The most flexible way to customize indentation is by writing custom
6595 line-up functions, and associating them with specific syntactic
6596 symbols (@pxref{c-offsets-alist}). Depending on the effect you want,
6597 it might be better to write a @code{c-special-indent-hook} function
6598 rather than a line-up function (@pxref{Other Indentation}).
6600 @ccmode{} comes with an extensive set of predefined line-up functions,
6601 not all of which are used by the default styles. So there's a good
6602 chance the function you want already exists. @xref{Line-Up
6603 Functions}, for a list of them. If you write your own line-up
6604 function, it's probably a good idea to start working from one of these
6605 predefined functions, which can be found in the file
6606 @file{cc-align.el}. If you have written a line-up function that you
6607 think is generally useful, you're very welcome to contribute it;
6608 please contact @email{bug-cc-mode@@gnu.org}.
6610 Line-up functions are passed a single argument, the syntactic
6611 element (see below). At the time of the call, point will be somewhere
6612 on the line being indented. The return value is a
6613 @code{c-offsets-alist} offset specification: for example, an integer,
6614 a symbol such as @code{+}, a vector, @code{nil}@footnote{Returning
6615 @code{nil} is useful when the offset specification for a syntactic
6616 element is a list containing the line-up function
6617 (@pxref{c-offsets-alist}).}, or even another line-up function. Full
6618 details of these are in @ref{c-offsets-alist}.
6620 Line-up functions must not move point or change the content of the
6621 buffer (except temporarily). They are however allowed to do
6622 @dfn{hidden buffer changes}, i.e., setting text properties for caching
6623 purposes etc. Buffer undo recording is disabled while they run.
6625 The syntactic element passed as the parameter to a line-up function is
6626 a cons cell of the form
6629 (@r{@var{syntactic-symbol}} . @r{@var{anchor-position}})
6633 @c FIXME!!! The following sentence might be better omitted, since the
6634 @c information is in the cross reference "Syntactic Analysis". 2005/10/2.
6635 where @var{syntactic-symbol} is the symbol that the function was
6636 called for, and @var{anchor-position} is the anchor position (if any)
6637 for the construct that triggered the syntactic symbol
6638 (@pxref{Syntactic Analysis}). This cons cell is how the syntactic
6639 element of a line used to be represented in @ccmode{} 5.28 and
6640 earlier. Line-up functions are still passed this cons cell, so as to
6641 preserve compatibility with older configurations. In the future, we
6642 may decide to convert to using the full list format---you can prepare
6643 your setup for this by using the access functions
6644 (@code{c-langelem-sym}, etc.)@: described below.
6646 @vindex c-syntactic-element
6647 @vindex syntactic-element @r{(c-)}
6648 @vindex c-syntactic-context
6649 @vindex syntactic-context @r{(c-)}
6650 Some syntactic symbols, e.g., @code{arglist-cont-nonempty}, have more
6651 info in the syntactic element: typically other positions that can be
6652 interesting besides the anchor position. That info can't be accessed
6653 through the passed argument, which is a cons cell. Instead, you can
6654 get this information from the variable @code{c-syntactic-element},
6655 which is dynamically bound to the complete syntactic element. The
6656 variable @code{c-syntactic-context} might also be useful: it gets
6657 dynamically bound to the complete syntactic context. @xref{Custom
6660 @ccmode{} provides a few functions to access parts of syntactic
6661 elements in a more abstract way. Besides making the code easier to
6662 read, they also hide the difference between the old cons cell form
6663 used in the line-up function argument and the new list form used in
6664 @code{c-syntactic-element} and everywhere else. The functions are:
6666 @defun c-langelem-sym langelem
6667 @findex langelem-sym @r{(c-)}
6668 Return the syntactic symbol in @var{langelem}.
6671 @defun c-langelem-pos langelem
6672 @findex langelem-pos @r{(c-)}
6673 Return the anchor position in @var{langelem}, or @code{nil} if there is none.
6676 @defun c-langelem-col langelem &optional preserve-point
6677 @findex langelem-col @r{(c-)}
6678 Return the column of the anchor position in @var{langelem}. Also move
6679 the point to that position unless @var{preserve-point} is
6683 @defun c-langelem-2nd-pos langelem
6684 @findex langelem-2nd-pos @r{(c-)}
6685 Return the secondary position in @var{langelem}, or @code{nil} if there
6688 Note that the return value of this function is always @code{nil} if
6689 @var{langelem} is in the old cons cell form. Thus this function is
6690 only meaningful when used on syntactic elements taken from
6691 @code{c-syntactic-element} or @code{c-syntactic-context}.
6694 Sometimes you may need to use the syntactic context of a line other
6695 than the one being indented. You can determine this by (temporarily)
6696 moving point onto this line and calling @code{c-guess-basic-syntax}
6697 (@pxref{Syntactic Analysis}).
6699 Custom line-up functions can be as simple or as complex as you like, and
6700 any syntactic symbol that appears in @code{c-offsets-alist} can have a
6701 custom line-up function associated with it.
6703 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6704 @node Other Indentation, , Custom Line-Up, Customizing Indentation
6705 @comment node-name, next, previous, up
6706 @section Other Special Indentations
6707 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6709 To configure macros which you invoke without a terminating @samp{;},
6710 see @xref{Macros with ;}.
6712 Here are the remaining odds and ends regarding indentation:
6714 @defopt c-label-minimum-indentation
6715 @vindex label-minimum-indentation @r{(c-)}
6716 In @samp{gnu} style (@pxref{Built-in Styles}), a minimum indentation is
6717 imposed on lines inside code blocks. This minimum indentation is
6718 controlled by this style variable. The default value is 1.
6720 @findex c-gnu-impose-minimum
6721 @findex gnu-impose-minimum @r{(c-)}
6722 It's the function @code{c-gnu-impose-minimum} that enforces this minimum
6723 indentation. It must be present on @code{c-special-indent-hook} to
6727 @defopt c-special-indent-hook
6728 @vindex special-indent-hook @r{(c-)}
6729 This style variable is a standard hook variable that is called after
6730 every line is indented by @ccmode{}. It is called only if
6731 @code{c-syntactic-indentation} is non-@code{nil} (which it is by
6732 default (@pxref{Indentation Engine Basics})). You can put a function
6733 on this hook to do any special indentation or ad hoc line adjustments
6734 your style dictates, such as adding extra indentation to constructors
6735 or destructor declarations in a class definition, etc. Sometimes it
6736 is better to write a custom Line-up Function instead (@pxref{Custom
6739 When the indentation engine calls this hook, the variable
6740 @code{c-syntactic-context} is bound to the current syntactic context
6741 (i.e., what you would get by typing @kbd{C-c C-s} on the source line.
6742 @xref{Custom Braces}.). Note that you should not change point or mark
6743 inside a @code{c-special-indent-hook} function, i.e., you'll probably
6744 want to wrap your function in a @code{save-excursion}@footnote{The
6745 numerical value returned by @code{point} will change if you change the
6746 indentation of the line within a @code{save-excursion} form, but point
6747 itself will still be over the same piece of text.}.
6749 Setting @code{c-special-indent-hook} in style definitions is handled
6750 slightly differently from other variables---A style can only add
6751 functions to this hook, not remove them. @xref{Style Variables}.
6755 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6756 @node Custom Macros, Odds and Ends, Customizing Indentation, Top
6757 @comment node-name, next, previous, up
6758 @chapter Customizing Macros
6760 @cindex preprocessor directives
6761 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6763 Preprocessor macros in C, C++, and Objective C (introduced by
6764 @code{#define}) have a syntax different from the main language---for
6765 example, a macro declaration is not terminated by a semicolon, and if
6766 it is more than a line long, line breaks in it must be escaped with
6767 backslashes. @ccmode{} has some commands to manipulate these, see
6768 @ref{Macro Backslashes}.
6770 Normally, the lines in a multi-line macro are indented relative to
6771 each other as though they were code. You can suppress this behavior
6772 by setting the following user option:
6774 @defopt c-syntactic-indentation-in-macros
6775 @vindex syntactic-indentation-in-macros @r{(c-)}
6776 Enable syntactic analysis inside macros, which is the default. If this
6777 is @code{nil}, all lines inside macro definitions are analyzed as
6778 @code{cpp-macro-cont}.
6781 Because a macro can expand into anything at all, near where one is
6782 invoked @ccmode{} can only indent and fontify code heuristically.
6783 Sometimes it gets it wrong. Usually you should try to design your
6784 macros so that they ''look like ordinary code'' when you invoke them.
6785 However, two situations are so common that @ccmode{} handles them
6786 specially: that is when certain macros needn't (or mustn't) be
6787 followed by a @samp{;}, and when certain macros (or compiler
6788 directives) expand to nothing. You need to configure @ccmode{} to
6789 handle these macros properly, see @ref{Macros with ;} and @ref{Noise
6792 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6794 * Macro Backslashes::
6799 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6800 @node Macro Backslashes, Macros with ;, Custom Macros, Custom Macros
6801 @comment node-name, next, previous, up
6802 @section Customizing Macro Backslashes
6803 @cindex @code{#define}
6804 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6806 @ccmode{} provides some tools to help keep the line continuation
6807 backslashes in macros neat and tidy. Their precise action is
6808 customized with these variables:
6810 @defopt c-backslash-column
6811 @vindex backslash-column @r{(c-)}
6812 @defoptx c-backslash-max-column
6813 @vindex backslash-max-column @r{(c-)}
6814 These variables control the alignment columns for line continuation
6815 backslashes in multiline macros. They are used by the functions that
6816 automatically insert or align such backslashes,
6817 e.g., @code{c-backslash-region} and @code{c-context-line-break}.
6819 @code{c-backslash-column} specifies the minimum column for the
6820 backslashes. If any line in the macro goes past this column, then the
6821 next tab stop (i.e., next multiple of @code{tab-width}) in that line is
6822 used as the alignment column for all the backslashes, so that they
6823 remain in a single column. However, if any lines go past
6824 @code{c-backslash-max-column} then the backslashes in the rest of the
6825 macro will be kept at that column, so that the lines which are too
6826 long ``stick out'' instead.
6828 Don't ever set these variables to @code{nil}. If you want to disable
6829 the automatic alignment of backslashes, use
6830 @code{c-auto-align-backslashes}.
6833 @defopt c-auto-align-backslashes
6834 @vindex auto-align-backslashes @r{(c-)}
6835 Align automatically inserted line continuation backslashes if
6836 non-@code{nil}. When line continuation backslashes are inserted
6837 automatically for line breaks in multiline macros, e.g., by
6838 @code{c-context-line-break}, they are aligned with the other
6839 backslashes in the same macro if this flag is set.
6841 If @code{c-auto-align-backslashes} is @code{nil}, automatically
6842 inserted backslashes are preceded by a single space, and backslashes
6843 get aligned only when you explicitly invoke the command
6844 @code{c-backslash-region} (@kbd{C-c C-\}).
6847 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6848 @node Macros with ;, Noise Macros, Macro Backslashes, Custom Macros
6849 @comment node-name, next, previous, up
6850 @section Macros with semicolons
6851 @cindex macros with semicolons
6852 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6853 Macros which needn't (or mustn't) be followed by a semicolon when you
6854 invoke them, @dfn{macros with semicolons}, are very common. These can
6855 cause @ccmode{} to parse the next line wrongly as a
6856 @code{statement-cont} (@pxref{Function Symbols}) and thus mis-indent
6857 it. At the top level, a macro invocation before a defun start can
6858 cause, for example, @code{c-beginning-of-defun} (@kbd{C-M-a}) not to
6859 find the correct start of the current function.
6861 You can prevent these by specifying which macros have semicolons. It
6862 doesn't matter whether or not such a macro has a parameter list:
6864 @defopt c-macro-names-with-semicolon
6865 @vindex macro-names-with-semicolon @r{(c-)}
6866 This buffer-local variable specifies which macros have semicolons.
6867 After setting its value, you need to call
6868 @code{c-make-macro-with-semi-re} for it to take effect. It should be
6869 set to one of these values:
6873 There are no macros with semicolons.
6874 @item a list of strings
6875 Each string is the name of a macro with a semicolon. Only valid
6876 @code{#define} names are allowed here. For example, to set the
6877 default value, you could write the following into your @file{.emacs}:
6880 (setq c-macro-names-with-semicolon
6881 '("Q_OBJECT" "Q_PROPERTY" "Q_DECLARE" "Q_ENUMS"))
6884 @item a regular expression
6885 This matches each symbol which is a macro with a semicolon. It must
6886 not match any string which isn't a valid @code{#define} name. For
6890 (setq c-macro-names-with-semicolon
6891 "\\<\\(CLEAN_UP_AND_RETURN\\|Q_[[:upper:]]+\\)\\>")
6896 @defun c-make-macro-with-semi-re
6897 @findex make-macro-with-semi-re @r{(c-)}
6898 Call this (non-interactive) function, which sets internal variables,
6899 each time you change the value of @code{c-macro-names-with-semicolon}
6900 after the major mode function has run. It takes no arguments, and its
6901 return value has no meaning. This function is called by @ccmode{}'s
6902 initialization code, after the mode hooks have run.
6905 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6906 @node Noise Macros, , Macros with ;, Custom Macros
6907 @comment node-name, next, previous, up
6908 @section Noise Macros
6909 @cindex noise macros
6910 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6912 In @ccmode{}, @dfn{noise macros} are macros which expand to nothing,
6913 or compiler directives (such as GCC's @code{__attribute__}) which play
6914 no part in the syntax of the C (etc.) language. Some noise macros are
6915 followed by arguments in parentheses (possibly optionally), others
6918 Noise macros can easily confuse @ccmode{}'s analysis of function
6919 headers, causing them to be mis-fontified, or even mis-indented. You
6920 can prevent this confusion by specifying the identifiers which
6921 constitute noise macros.
6923 @defopt c-noise-macro-names
6924 @vindex noise-macro-names @r{(c-)}
6925 This variable is a list of names of noise macros which never have
6926 parenthesized arguments. Each element is a string, and must be a
6927 valid identifier. An element in @code{c-noise-macro-names} must not
6928 also be in @code{c-noise-macro-with-parens-names}. Such an element is
6929 treated as whitespace by @ccmode{}.
6932 @defopt c-noise-macro-with-parens-names
6933 @vindex noise-macro-with-parens-names @r{(c-)}
6934 This variable is a list of names of noise macros which optionally have
6935 arguments in parentheses. Each element of the list is a string, and
6936 must be a valid identifier. An element in
6937 @code{c-noise-macro-with-parens-names} must not also be in
6938 @code{c-noise-macro-names}. For performance reasons, such an element,
6939 together with the optional parenthesized arguments, is specially
6940 handled, but it is only handled when used in declaration
6941 contexts@footnote{If this restriction causes your project
6942 difficulties, please get in touch with @email{bug-cc-mode@@gnu.org}.}.
6944 The two compiler directives @code{__attribute__} and @code{__declspec}
6945 have traditionally been handled specially in @ccmode{}; for example
6946 they are fontified with font-lock-keyword-face. You don't need to
6947 include these directives in @code{c-noise-macro-with-parens-names},
6951 @defun c-make-noise-macro-regexps
6952 @findex make-noise-macro-regexps @r{(c-)}
6953 Call this (non-interactive) function, which sets internal variables,
6954 on changing the value of @code{c-noise-macro-names} or
6955 @code{c-noise-macro-with-parens-names} after the major mode's function
6956 has run. This function is called by @ccmode{}'s initialization code,
6957 after the mode hooks have run.
6960 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6961 @node Odds and Ends, Sample Init File, Custom Macros, Top
6962 @comment node-name, next, previous, up
6963 @chapter Odds and Ends
6964 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6966 The stuff that didn't fit in anywhere else is documented here.
6968 @defopt c-require-final-newline
6969 @vindex require-final-newline @r{(c-)}
6970 Controls whether a final newline is enforced when the file is saved.
6971 The value is an association list that for each language mode specifies
6972 the value to give to @code{require-final-newline} (@pxref{Saving
6973 Buffers,,,@lispref{}, @lispreftitle{}}) at mode initialization. If a
6974 language isn't present on the association list, CC Mode won't touch
6975 @code{require-final-newline} in buffers for that language.
6977 The default is to set @code{require-final-newline} to @code{t} in the
6978 languages that mandate that source files should end with newlines.
6979 These are C, C++ and Objective-C.
6982 @defopt c-echo-syntactic-information-p
6983 @vindex echo-syntactic-information-p @r{(c-)}
6984 If non-@code{nil}, the syntactic analysis for the current line is shown
6985 in the echo area when it's indented (unless
6986 @code{c-syntactic-indentation} is @code{nil}). That's useful when
6987 finding out which syntactic symbols to modify to get the indentation you
6991 @defopt c-report-syntactic-errors
6992 @vindex report-syntactic-errors @r{(c-)}
6993 If non-@code{nil}, certain syntactic errors are reported with a ding and
6994 a message, for example when an @code{else} is indented for which there
6995 is no corresponding @code{if}.
6997 Note however that @ccmode{} doesn't make any special effort to check for
6998 syntactic errors; that's the job of the compiler. The reason it can
6999 report cases like the one above is that it can't find the correct
7000 anchoring position to indent the line in that case.
7004 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
7005 @node Sample Init File, Performance Issues, Odds and Ends, Top
7006 @comment node-name, next, previous, up
7007 @appendix Sample Init File
7008 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
7010 Here's a sample .emacs file fragment that might help you along the way.
7011 Just copy this region and paste it into your .emacs file. You might want
7012 to change some of the actual values.
7015 ;; Make a non-standard key binding. We can put this in
7016 ;; c-mode-base-map because c-mode-map, c++-mode-map, and so on,
7018 (defun my-c-initialization-hook ()
7019 (define-key c-mode-base-map "\C-m" 'c-context-line-break))
7020 (add-hook 'c-initialization-hook 'my-c-initialization-hook)
7022 ;; offset customizations not in my-c-style
7023 ;; This will take precedence over any setting of the syntactic symbol
7025 (setq c-offsets-alist '((member-init-intro . ++)))
7027 ;; Create my personal style.
7028 (defconst my-c-style
7029 '((c-tab-always-indent . t)
7030 (c-comment-only-line-offset . 4)
7031 (c-hanging-braces-alist . ((substatement-open after)
7033 (c-hanging-colons-alist . ((member-init-intro before)
7037 (access-label after)))
7038 (c-cleanup-list . (scope-operator
7041 (c-offsets-alist . ((arglist-close . c-lineup-arglist)
7042 (substatement-open . 0)
7045 (knr-argdecl-intro . -)))
7046 (c-echo-syntactic-information-p . t))
7047 "My C Programming Style")
7048 (c-add-style "PERSONAL" my-c-style)
7050 ;; Customizations for all modes in CC Mode.
7051 (defun my-c-mode-common-hook ()
7052 ;; set my personal style for the current buffer
7053 (c-set-style "PERSONAL")
7054 ;; other customizations
7056 ;; this will make sure spaces are used instead of tabs
7057 indent-tabs-mode nil)
7058 ;; we like auto-newline, but not hungry-delete
7059 (c-toggle-auto-newline 1))
7060 (add-hook 'c-mode-common-hook 'my-c-mode-common-hook)
7063 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
7064 @node Performance Issues, Limitations and Known Bugs, Sample Init File, Top
7065 @comment node-name, next, previous, up
7066 @appendix Performance Issues
7068 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
7070 @comment FIXME: (ACM, 2003/5/24). Check whether AWK needs mentioning here.
7072 C and its derivative languages are highly complex creatures. Often,
7073 ambiguous code situations arise that require @ccmode{} to scan large
7074 portions of the buffer to determine syntactic context. Such
7075 pathological code can cause @ccmode{} to perform fairly badly. This
7076 section gives some insight in how @ccmode{} operates, how that interacts
7077 with some coding styles, and what you can use to improve performance.
7079 The overall goal is that @ccmode{} shouldn't be overly slow (i.e., take
7080 more than a fraction of a second) in any interactive operation.
7081 I.e., it's tuned to limit the maximum response time in single operations,
7082 which is sometimes at the expense of batch-like operations like
7083 reindenting whole blocks. If you find that @ccmode{} gradually gets
7084 slower and slower in certain situations, perhaps as the file grows in
7085 size or as the macro or comment you're editing gets bigger, then chances
7086 are that something isn't working right. You should consider reporting
7087 it, unless it's something that's mentioned in this section.
7089 Because @ccmode{} has to scan the buffer backwards from the current
7090 insertion point, and because C's syntax is fairly difficult to parse in
7091 the backwards direction, @ccmode{} often tries to find the nearest
7092 position higher up in the buffer from which to begin a forward scan
7093 (it's typically an opening or closing parenthesis of some kind). The
7094 farther this position is from the current insertion point, the slower it
7097 @findex beginning-of-defun
7098 In earlier versions of @ccmode{}, we used to recommend putting the
7099 opening brace of a top-level construct@footnote{E.g., a function in C,
7100 or outermost class definition in C++ or Java.} into the leftmost
7101 column. Earlier still, this used to be a rigid Emacs constraint, as
7102 embodied in the @code{beginning-of-defun} function. @ccmode now
7103 caches syntactic information much better, so that the delay caused by
7104 searching for such a brace when it's not in column 0 is minimal,
7105 except perhaps when you've just moved a long way inside the file.
7107 @findex defun-prompt-regexp
7108 @vindex c-Java-defun-prompt-regexp
7109 @vindex Java-defun-prompt-regexp @r{(c-)}
7110 A special note about @code{defun-prompt-regexp} in Java mode: The common
7111 style is to hang the opening braces of functions and classes on the
7112 right side of the line, and that doesn't work well with the Emacs
7113 approach. @ccmode{} comes with a constant
7114 @code{c-Java-defun-prompt-regexp} which tries to define a regular
7115 expression usable for this style, but there are problems with it. In
7116 some cases it can cause @code{beginning-of-defun} to hang@footnote{This
7117 has been observed in Emacs 19.34 and XEmacs 19.15.}. For this reason,
7118 it is not used by default, but if you feel adventurous, you can set
7119 @code{defun-prompt-regexp} to it in your mode hook. In any event,
7120 setting and relying on @code{defun-prompt-regexp} will definitely slow
7121 things down because (X)Emacs will be doing regular expression searches a
7122 lot, so you'll probably be taking a hit either way!
7124 @ccmode{} maintains a cache of the opening parentheses of the blocks
7125 surrounding the point, and it adapts that cache as the point is moved
7126 around. That means that in bad cases it can take noticeable time to
7127 indent a line in a new surrounding, but after that it gets fast as long
7128 as the point isn't moved far off. The farther the point is moved, the
7129 less useful is the cache. Since editing typically is done in ``chunks''
7130 rather than on single lines far apart from each other, the cache
7131 typically gives good performance even when the code doesn't fit the
7132 Emacs approach to finding the defun starts.
7134 @vindex c-enable-xemacs-performance-kludge-p
7135 @vindex enable-xemacs-performance-kludge-p @r{(c-)}
7136 XEmacs users can set the variable
7137 @code{c-enable-xemacs-performance-kludge-p} to non-@code{nil}. This
7138 tells @ccmode{} to use XEmacs-specific built-in functions which, in some
7139 circumstances, can locate the top-most opening brace much more quickly than
7140 @code{beginning-of-defun}. Preliminary testing has shown that for
7141 styles where these braces are hung (e.g., most JDK-derived Java styles),
7142 this hack can improve performance of the core syntax parsing routines
7143 from 3 to 60 times. However, for styles which @emph{do} conform to
7144 Emacs's recommended style of putting top-level braces in column zero,
7145 this hack can degrade performance by about as much. Thus this variable
7146 is set to @code{nil} by default, since the Emacs-friendly styles should
7147 be more common (and encouraged!). Note that this variable has no effect
7148 in Emacs since the necessary built-in functions don't exist (in Emacs
7149 22.1 as of this writing in February 2007).
7151 Text properties are used to speed up skipping over syntactic whitespace,
7152 i.e., comments and preprocessor directives. Indenting a line after a
7153 huge macro definition can be slow the first time, but after that the
7154 text properties are in place and it should be fast (even after you've
7155 edited other parts of the file and then moved back).
7157 Font locking can be a CPU hog, especially the font locking done on
7158 decoration level 3 which tries to be very accurate. Note that that
7159 level is designed to be used with a font lock support mode that only
7160 fontifies the text that's actually shown, i.e., Lazy Lock or Just-in-time
7161 Lock mode, so make sure you use one of them. Fontification of a whole
7162 buffer with some thousand lines can often take over a minute. That is
7163 a known weakness; the idea is that it never should happen.
7165 The most effective way to speed up font locking is to reduce the
7166 decoration level to 2 by setting @code{font-lock-maximum-decoration}
7167 appropriately. That level is designed to be as pretty as possible
7168 without sacrificing performance. @xref{Font Locking Preliminaries}, for
7172 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
7173 @node Limitations and Known Bugs, FAQ, Performance Issues, Top
7174 @comment node-name, next, previous, up
7175 @appendix Limitations and Known Bugs
7178 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
7182 @ccmode{} doesn't support trigraphs. (These are character sequences
7183 such as @samp{??(}, which represents @samp{[}. They date from a time
7184 when some character sets didn't have all the characters that C needs,
7185 and are now utterly obsolete.)
7188 There is no way to apply auto newline settings (@pxref{Auto-newlines})
7189 on already typed lines. That's only a feature to ease interactive
7192 To generalize this issue a bit: @ccmode{} is not intended to be used as
7193 a reformatter for old code in some more or less batch-like way. With
7194 the exception of some functions like @code{c-indent-region}, it's only
7195 geared to be used interactively to edit new code. There's currently no
7196 intention to change this goal.
7198 If you want to reformat old code, you're probably better off using some
7199 other tool instead, e.g., @ref{Top, , GNU indent, indent, The `indent'
7200 Manual}, which has more powerful reformatting capabilities than
7204 The support for C++ templates (in angle brackets) is not yet complete.
7205 When a non-nested template is used in a declaration, @ccmode{} indents
7206 it and font-locks it OK@. Templates used in expressions, and nested
7207 templates do not fare so well. Sometimes a workaround is to refontify
7208 the expression after typing the closing @samp{>}.
7211 In a @dfn{k&r region} (the part of an old-fashioned C function
7212 declaration which specifies the types of its parameters, coming
7213 between the parameter list and the opening brace), there should be at
7214 most 20 top-level parenthesis and bracket pairs. This limit has been
7215 imposed for performance reasons. If it is violated, the source file
7216 might be incorrectly indented or fontified.
7219 On loading @ccmode{}, sometimes this error message appears:
7222 File mode specification error: (void-variable c-font-lock-keywords-3)
7225 This is due to a bug in the function @code{eval-after-load} in some
7226 versions of (X)Emacs. It can manifest itself when there is a symbolic
7227 link in the path of the directory which contains (X)Emacs. As a
7228 workaround, put the following into your @file{.emacs} file, fairly
7232 (defun my-load-cc-fonts ()
7233 (require "cc-fonts"))
7234 (add-hook 'c-initialization-hook 'my-load-cc-fonts)
7238 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
7239 @node FAQ, Updating CC Mode, Limitations and Known Bugs, Top
7240 @comment node-name, next, previous, up
7241 @appendix Frequently Asked Questions
7242 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
7246 @emph{How can I change the indent level from 4 spaces to 2 spaces?}
7248 Set the variable @code{c-basic-offset}. @xref{Getting Started}.
7253 @emph{Why does/doesn't the @kbd{@key{RET}} key indent the new line?}
7255 Emacs's convention used to be that @kbd{RET} just adds a newline, and that
7256 @kbd{C-j} adds a newline and indents it. In Emacs-24.4, this convention was
7259 If you use an older Emacs and you want @kbd{@key{RET}} do this
7260 too, add this to your @code{c-initialization-hook}:
7263 (define-key c-mode-base-map "\C-m" 'c-context-line-break)
7266 @xref{Getting Started}. This was a very common question.
7269 @emph{How do I get block comments in my C++ files?}
7271 Interactively, change the comment style with @kbd{C-c C-k}.
7274 To configure this setting, say, for files within the gdb project, you
7275 could amend your C++ Mode hook like this:
7278 (defun my-c++-mode-hook ()
7279 (if (string-match "/gdb/" (buffer-file-name))
7280 (c-toggle-comment-style 1)))
7281 (add-hook 'c++-mode-hook 'my-c++-mode-hook)
7285 @emph{How do I stop my C++ lambda expressions being indented way over
7288 Change the offset associated with @code{inlambda} from its default,
7289 the function @code{c-lineup-inexpr-block}, to 0. For example, if you
7290 are setting offsets in a hook function you might include the following
7294 (c-set-offset 'inlambda 0)
7297 For details of the different ways you can make this setting,
7298 @ref{Config Basics}.
7301 @emph{How do I stop my code jumping all over the place when I type?}
7303 Deactivate ``electric minor mode'' with @kbd{C-c C-l}. @xref{Getting
7309 @emph{How do I reindent the whole file?}
7311 Visit the file and hit @kbd{C-x h} to mark the whole buffer. Then hit
7312 @kbd{C-M-\}. @xref{Indentation Commands}.
7317 @emph{How do I reindent the current block?}
7319 First move to the brace which opens the block with @kbd{C-M-u}, then
7320 reindent that expression with @kbd{C-M-q}. @xref{Indentation
7324 @emph{I put @code{(c-set-offset 'substatement-open 0)} in my
7325 @file{.emacs} file but I get an error saying that @code{c-set-offset}'s
7326 function definition is void. What's wrong?}
7328 This means that @ccmode{} hasn't yet been loaded into your Emacs
7329 session by the time the @code{c-set-offset} call is reached, most
7330 likely because @ccmode{} is being autoloaded. Instead of putting the
7331 @code{c-set-offset} line in your top-level @file{.emacs} file, put it
7332 in your @code{c-initialization-hook} (@pxref{CC Hooks}), or simply
7333 modify @code{c-offsets-alist} directly:
7336 (setq c-offsets-alist '((substatement-open . 0)))
7340 @cindex open paren in column zero
7341 @emph{I have an open paren character at column zero inside a comment or
7342 multiline string literal, and it causes the fontification and/or
7343 indentation to go haywire. What gives?}
7345 It's due to the ad-hoc rule in (X)Emacs that such open parens always
7346 start defuns (which translates to functions, classes, namespaces or any
7347 other top-level block constructs in the @ccmode{} languages).
7349 @xref{Defuns,,, xemacs, XEmacs User's Manual}, for details.
7352 @xref{Left Margin Paren,,, emacs, GNU Emacs Manual}, for details
7353 (@xref{Defuns,,, emacs, GNU Emacs Manual}, in the Emacs 20 manual).
7356 This heuristic is built into the core syntax analysis routines in
7357 (X)Emacs, so it's not really a @ccmode{} issue. However, in Emacs
7358 21.1 it became possible to turn it off@footnote{Using the variable
7359 @code{open-paren-in-column-0-is-defun-start}.} and @ccmode{} does so
7360 there since it's got its own system to keep track of blocks.
7365 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
7366 @node Updating CC Mode, Mailing Lists and Bug Reports, FAQ, Top
7367 @comment node-name, next, previous, up
7368 @appendix Getting the Latest CC Mode Release
7369 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
7371 @ccmode{} has been standard with all versions of Emacs since 19.34 and
7372 of XEmacs since 19.16.
7375 Due to release schedule skew, it is likely that all of these Emacsen
7376 have old versions of @ccmode{} and so should be upgraded. Access to the
7377 @ccmode{} source code, as well as more detailed information on Emacsen
7378 compatibility, etc.@: are all available on the web site:
7381 @uref{http://cc-mode.sourceforge.net/}
7385 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
7386 @node Mailing Lists and Bug Reports, GNU Free Documentation License, Updating CC Mode, Top
7387 @comment node-name, next, previous, up
7388 @appendix Mailing Lists and Submitting Bug Reports
7389 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
7392 @findex c-submit-bug-report
7393 @findex submit-bug-report @r{(c-)}
7394 To report bugs, use the @kbd{C-c C-b} (bound to
7395 @code{c-submit-bug-report}) command. This provides vital information
7396 we need to reproduce your problem. Make sure you include a concise,
7397 but complete code example. Please try to boil your example down to
7398 just the essential code needed to reproduce the problem, and include
7399 an exact recipe of steps needed to expose the bug. Be especially sure
7400 to include any code that appears @emph{before} your bug example, if
7401 you think it might affect our ability to reproduce it.
7403 Please try to produce the problem in an Emacs instance without any
7404 customizations loaded (i.e., start it with the @samp{-q --no-site-file}
7405 arguments). If it works correctly there, the problem might be caused
7406 by faulty customizations in either your own or your site
7407 configuration. In that case, we'd appreciate it if you isolate the
7408 Emacs Lisp code that triggers the bug and include it in your report.
7410 @cindex bug report mailing list
7411 Reporting a bug using @code{c-submit-bug-report} files it in
7412 the GNU Bug Tracker at @url{https://debbugs.gnu.org}, then sends it on
7413 to @email{bug-cc-mode@@gnu.org}. You can also send reports, other
7414 questions, and suggestions (kudos?@: @t{;-)} to that address. It's a
7415 mailing list which you can join or browse an archive of; see the web site at
7416 @uref{http://cc-mode.sourceforge.net/} for further details.
7418 @cindex announcement mailing list
7419 If you want to get announcements of new @ccmode{} releases, send the
7420 word @emph{subscribe} in the body of a message to
7421 @email{cc-mode-announce-request@@lists.sourceforge.net}. It's possible
7422 to subscribe from the web site too. Announcements will also be posted
7423 to the Usenet newsgroups @code{gnu.emacs.sources}, @code{comp.emacs},
7424 @code{comp.emacs.xemacs}, @code{comp.lang.c}, @code{comp.lang.c++},
7425 @code{comp.lang.objective-c}, @code{comp.lang.java.softwaretools},
7426 @code{comp.lang.idl}, and @code{comp.lang.awk}.
7427 @c There is no newsgroup for Pike. :-(
7430 @node GNU Free Documentation License, Command and Function Index, Mailing Lists and Bug Reports, Top
7431 @appendix GNU Free Documentation License
7432 @include doclicense.texi
7435 @c Removed the tentative node "Mode Initialization" from here, 2005/8/27.
7436 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
7437 @node Command and Function Index, Variable Index, GNU Free Documentation License, Top
7438 @comment node-name, next, previous, up
7439 @unnumbered Command and Function Index
7440 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
7442 Since most @ccmode{} commands are prepended with the string
7443 @samp{c-}, each appears under its @code{c-@var{thing}} name and its
7444 @code{@var{thing} (c-)} name.
7451 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
7452 @node Variable Index, Concept and Key Index, Command and Function Index, Top
7453 @comment node-name, next, previous, up
7454 @unnumbered Variable Index
7455 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
7457 Since most @ccmode{} variables are prepended with the string
7458 @samp{c-}, each appears under its @code{c-@var{thing}} name and its
7459 @code{@var{thing} (c-)} name.
7466 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
7467 @node Concept and Key Index, , Variable Index, Top
7468 @comment node-name, next, previous, up
7469 @unnumbered Concept and Key Index
7470 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
7475 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
7477 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!