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 cc-mode.info
85 @settitle CC Mode Manual
88 @c The following four macros generate the filenames and titles of the
89 @c main (X)Emacs manual and the Elisp/Lispref manual. Leave the
90 @c Texinfo variable `XEMACS' unset to generate a GNU Emacs version, set it
91 @c to generate an XEmacs version, e.g. with
92 @c "makeinfo -DXEMACS cc-mode.texi".
104 XEmacs Lisp Reference Manual
119 GNU Emacs Lisp Reference Manual
128 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
129 @comment @setchapternewpage odd !! we don't want blank pages !!
130 @comment %**end of header (This is for running Texinfo on a region)
131 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
134 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
136 @comment Texinfo manual for CC Mode
137 @comment Generated from the original README file by Krishna Padmasola
138 @comment <krishna@earth-gw.njit.edu>
141 @comment Barry A. Warsaw
142 @comment Martin Stjernholm
143 @comment Alan Mackenzie
145 @comment Maintained by Martin Stjernholm and Alan Mackenzie <bug-cc-mode@gnu.org>
147 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
149 @comment Define an index for syntactic symbols.
150 @ifnottex @c In texi2dvi, the @defindex would create an empty cc-mode.ss
151 @c For Info, unlike tex, @syncodeindex needs a matching @defindex.
155 @comment Combine key, syntactic symbol and concept indices into one.
160 Copyright @copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
161 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 Free
162 Software Foundation, Inc.
164 This manual is free documentation; you can redistribute it and/or
165 modify it under the terms of the GNU General Public License as
166 published by the Free Software Foundation; either version 3, or (at
167 your option) any later version.
169 This manual is distributed in the hope that it will be useful, but
170 WITHOUT ANY WARRANTY; without even the implied warranty of
171 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
172 General Public License for more details.
174 You should have received a copy of the GNU General Public License, the
175 file @file{COPYING}, along with @ccmode{}. If not, see
176 @url{http://www.gnu.org/licenses/gpl.html}.
179 @comment Info directory entry for use by install-info. The indentation
180 @comment here is by request from the FSF folks.
183 * CC Mode: (cc-mode). Emacs mode for editing C, C++, Objective-C,
184 Java, Pike, AWK, and CORBA IDL code.
187 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
188 @comment TeX title page
189 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
195 @center @titlefont{CC Mode 5.32}
197 @center @subtitlefont{A GNU Emacs mode for editing C and C-like languages}
199 @center Barry A. Warsaw, Martin Stjernholm, Alan Mackenzie
204 @subtitle A GNU Emacs mode for editing C and C-like languages
206 @author Barry A. Warsaw, Martin Stjernholm, Alan Mackenzie
210 @vskip 0pt plus 1filll
213 This manual was generated from $Revision: 5.266 $ of $RCSfile: cc-mode.texi,v $, which can be
215 @url{http://cc-mode.cvs.sourceforge.net/viewvc/cc-mode/cc-mode/cc-mode.texi}.
218 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
219 @comment The Top node contains the master menu for the Info file.
220 @comment This appears only in the Info file, not the printed manual.
221 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
223 @node Top, Introduction, (dir), (dir)
224 @comment node-name, next, previous, up
229 @ccmode{} is a GNU Emacs mode for editing files containing C, C++,
230 Objective-C, Java, CORBA IDL (and the variants PSDL and CIDL), Pike
231 and AWK code. It provides syntax-based indentation, font locking, and
232 has several handy commands and some minor modes to make the editing
233 easier. It does not provide tools to look up and navigate between
234 functions, classes etc - there are other packages for that.
237 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
238 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
247 * Custom Filling and Breaking::
248 * Custom Auto-newlines::
250 * Indentation Engine Basics::
251 * Customizing Indentation::
254 * Sample .emacs File::
255 * Performance Issues::
256 * Limitations and Known Bugs::
259 * Mailing Lists and Bug Reports::
260 * Command and Function Index::
262 * Concept and Key Index::
265 --- The Detailed Node Listing ---
269 * Indentation Commands::
271 * Movement Commands::
272 * Filling and Breaking::
276 * Hungry WS Deletion::
282 * Font Locking Preliminaries::
285 * AWK Mode Font Locking::
298 * Guessing the Style::
301 Customizing Auto-newlines
305 * Hanging Semicolons and Commas::
311 Indentation Engine Basics
313 * Syntactic Analysis::
314 * Syntactic Symbols::
315 * Indentation Calculation::
321 * Conditional Construct Symbols::
322 * Switch Statement Symbols::
323 * Brace List Symbols::
324 * External Scope Symbols::
325 * Paren List Symbols::
327 * Multiline Macro Symbols::
328 * Objective-C Method Symbols::
330 * Statement Block Symbols::
333 Customizing Indentation
336 * Interactive Customization::
337 * Line-Up Functions::
339 * Other Indentation::
343 * Brace/Paren Line-Up::
351 * Macro Backslashes::
357 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
358 @node Introduction, Overview, Top, Top
359 @comment node-name, next, previous, up
360 @chapter Introduction
361 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
369 Welcome to @ccmode{}, a GNU Emacs mode for editing files containing C,
370 C++, Objective-C, Java, CORBA IDL (and the variants CORBA PSDL and
371 CIDL), Pike and AWK code. This incarnation of the mode is descended
372 from @file{c-mode.el} (also called ``Boring Old C Mode'' or BOCM
373 @t{:-)}, @file{c++-mode.el} version 2, which Barry Warsaw had been
374 maintaining since 1992, and @file{awk-mode.el}, a long neglected mode
375 in the (X)Emacs base.
377 Late in 1997, Martin Stjernholm joined Barry on the @ccmode{}
378 Maintainers Team, and implemented the Pike support. In 2000 Martin
379 took over as the sole maintainer. In 2001 Alan Mackenzie joined the
380 team, implementing AWK support in version 5.30. @ccmode{} did not
381 originally contain the font lock support for its languages --- that
382 was added in version 5.30.
384 This manual describes @ccmode{}
385 @comment The following line must appear on its own, so that the
387 @comment Release.py script can update the version number automatically
389 @ccmode{} supports the editing of K&R and ANSI C, C++, Objective-C,
390 Java, CORBA's Interface Definition Language, Pike@footnote{A C-like
391 scripting language with its roots in the LPC language used in some MUD
392 engines. See @uref{http://pike.ida.liu.se/}.} and AWK files. In this
393 way, you can easily set up consistent font locking and coding styles for
394 use in editing all of these languages, although AWK is not yet as
395 uniformly integrated as the other languages.
404 Note that the name of this package is ``@ccmode{}'', but there is no top
405 level @code{cc-mode} entry point. All of the variables, commands, and
406 functions in @ccmode{} are prefixed with @code{c-@var{thing}}, and
407 @code{c-mode}, @code{c++-mode}, @code{objc-mode}, @code{java-mode},
408 @code{idl-mode}, @code{pike-mode}, and @code{awk-mode} entry points are
409 provided. This package is intended to be a replacement for
410 @file{c-mode.el}, @file{c++-mode.el} and @file{awk-mode.el}.
412 A special word of thanks goes to Krishna Padmasola for his work in
413 converting the original @file{README} file to Texinfo format. I'd
414 also like to thank all the @ccmode{} victims who help enormously
415 during the early beta stages of @ccmode{}'s development.
417 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
418 @node Overview, Getting Started, Introduction, Top
419 @comment node-name, next, previous, up@cindex organization of the manual
420 @chapter Overview of the Manual
421 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
424 The manual starts with several introductory chapters (including this
428 The next chunk of the manual describes the day to day @emph{use} of
429 @ccmode{} (as contrasted with how to customize it).
433 The chapter ``Commands'' describes in detail how to use (nearly) all
434 of @ccmode{}'s features. There are extensive cross-references from
435 here to the corresponding sections later in the manual which tell you
436 how to customize these features.
439 ``Font Locking'' describes how ``syntax highlighting'' is applied to
440 your buffers. It is mainly background information and can be skipped
441 over at a first reading.
445 The next chunk of the manual describes how to @emph{customize}
446 @ccmode{}. Typically, an overview of a topic is given at the chapter
447 level, then the sections and subsections describe the material in
452 The chapter ``Configuration Basics'' tells you @emph{how} to write
453 customizations - whether in hooks, in styles, in both, or in neither,
454 depending on your needs. It describes the @ccmode{} style system and
455 lists the standard styles that @ccmode{} supplies.
458 The next few chapters describe in detail how to customize the various
459 features of @ccmode{}.
462 Finally, there is a sample @file{.emacs} fragment, which might help you
463 in creating your own customization.
467 The manual ends with ``this and that'', things that don't fit cleanly
468 into any of the previous chunks.
472 Two chapters discuss the performance of @ccmode{} and known
476 The FAQ contains a list of common problems and questions.
479 The next two chapters tell you how to get in touch with the @ccmode{}
480 project - whether for updating @ccmode{} or submitting bug reports.
484 Finally, there are the customary indices.
486 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
487 @node Getting Started, Commands, Overview, Top
488 @comment node-name, next, previous, up
489 @chapter Getting Started
490 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
492 If you got this version of @ccmode{} with Emacs or XEmacs, it should
493 work just fine right out of the box. Note however that you might not
494 have the latest @ccmode{} release and might want to upgrade your copy
497 You should probably start by skimming through the entire chapter
498 @ref{Commands} to get an overview of @ccmode{}'s capabilities.
500 After trying out some commands, you may dislike some aspects of
501 @ccmode{}'s default configuration. Here is an outline of how to
502 change some of the settings that newcomers to @ccmode{} most often
507 This Lisp variable holds an integer, the number of columns @ccmode{}
508 indents nested code. To set this value to 6, customize
509 @code{c-basic-offset} or put this into your @file{.emacs}:
512 (setq c-basic-offset 6)
515 @item The (indentation) style
516 The basic ``shape'' of indentation created by @ccmode{}---by default,
517 this is @code{gnu} style (except for Java and AWK buffers). A list of
518 the available styles and their descriptions can be found in
519 @ref{Built-in Styles}. A complete specification of the @ccmode{}
520 style system, including how to create your own style, can be found in
521 the chapter @ref{Styles}. To set your style to @code{linux}, either
522 customize @code{c-default-style} or put this into your @file{.emacs}:
525 (setq c-default-style '((java-mode . "java")
530 @item Electric Indentation
531 Normally, when you type ``punctuation'' characters such as @samp{;} or
532 @samp{@{}, @ccmode{} instantly reindents the current line. This can
533 be disconcerting until you get used to it. To disable @dfn{electric
534 indentation} in the current buffer, type @kbd{C-c C-l}. Type the same
535 thing to enable it again. To have electric indentation disabled by
536 default, put the following into your @file{.emacs} file@footnote{There
537 is no ``easy customization'' facility for making this change.}:
540 (setq-default c-electric-flag nil)
544 Details of this and other similar ``Minor Modes'' appear in the
545 section @ref{Minor Modes}.
547 @item Making the @key{RET} key indent the new line
548 The standard Emacs binding for @key{RET} just adds a new line. If you
549 want it to reindent the new line as well, rebind the key. Note that
550 the action of rebinding would fail if the pertinent keymap didn't yet
551 exist---we thus need to delay the action until after @ccmode{} has
552 been loaded. Put the following code into your @file{.emacs}:
555 (defun my-make-CR-do-indent ()
556 (define-key c-mode-base-map "\C-m" 'c-context-line-break))
557 (add-hook 'c-initialization-hook 'my-make-CR-do-indent)
561 This example demonstrates the use of a very powerful @ccmode{} (and
562 Emacs) facility, the hook. The use of @ccmode{}'s hooks is described
566 All these settings should occur in your @file{.emacs} @emph{before}
567 any @ccmode{} buffers get loaded---in particular, before any call of
570 As you get to know the mode better, you may want to make more
571 ambitious changes to your configuration. For this, you should start
572 reading the chapter @ref{Config Basics}.
574 If you are upgrading an existing @ccmode{} installation, please see
575 the @file{README} file for installation details. In particular, if
576 you are going to be editing AWK files, @file{README} describes how to
577 configure your (X)Emacs so that @ccmode{} will supersede the obsolete
578 @code{awk-mode.el} which might have been supplied with your (X)Emacs.
579 @ccmode{} might not work with older versions of Emacs or XEmacs. See
580 the @ccmode{} release notes at @uref{http://cc-mode.sourceforge.net}
581 for the latest information on Emacs version and package compatibility
582 (@pxref{Updating CC Mode}).
584 @deffn Command c-version
586 You can find out what version of @ccmode{} you are using by visiting a C
587 file and entering @kbd{M-x c-version RET}. You should see this message in
591 Using CC Mode version 5.XX
595 where @samp{XX} is the minor release number.
598 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
599 @node Commands, Font Locking, Getting Started, Top
600 @comment node-name, next, previous, up
602 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
604 This chapter specifies all of CC Mode's commands, and thus contains
605 nearly everything you need to know to @emph{use} @ccmode{} (as
606 contrasted with configuring it). @dfn{Commands} here means both
607 control key sequences and @dfn{electric keys}, these being characters
608 such as @samp{;} which, as well as inserting themselves into the
609 buffer, also do other things.
611 You might well want to review
613 @ref{Lists,,,@emacsman{}, @emacsmantitle{}},
616 @ref{Moving by Parens,,,@emacsman{}, @emacsmantitle{}},
618 which describes commands for moving around brace and parenthesis
623 * Indentation Commands::
625 * Movement Commands::
626 * Filling and Breaking::
630 * Hungry WS Deletion::
635 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
636 @node Indentation Commands, Comment Commands, Commands, Commands
637 @comment node-name, next, previous,up
638 @section Indentation Commands
640 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
642 The following commands reindent C constructs. Note that when you
643 change your coding style, either interactively or through some other
644 means, your file does @emph{not} automatically get reindented. You
645 will need to execute one of the following commands to see the effects
648 @cindex GNU indent program
649 Also, variables like @code{c-hanging-*} and @code{c-cleanup-list}
650 (@pxref{Custom Auto-newlines}) only affect how on-the-fly code is
651 formatted. Changing the ``hanginess'' of a brace and then
652 reindenting, will not move the brace to a different line. For this,
653 you're better off getting an external program like GNU @code{indent},
654 which will rearrange brace location, amongst other things.
656 Preprocessor directives are handled as syntactic whitespace from other
657 code, i.e. they can be interspersed anywhere without affecting the
658 indentation of the surrounding code, just like comments.
660 The code inside macro definitions is, by default, still analyzed
661 syntactically so that you get relative indentation there just as you'd
662 get if the same code was outside a macro. However, since there is no
663 hint about the syntactic context, i.e. whether the macro expands to an
664 expression, to some statements, or perhaps to whole functions, the
665 syntactic recognition can be wrong. @ccmode{} manages to figure it
666 out correctly most of the time, though.
668 Some macros, when invoked, ''have their own semicolon''. To get the
669 next line indented correctly, rather than as a continuation line,
670 @xref{Macros with ;}.
672 Reindenting large sections of code can take a long time. When
673 @ccmode{} reindents a region of code, it is essentially equivalent to
674 hitting @key{TAB} on every line of the region.
676 These commands indent code:
679 @item @kbd{@key{TAB}} (@code{c-indent-command})
681 @findex c-indent-command
682 @findex indent-command (c-)
683 This command indents the current line. That is all you need to know
684 about it for normal use.
686 @code{c-indent-command} does different things, depending on the
687 setting of @code{c-syntactic-indentation} (@pxref{Indentation Engine
692 When it's non-@code{nil} (which it normally is), the command indents
693 the line according to its syntactic context. With a prefix argument
694 (@kbd{C-u @key{TAB}}), it will re-indent the entire
695 expression@footnote{this is only useful for a line starting with a
696 comment opener or an opening brace, parenthesis, or string quote.}
697 that begins at the line's left margin.
700 When it's @code{nil}, the command indents the line by an extra
701 @code{c-basic-offset} columns. A prefix argument acts as a
702 multiplier. A bare prefix (@kbd{C-u @key{TAB}}) is equivalent to -1,
703 removing @code{c-basic-offset} columns from the indentation.
706 The precise behavior is modified by several variables: With
707 @code{c-tab-always-indent}, you can make @key{TAB} insert whitespace
708 in some circumstances---@code{c-insert-tab-function} then defines
709 precisely what sort of ``whitespace'' this will be. Set the standard
710 Emacs variable @code{indent-tabs-mode} to @code{t} if you want real
711 @samp{tab} characters to be used in the indentation, to @code{nil} if
712 you want only spaces. @xref{Just Spaces,,, @emacsman{},
715 @defopt c-tab-always-indent
716 @vindex tab-always-indent (c-)
718 This variable modifies how @key{TAB} operates.
721 When it is @code{t} (the default), @key{TAB} simply indents the
724 When it is @code{nil}, @key{TAB} (re)indents the line only if point is
725 to the left of the first non-whitespace character on the line.
726 Otherwise it inserts some whitespace (a tab or an equivalent number of
727 spaces - see below) at point.
729 With some other value, the line is reindented. Additionally, if point
730 is within a string or comment, some whitespace is inserted.
734 @defopt c-insert-tab-function
735 @vindex insert-tab-function (c-)
736 @findex tab-to-tab-stop
737 When ``some whitespace'' is inserted as described above, what actually
738 happens is that the function stored in @code{c-insert-tab-function} is
739 called. Normally, this is @code{insert-tab}, which inserts a real tab
740 character or the equivalent number of spaces (depending on
741 @code{indent-tabs-mode}). Some people, however, set
742 @code{c-insert-tab-function} to @code{tab-to-tab-stop} so as to get
743 hard tab stops when indenting.
748 The kind of indentation the next five commands do depends on the
749 setting of @code{c-syntactic-indentation} (@pxref{Indentation Engine
753 when it is non-@code{nil} (the default), the commands indent lines
754 according to their syntactic context;
756 when it is @code{nil}, they just indent each line the same amount as
757 the previous non-blank line. The commands that indent a region aren't
758 very useful in this case.
762 @item @kbd{C-j} (@code{newline-and-indent})
764 @findex newline-and-indent
765 Inserts a newline and indents the new blank line, ready to start
766 typing. This is a standard (X)Emacs command.
768 @item @kbd{C-M-q} (@code{c-indent-exp})
771 @findex indent-exp (c-)
772 Indents an entire balanced brace or parenthesis expression. Note that
773 point must be on the opening brace or parenthesis of the expression
776 @item @kbd{C-c C-q} (@code{c-indent-defun})
778 @findex c-indent-defun
779 @findex indent-defun (c-)
780 Indents the entire top-level function, class or macro definition
781 encompassing point. It leaves point unchanged. This function can't be
782 used to reindent a nested brace construct, such as a nested class or
783 function, or a Java method. The top-level construct being reindented
784 must be complete, i.e. it must have both a beginning brace and an ending
787 @item @kbd{C-M-\} (@code{indent-region})
789 @findex indent-region
790 Indents an arbitrary region of code. This is a standard Emacs command,
791 tailored for C code in a @ccmode{} buffer. Note, of course, that point
792 and mark must delineate the region you want to indent.
794 @item @kbd{C-M-h} (@code{c-mark-function})
796 @findex c-mark-function
797 @findex mark-function (c-)
798 While not strictly an indentation command, this is useful for marking
799 the current top-level function or class definition as the current
800 region. As with @code{c-indent-defun}, this command operates on
801 top-level constructs, and can't be used to mark say, a Java method.
804 These variables are also useful when indenting code:
806 @defopt indent-tabs-mode
807 This is a standard Emacs variable that controls how line indentation
808 is composed. When it's non-@code{nil}, tabs can be used in a line's
809 indentation, otherwise only spaces are used.
812 @defopt c-progress-interval
813 @vindex progress-interval (c-)
814 When indenting large regions of code, this variable controls how often a
815 progress message is displayed. Set this variable to @code{nil} to
816 inhibit the progress messages, or set it to an integer which is how
817 often (in seconds) progress messages are to be displayed.
820 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
821 @node Comment Commands, Movement Commands, Indentation Commands, Commands
822 @comment node-name, next, previous, up
823 @section Comment Commands
824 @cindex comments (insertion of)
825 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
828 @item @kbd{C-c C-c} (@code{comment-region})
830 @findex comment-region
831 This command comments out the lines that start in the region. With a
832 negative argument, it does the opposite - it deletes the comment
833 delimiters from these lines. @xref{Multi-Line Comments,,, emacs, GNU
834 Emacs Manual}, for fuller details. @code{comment-region} isn't
835 actually part of @ccmode{} - it is given a @ccmode{} binding for
838 @item @kbd{M-;} (@code{comment-dwim} or @code{indent-for-comment} @footnote{The name of this command varies between (X)Emacs versions.})
841 @findex indent-for-comment
842 Insert a comment at the end of the current line, if none is there
843 already. Then reindent the comment according to @code{comment-column}
845 (@pxref{Options for Comments,,, emacs, GNU Emacs Manual})
848 (@pxref{Comments,,, xemacs, XEmacs User's Manual})
850 and the variables below. Finally, position the point after the
851 comment starter. @kbd{C-u M-;} kills any comment on the current line,
852 together with any whitespace before it. This is a standard Emacs
853 command, but @ccmode{} enhances it a bit with two variables:
855 @defopt c-indent-comment-alist
856 @vindex indent-comment-alist (c-)
857 @vindex comment-column
858 This style variable allows you to vary the column that @kbd{M-;} puts
859 the comment at, depending on what sort of code is on the line, and
860 possibly the indentation of any similar comment on the preceding line.
861 It is an association list that maps different types of lines to
862 actions describing how they should be handled. If a certain line type
863 isn't present on the list then the line is indented to the column
864 specified by @code{comment-column}.
866 See the documentation string for a full description of this
867 variable (use @kbd{C-h v c-indent-comment-alist}).
870 @defopt c-indent-comments-syntactically-p
871 @vindex indent-comments-syntactically-p (c-)
872 Normally, when this style variable is @code{nil}, @kbd{M-;} will
873 indent comment-only lines according to @code{c-indent-comment-alist},
874 just as it does with lines where other code precede the comments.
875 However, if you want it to act just like @key{TAB} for comment-only
876 lines you can get that by setting
877 @code{c-indent-comments-syntactically-p} to non-@code{nil}.
879 If @code{c-indent-comments-syntactically-p} is non-@code{nil} then
880 @code{c-indent-comment-alist} won't be consulted at all for comment-only
885 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
886 @node Movement Commands, Filling and Breaking, Comment Commands, Commands
887 @comment node-name, next, previous, up
888 @section Movement Commands
890 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
892 @ccmode{} contains some useful commands for moving around in C code.
895 @item @kbd{C-M-a} (@code{c-beginning-of-defun})
896 @itemx @kbd{C-M-e} (@code{c-end-of-defun})
897 @findex c-beginning-of-defun
898 @findex c-end-of-defun
899 @vindex c-defun-tactic
900 @vindex defun-tactic (c-)
902 Move to the beginning or end of the current or next function. Other
903 constructs (such as a structs or classes) which have a brace block
904 also count as ``functions'' here. To move over several functions, you
905 can give these commands a repeat count.
907 The start of a function is at its header. The end of the function is
908 after its closing brace, or after the semicolon of a construct (such
909 as a @code{struct}) which doesn't end at the brace. These two
910 commands try to leave point at the beginning of a line near the actual
911 start or end of the function. This occasionally causes point not to
914 By default, these commands will recognize functions contained within a
915 @dfn{declaration scope} such as a C++ @code{class} or @code{namespace}
916 construct, should the point start inside it. If @ccmode fails to find
917 function beginnings or ends inside the current declaration scope, it
918 will search the enclosing scopes. If you want @ccmode to recognize
919 functions only at the top level@footnote{this was @ccmode{}'s
920 behavior prior to version 5.32.}, set @code{c-defun-tactic} to
923 These functions are analogous to the Emacs built-in commands
924 @code{beginning-of-defun} and @code{end-of-defun}, except they
925 eliminate the constraint that the top-level opening brace of the defun
926 must be in column zero. See @ref{Defuns,,,@emacsman{},
927 @emacsmantitle{}}, for more information.
929 @item @kbd{C-M-a} (AWK Mode) (@code{c-awk-beginning-of-defun})
930 @itemx @kbd{C-M-e} (AWK Mode) (@code{c-awk-end-of-defun})
931 @kindex C-M-a (AWK Mode)
932 @kindex C-M-e (AWK Mode)
933 @findex c-awk-beginning-of-defun
934 @findex awk-beginning-of-defun (c-)
935 @findex c-awk-end-of-defun
936 @findex awk-end-of-defun (c-)
937 Move to the beginning or end of the current or next AWK defun. These
938 commands can take prefix-arguments, their functionality being entirely
939 equivalent to @code{beginning-of-defun} and @code{end-of-defun}.
941 AWK Mode @dfn{defuns} are either pattern/action pairs (either of which
942 might be implicit) or user defined functions. Having the @samp{@{} and
943 @samp{@}} (if there are any) in column zero, as is suggested for some
944 modes, is neither necessary nor helpful in AWK mode.
946 @item @kbd{M-a} (@code{c-beginning-of-statement})
947 @itemx @kbd{M-e} (@code{c-end-of-statement})
950 @findex c-beginning-of-statement
951 @findex c-end-of-statement
952 @findex beginning-of-statement (c-)
953 @findex end-of-statement (c-)
954 Move to the beginning or end of the innermost C statement. If point
955 is already there, move to the next beginning or end of a statement,
956 even if that means moving into a block. (Use @kbd{C-M-b} or
957 @kbd{C-M-f} to move over a balanced block.) A prefix argument @var{n}
958 means move over @var{n} statements.
960 If point is within or next to a comment or a string which spans more
961 than one line, these commands move by sentences instead of statements.
963 When called from a program, these functions take three optional
964 arguments: the repetition count, a buffer position limit which is the
965 farthest back to search for the syntactic context, and a flag saying
966 whether to do sentence motion in or near comments and multiline
969 @item @kbd{C-c C-u} (@code{c-up-conditional})
971 @findex c-up-conditional
972 @findex up-conditional (c-)
973 Move back to the containing preprocessor conditional, leaving the mark
974 behind. A prefix argument acts as a repeat count. With a negative
975 argument, move forward to the end of the containing preprocessor
978 @samp{#elif} is treated like @samp{#else} followed by @samp{#if}, so the
979 function stops at them when going backward, but not when going
982 This key sequence is not bound in AWK Mode, which doesn't have
983 preprocessor statements.
985 @item @kbd{M-x c-up-conditional-with-else}
986 @findex c-up-conditional-with-else
987 @findex up-conditional-with-else (c-)
988 A variety of @code{c-up-conditional} that also stops at @samp{#else}
989 lines. Normally those lines are ignored.
991 @item @kbd{M-x c-down-conditional}
992 @findex c-down-conditional
993 @findex down-conditional (c-)
994 Move forward into the next nested preprocessor conditional, leaving
995 the mark behind. A prefix argument acts as a repeat count. With a
996 negative argument, move backward into the previous nested preprocessor
999 @samp{#elif} is treated like @samp{#else} followed by @samp{#if}, so the
1000 function stops at them when going forward, but not when going backward.
1002 @item @kbd{M-x c-down-conditional-with-else}
1003 @findex c-down-conditional-with-else
1004 @findex down-conditional-with-else (c-)
1005 A variety of @code{c-down-conditional} that also stops at @samp{#else}
1006 lines. Normally those lines are ignored.
1008 @item @kbd{C-c C-p} (@code{c-backward-conditional})
1009 @itemx @kbd{C-c C-n} (@code{c-forward-conditional})
1012 @findex c-backward-conditional
1013 @findex c-forward-conditional
1014 @findex backward-conditional (c-)
1015 @findex forward-conditional (c-)
1016 Move backward or forward across a preprocessor conditional, leaving
1017 the mark behind. A prefix argument acts as a repeat count. With a
1018 negative argument, move in the opposite direction.
1020 These key sequences are not bound in AWK Mode, which doesn't have
1021 preprocessor statements.
1023 @item @kbd{M-x c-backward-into-nomenclature}
1024 @itemx @kbd{M-x c-forward-into-nomenclature}
1025 @findex c-backward-into-nomenclature
1026 @findex c-forward-into-nomenclature
1027 @findex backward-into-nomenclature (c-)
1028 @findex forward-into-nomenclature (c-)
1029 A popular programming style, especially for object-oriented languages
1030 such as C++ is to write symbols in a mixed case format, where the
1031 first letter of each word is capitalized, and not separated by
1032 underscores. E.g. @samp{SymbolsWithMixedCaseAndNoUnderlines}.
1034 These commands move backward or forward to the beginning of the next
1035 capitalized word. With prefix argument @var{n}, move @var{n} times.
1036 If @var{n} is negative, move in the opposite direction.
1038 Note that these two commands have been superseded by
1039 @code{c-subword-mode}, which you should use instead. @xref{Subword
1040 Movement}. They might be removed from a future release of @ccmode{}.
1043 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1044 @node Filling and Breaking, Minor Modes, Movement Commands, Commands
1045 @comment node-name, next, previous, up
1046 @section Filling and Line Breaking Commands
1047 @cindex text filling
1048 @cindex line breaking
1049 @cindex comment handling
1050 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1052 Since there's a lot of normal text in comments and string literals,
1053 @ccmode{} provides features to edit these like in text mode. The goal
1054 is to do it seamlessly, i.e. you can use auto fill mode, sentence and
1055 paragraph movement, paragraph filling, adaptive filling etc. wherever
1056 there's a piece of normal text without having to think much about it.
1057 @ccmode{} keeps the indentation, fixes suitable comment line prefixes,
1060 You can configure the exact way comments get filled and broken, and
1061 where Emacs does auto-filling (see @pxref{Custom Filling and
1062 Breaking}). Typically, the style system (@pxref{Styles}) will have
1063 set this up for you, so you probably won't have to bother.
1065 @findex auto-fill-mode
1066 @cindex Auto Fill mode
1067 @cindex paragraph filling
1068 Line breaks are by default handled (almost) the same regardless of
1069 whether they are made by auto fill mode (@pxref{Auto Fill,,,
1070 @emacsman{}, @emacsmantitle{}}), by paragraph filling (e.g. with
1071 @kbd{M-q}), or explicitly with @kbd{M-j} or similar methods. In
1072 string literals, the new line gets the same indentation as the
1073 previous nonempty line.@footnote{You can change this default by
1074 setting the @code{string} syntactic symbol (@pxref{Syntactic Symbols}
1075 and @pxref{Customizing Indentation})}.
1078 @item @kbd{M-q} (@code{c-fill-paragraph})
1080 @findex c-fill-paragraph
1081 @findex fill-paragraph (c-)
1082 @cindex Javadoc markup
1083 @cindex Pike autodoc markup
1084 This command fills multiline string literals and both block
1085 and line style comments. In Java buffers, the Javadoc markup words
1086 are recognized as paragraph starters. The line oriented Pike autodoc
1087 markup words are recognized in the same way in Pike mode.
1089 The formatting of the starters (@code{/*}) and enders (@code{*/}) of
1090 block comments are kept as they were before the filling. I.e., if
1091 either the starter or ender were on a line of its own, then it stays
1092 on its own line; conversely, if the delimiter has comment text on its
1093 line, it keeps at least one word of that text with it on the line.
1095 This command is the replacement for @code{fill-paragraph} in @ccmode{}
1098 @item @kbd{M-j} (@code{c-indent-new-comment-line})
1100 @findex c-indent-new-comment-line
1101 @findex indent-new-comment-line (c-)
1102 This breaks the current line at point and indents the new line. If
1103 point was in a comment, the new line gets the proper comment line
1104 prefix. If point was inside a macro, a backslash is inserted before
1105 the line break. It is the replacement for
1106 @code{indent-new-comment-line}.
1108 @item @kbd{M-x c-context-line-break}
1109 @findex c-context-line-break
1110 @findex context-line-break (c-)
1111 Insert a line break suitable to the context: If the point is inside a
1112 comment, the new line gets the suitable indentation and comment line
1113 prefix like @code{c-indent-new-comment-line}. In normal code it's
1114 indented like @code{newline-and-indent} would do. In macros it acts
1115 like @code{newline-and-indent} but additionally inserts and optionally
1116 aligns the line ending backslash so that the macro remains unbroken.
1117 @xref{Custom Macros}, for details about the backslash alignment. In a
1118 string, a backslash is inserted only if the string is within a
1119 macro@footnote{In GCC, unescaped line breaks within strings are
1122 This function is not bound to a key by default, but it's intended to be
1123 used on the @kbd{RET} key. If you like the behavior of
1124 @code{newline-and-indent} on @kbd{RET}, you should consider switching to
1125 this function. @xref{Sample .emacs File}.
1127 @item @kbd{M-x c-context-open-line}
1128 @findex c-context-open-line
1129 @findex context-open-line (c-)
1130 This is to @kbd{C-o} (@kbd{M-x open-line}) as
1131 @code{c-context-line-break} is to @kbd{RET}. I.e. it works just like
1132 @code{c-context-line-break} but leaves the point before the inserted
1137 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1138 @node Minor Modes, Electric Keys, Filling and Breaking, Commands
1139 @comment node-name, next, previous, up
1140 @section Minor Modes
1142 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1144 @ccmode{} contains several minor-mode-like features that you might
1145 find useful while writing new code or editing old code:
1149 When this is enabled, certain visible characters cause reformatting as
1150 they are typed. This is normally helpful, but can be a nuisance when
1151 editing chaotically formatted code. It can also be disconcerting,
1152 especially for users who are new to @ccmode{}.
1153 @item auto-newline mode
1154 This automatically inserts newlines where you'd probably want to type
1155 them yourself, e.g. after typing @samp{@}}s. Its action is suppressed
1156 when electric mode is disabled.
1157 @item hungry-delete mode
1158 This lets you delete a contiguous block of whitespace with a single
1159 key - for example, the newline and indentation just inserted by
1160 auto-newline when you want to back up and write a comment after the
1163 This mode makes basic word movement commands like @kbd{M-f}
1164 (@code{forward-word}) and @kbd{M-b} (@code{backward-word}) treat the
1165 parts of sillycapsed symbols as different words.
1166 E.g. @samp{NSGraphicsContext} is treated as three words @samp{NS},
1167 @samp{Graphics}, and @samp{Context}.
1168 @item syntactic-indentation mode
1169 When this is enabled (which it normally is), indentation commands such
1170 as @kbd{C-j} indent lines of code according to their syntactic
1171 structure. Otherwise, a line is simply indented to the same level as
1172 the previous one and @kbd{@key{TAB}} adjusts the indentation in steps
1173 of `c-basic-offset'.
1176 Full details on how these minor modes work are at @ref{Electric Keys},
1177 @ref{Auto-newlines}, @ref{Hungry WS Deletion}, @ref{Subword Movement},
1178 and @ref{Indentation Engine Basics}.
1180 You can toggle each of these minor modes on and off, and you can
1181 configure @ccmode{} so that it starts up with your favorite
1182 combination of them (@pxref{Sample .emacs File}). By default, when
1183 you initialize a buffer, electric mode and syntactic-indentation mode
1184 are enabled but the other two modes are disabled.
1186 @ccmode{} displays the current state of the first four of these minor
1187 modes on the mode line by appending letters to the major mode's name,
1188 one letter for each enabled minor mode - @samp{l} for electric mode,
1189 @samp{a} for auto-newline mode, @samp{h} for hungry delete mode, and
1190 @samp{w} for subword mode. If all these modes were enabled, you'd see
1191 @samp{C/lahw}@footnote{The @samp{C} would be replaced with the name of
1192 the language in question for the other languages @ccmode{} supports.}.
1194 Here are the commands to toggle these modes:
1197 @item @kbd{C-c C-l} (@code{c-toggle-electric-state})
1199 @findex c-toggle-electric-state
1200 @findex toggle-electric-state (c-)
1201 Toggle electric minor mode. When the command turns the mode off, it
1202 also suppresses auto-newline mode.
1204 @item @kbd{C-c C-a} (@code{c-toggle-auto-newline})
1206 @findex c-toggle-auto-newline
1207 @findex toggle-auto-newline (c-)
1208 Toggle auto-newline minor mode. When the command turns the mode on,
1209 it also enables electric minor mode.
1211 @item @kbd{M-x c-toggle-hungry-state}@footnote{Prior to @ccmode{} 5.31, this command was bound to @kbd{C-c C-d}.}
1212 @findex c-toggle-hungry-state
1213 @findex toggle-hungry-state (c-)
1214 Toggle hungry-delete minor mode.
1216 @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}.}
1217 @findex c-toggle-auto-hungry-state
1218 @findex toggle-auto-hungry-state (c-)
1219 Toggle both auto-newline and hungry delete minor modes.
1221 @item @kbd{C-c C-w} (@code{M-x c-subword-mode})
1223 @findex c-subword-mode
1224 @findex subword-mode (c-)
1225 Toggle subword mode.
1227 @item @kbd{M-x c-toggle-syntactic-indentation}
1228 @findex c-toggle-syntactic-indentation
1229 @findex toggle-syntactic-indentation (c-)
1230 Toggle syntactic-indentation mode.
1233 Common to all the toggle functions above is that if they are called
1234 programmatically, they take an optional numerical argument. A
1235 positive value will turn on the minor mode (or both of them in the
1236 case of @code{c-toggle-auto-hungry-state}) and a negative value will
1237 turn it (or them) off.
1240 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1241 @node Electric Keys, Auto-newlines, Minor Modes, Commands
1242 @comment node-name, next, previous, up
1243 @section Electric Keys and Keywords
1244 @cindex electric characters
1245 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1247 Most punctuation keys provide @dfn{electric} behavior - as well as
1248 inserting themselves they perform some other action, such as
1249 reindenting the line. This reindentation saves you from having to
1250 reindent a line manually after typing, say, a @samp{@}}. A few
1251 keywords, such as @code{else}, also trigger electric action.
1253 You can inhibit the electric behavior described here by disabling
1254 electric minor mode (@pxref{Minor Modes}).
1256 Common to all these keys is that they only behave electrically when
1257 used in normal code (as contrasted with getting typed in a string
1258 literal or comment). Those which cause re-indentation do so only when
1259 @code{c-syntactic-indentation} has a non-@code{nil} value (which it
1262 These keys and keywords are:
1263 @c ACM, 2004/8/24: c-electric-pound doesn't check c-s-i: this is more
1264 @c like a bug in the code than a bug in this document. It'll get
1265 @c fixed in the code sometime.
1270 @findex c-electric-pound
1271 @findex electric-pound (c-)
1272 @vindex c-electric-pound-behavior
1273 @vindex electric-pound-behavior (c-)
1274 Pound (bound to @code{c-electric-pound}) is electric when typed as the
1275 first non-whitespace character on a line and not within a macro
1276 definition. In this case, the variable @code{c-electric-pound-behavior}
1277 is consulted for the electric behavior. This variable takes a list
1278 value, although the only element currently defined is @code{alignleft},
1279 which tells this command to force the @samp{#} character into column
1280 zero. This is useful for entering preprocessor macro definitions.
1282 Pound is not electric in AWK buffers, where @samp{#} starts a comment,
1283 and is bound to @code{self-insert-command} like any typical printable
1285 @c ACM, 2004/8/24: Change this (and the code) to do AWK comment
1292 @findex c-electric-star
1293 @findex electric-star (c-)
1294 @findex c-electric-slash
1295 @findex electric-slash (c-)
1296 A star (bound to @code{c-electric-star}) or a slash
1297 (@code{c-electric-slash}) causes reindentation when you type it as the
1298 second component of a C style block comment opener (@samp{/*}) or a
1299 C++ line comment opener (@samp{//}) respectively, but only if the
1300 comment opener is the first thing on the line (i.e. there's only
1301 whitespace before it).
1303 Additionally, you can configure @ccmode{} so that typing a slash at
1304 the start of a line within a block comment will terminate the
1305 comment. You don't need to have electric minor mode enabled to get
1306 this behavior. @xref{Clean-ups}.
1308 In AWK mode, @samp{*} and @samp{/} do not delimit comments and are not
1315 @findex c-electric-lt-gt
1316 @findex electric-lt-gt (c-)
1317 A less-than or greater-than sign (bound to @code{c-electric-lt-gt}) is
1318 electric in two circumstances: when it is an angle bracket in a C++
1319 @samp{template} declaration (and similar constructs in other
1320 languages) and when it is the second of two @kbd{<} or @kbd{>}
1321 characters in a C++ style stream operator. In either case, the line
1322 is reindented. Angle brackets in C @samp{#include} directives are not
1329 @findex c-electric-paren
1330 @findex electric-paren (c-)
1331 The normal parenthesis characters @samp{(} and @samp{)} (bound to
1332 @code{c-electric-paren}) reindent the current line. This is useful
1333 for getting the closing parenthesis of an argument list aligned
1336 You can also configure @ccmode{} to insert a space automatically
1337 between a function name and the @samp{(} you've just typed, and to
1338 remove it automatically after typing @samp{)}, should the argument
1339 list be empty. You don't need to have electric minor mode enabled to
1340 get these actions. @xref{Clean-ups}.
1346 @findex c-electric-brace
1347 @findex electric-brace (c-)
1348 Typing a brace (bound to @code{c-electric-brace}) reindents the
1349 current line. Also, one or more newlines might be inserted if
1350 auto-newline minor mode is enabled. @xref{Auto-newlines}.
1351 Additionally, you can configure @ccmode{} to compact excess whitespace
1352 inserted by auto-newline mode in certain circumstances.
1357 @findex c-electric-colon
1358 @findex electric-colon (c-)
1359 Typing a colon (bound to @code{c-electric-colon}) reindents the
1360 current line. Additionally, one or more newlines might be inserted if
1361 auto-newline minor mode is enabled. @xref{Auto-newlines}. If you
1362 type a second colon immediately after such an auto-newline, by default
1363 the whitespace between the two colons is removed, leaving a C++ scope
1364 operator. @xref{Clean-ups}.
1366 If you prefer, you can insert @samp{::} in a single operation,
1367 avoiding all these spurious reindentations, newlines, and clean-ups.
1368 @xref{Other Commands}.
1374 @findex c-electric-semi&comma
1375 @findex electric-semi&comma (c-)
1376 Typing a semicolon or comma (bound to @code{c-electric-semi&comma})
1377 reindents the current line. Also, a newline might be inserted if
1378 auto-newline minor mode is enabled. @xref{Auto-newlines}.
1379 Additionally, you can configure @ccmode{} so that when auto-newline
1380 has inserted whitespace after a @samp{@}}, it will be removed again
1381 when you type a semicolon or comma just after it. @xref{Clean-ups}.
1385 @deffn Command c-electric-continued-statement
1386 @findex electric-continued-statement (c-)
1388 Certain keywords are electric, causing reindentation when they are
1389 preceded only by whitespace on the line. The keywords are those that
1390 continue an earlier statement instead of starting a new one:
1391 @code{else}, @code{while}, @code{catch} (only in C++ and Java) and
1392 @code{finally} (only in Java).
1398 for (i = 0; i < 17; i++)
1400 res += a[i]->offset;
1405 Here, the @code{else} should be indented like the preceding @code{if},
1406 since it continues that statement. @ccmode{} will automatically
1407 reindent it after the @code{else} has been typed in full, since only
1408 then is it possible to decide whether it's a new statement or a
1409 continuation of the preceding @code{if}.
1414 @ccmode{} uses Abbrev mode (@pxref{Abbrevs,,, @emacsman{}, @emacsmantitle{}})
1415 to accomplish this. It's therefore turned on by default in all language
1416 modes except IDL mode, since CORBA IDL doesn't have any statements.
1420 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1421 @node Auto-newlines, Hungry WS Deletion, Electric Keys, Commands
1422 @comment node-name, next, previous, up
1423 @section Auto-newline Insertion
1424 @cindex auto-newline
1425 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1427 When you have @dfn{Auto-newline minor mode} enabled (@pxref{Minor
1428 Modes}), @ccmode{} inserts newlines for you automatically (in certain
1429 syntactic contexts) when you type a left or right brace, a colon, a
1430 semicolon, or a comma. Sometimes a newline appears before the
1431 character you type, sometimes after it, sometimes both.
1433 Auto-newline only triggers when the following conditions hold:
1437 Auto-newline minor mode is enabled, as evidenced by the indicator
1438 @samp{a} after the mode name on the mode line (e.g. @samp{C/a} or
1442 The character was typed at the end of a line, or with only whitespace
1443 after it, and possibly a @samp{\} escaping the newline.
1446 The character is not on its own line already. (This applies only to
1447 insertion of a newline @emph{before} the character.)
1451 @cindex syntactic whitespace
1452 The character was not typed inside of a literal @footnote{A
1453 @dfn{literal} is defined as any comment, string, or preprocessor macro
1454 definition. These constructs are also known as @dfn{syntactic
1455 whitespace} since they are usually ignored when scanning C code.}.
1458 No numeric argument was supplied to the command (i.e. it was typed as
1459 normal, with no @kbd{C-u} prefix).
1462 You can configure the precise circumstances in which newlines get
1463 inserted (see @pxref{Custom Auto-newlines}). Typically, the style
1464 system (@pxref{Styles}) will have set this up for you, so you probably
1465 won't have to bother.
1467 Sometimes @ccmode{} inserts an auto-newline where you don't want one,
1468 such as after a @samp{@}} when you're about to type a @samp{;}.
1469 Hungry deletion can help here (@pxref{Hungry WS Deletion}), or you can
1470 activate an appropriate @dfn{clean-up}, which will remove the excess
1471 whitespace after you've typed the @samp{;}. See @ref{Clean-ups} for a
1472 full description. See also @ref{Electric Keys} for a summary of
1473 clean-ups listed by key.
1476 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1477 @node Hungry WS Deletion, Subword Movement, Auto-newlines, Commands
1478 @comment node-name, next, previous, up
1479 @section Hungry Deletion of Whitespace
1480 @cindex hungry-deletion
1481 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1483 If you want to delete an entire block of whitespace at point, you can
1484 use @dfn{hungry deletion}. This deletes all the contiguous whitespace
1485 either before point or after point in a single operation.
1486 ``Whitespace'' here includes tabs and newlines, but not comments or
1487 preprocessor commands. Hungry deletion can markedly cut down on the
1488 number of times you have to hit deletion keys when, for example,
1489 you've made a mistake on the preceding line and have already pressed
1492 Hungry deletion is a simple feature that some people find extremely
1493 useful. In fact, you might find yourself wanting it in @strong{all}
1496 Loosely speaking, in what follows, @dfn{@key{DEL}} means ``the
1497 backspace key'' and @dfn{@key{DELETE}} means ``the forward delete
1498 key''. This is discussed in more detail below.
1500 There are two different ways you can use hungry deletion:
1503 @item Using @dfn{Hungry Delete Mode} with @kbd{@key{DEL}} and @kbd{C-d}
1504 Here you toggle Hungry Delete minor mode with @kbd{M-x
1505 c-toggle-hungry-state}@footnote{Prior to @ccmode{} 5.31, this command
1506 was bound to @kbd{C-c C-d}. @kbd{C-c C-d} is now the default binding
1507 for @code{c-hungry-delete-forward}.} (@pxref{Minor Modes}.) This
1508 makes @kbd{@key{DEL}} and @kbd{C-d} do backwards and forward hungry
1512 @item @kbd{@key{DEL}} (@code{c-electric-backspace})
1514 @findex c-electric-backspace
1515 @findex electric-backspace (c-)
1516 This command is run by default when you hit the @kbd{DEL} key. When
1517 hungry delete mode is enabled, it deletes any amount of whitespace in
1518 the backwards direction. Otherwise, or when used with a prefix
1519 argument or in a literal (@pxref{Auto-newlines}), the command just
1520 deletes backwards in the usual way. (More precisely, it calls the
1521 function contained in the variable @code{c-backspace-function},
1522 passing it the prefix argument, if any.)
1524 @item @code{c-backspace-function}
1525 @vindex c-backspace-function
1526 @vindex backspace-function (c-)
1527 @findex backward-delete-char-untabify
1528 Hook that gets called by @code{c-electric-backspace} when it doesn't
1529 do an ``electric'' deletion of the preceding whitespace. The default
1530 value is @code{backward-delete-char-untabify}
1531 (@pxref{Deletion,,,@lispref{}, @lispreftitle{}}, the function which
1532 deletes a single character.
1534 @item @kbd{C-d} (@code{c-electric-delete-forward})
1536 @findex c-electric-delete-forward
1537 @findex electric-delete-forward (c-)
1538 This function, which is bound to @kbd{C-d} by default, works just like
1539 @code{c-electric-backspace} but in the forward direction. When it
1540 doesn't do an ``electric'' deletion of the following whitespace, it
1541 just does @code{delete-char}, more or less. (Strictly speaking, it
1542 calls the function in @code{c-delete-function} with the prefix
1545 @item @code{c-delete-function}
1546 @vindex c-delete-function
1547 @vindex delete-function (c-)
1549 Hook that gets called by @code{c-electric-delete-forward} when it
1550 doesn't do an ``electric'' deletion of the following whitespace. The
1551 default value is @code{delete-char}.
1554 @item Using Distinct Bindings
1555 The other (newer and recommended) way to use hungry deletion is to
1556 perform @code{c-hungry-delete-backwards} and
1557 @code{c-hungry-delete-forward} directly through their key sequences
1558 rather than using the minor mode toggling.
1561 @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}.}
1562 @kindex C-c C-<backspace>
1563 @kindex C-c <backspace>
1566 @findex c-hungry-delete-backwards
1567 @findex hungry-delete-backwards (c-)
1568 Delete any amount of whitespace in the backwards direction (regardless
1569 whether hungry-delete mode is enabled or not). This command is bound
1570 to both @kbd{C-c C-@key{DEL}} and @kbd{C-c @key{DEL}}, since the more
1571 natural one, @kbd{C-c C-@key{DEL}}, is sometimes difficult to type at
1572 a character terminal.
1574 @item @kbd{C-c C-d}, @kbd{C-c C-@key{DELETE}}, or @kbd{C-c @key{DELETE}} (@code{c-hungry-delete-forward})
1576 @kindex C-c C-<DELETE>
1577 @kindex C-c <DELETE>
1578 @findex c-hungry-delete-forward
1579 @findex hungry-delete-forward (c-)
1580 Delete any amount of whitespace in the forward direction (regardless
1581 whether hungry-delete mode is enabled or not). This command is bound
1582 to both @kbd{C-c C-@key{DELETE}} and @kbd{C-c @key{DELETE}} for the
1583 same reason as for @key{DEL} above.
1590 When we talk about @kbd{@key{DEL}}, and @kbd{@key{DELETE}} above, we
1591 actually do so without connecting them to the physical keys commonly
1592 known as @key{Backspace} and @key{Delete}. The default bindings to
1593 those two keys depends on the flavor of (X)Emacs you are using.
1595 @findex c-electric-delete
1596 @findex electric-delete (c-)
1597 @findex c-hungry-delete
1598 @findex hungry-delete (c-)
1599 @vindex delete-key-deletes-forward
1600 In XEmacs 20.3 and beyond, the @key{Backspace} key is bound to
1601 @code{c-electric-backspace} and the @key{Delete} key is bound to
1602 @code{c-electric-delete}. You control the direction it deletes in by
1603 setting the variable @code{delete-key-deletes-forward}, a standard
1605 @c This variable is encapsulated by XEmacs's (defsubst delete-forward-p ...).
1606 When this variable is non-@code{nil}, @code{c-electric-delete} will do
1607 forward deletion with @code{c-electric-delete-forward}, otherwise it
1608 does backward deletion with @code{c-electric-backspace}. Similarly,
1609 @kbd{C-c @key{Delete}} and @kbd{C-c C-@key{Delete}} are bound to
1610 @code{c-hungry-delete} which is controlled in the same way by
1611 @code{delete-key-deletes-forward}.
1613 @findex normal-erase-is-backspace-mode
1615 Emacs 21 and later automatically binds @key{Backspace} and
1616 @key{Delete} to @kbd{DEL} and @kbd{C-d} according to your environment,
1617 and @ccmode{} extends those bindings to @kbd{C-c C-@key{Backspace}}
1618 etc. If you need to change the bindings through
1619 @code{normal-erase-is-backspace-mode} then @ccmode{} will also adapt
1620 its extended bindings accordingly.
1622 In earlier (X)Emacs versions, @ccmode{} doesn't bind either
1623 @key{Backspace} or @key{Delete} directly. Only the key codes
1624 @kbd{DEL} and @kbd{C-d} are bound, and it's up to the default bindings
1625 to map the physical keys to them. You might need to modify this
1626 yourself if the defaults are unsuitable.
1628 Getting your @key{Backspace} and @key{Delete} keys properly set up can
1629 sometimes be tricky. The information in @ref{DEL Does Not
1630 Delete,,,emacs, GNU Emacs Manual}, might be helpful if you're having
1631 trouble with this in GNU Emacs.
1634 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1635 @node Subword Movement, Other Commands, Hungry WS Deletion, Commands
1636 @comment node-name, next, previous, up
1637 @section Subword Movement and Editing
1638 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1640 @cindex nomenclature
1642 In spite of the GNU Coding Standards, it is popular to name a symbol
1643 by mixing uppercase and lowercase letters, e.g. @samp{GtkWidget},
1644 @samp{EmacsFrameClass}, or @samp{NSGraphicsContext}. Here we call
1645 these mixed case symbols @dfn{nomenclatures}. Also, each capitalized
1646 (or completely uppercase) part of a nomenclature is called a
1647 @dfn{subword}. Here are some examples:
1649 @multitable {@samp{NSGraphicsContext}} {@samp{NS}, @samp{Graphics}, and @samp{Context}}
1650 @headitem Nomenclature
1652 @item @samp{GtkWindow}
1653 @tab @samp{Gtk} and @samp{Window}
1654 @item @samp{EmacsFrameClass}
1655 @tab @samp{Emacs}, @samp{Frame}, and @samp{Class}
1656 @item @samp{NSGraphicsContext}
1657 @tab @samp{NS}, @samp{Graphics}, and @samp{Context}
1660 The subword minor mode replaces the basic word oriented movement and
1661 editing commands with variants that recognize subwords in a
1662 nomenclature and treat them as separate words:
1664 @findex c-forward-subword
1665 @findex forward-subword (c-)
1666 @findex c-backward-subword
1667 @findex backward-subword (c-)
1668 @findex c-mark-subword
1669 @findex mark-subword (c-)
1670 @findex c-kill-subword
1671 @findex kill-subword (c-)
1672 @findex c-backward-kill-subword
1673 @findex backward-kill-subword (c-)
1674 @findex c-transpose-subwords
1675 @findex transpose-subwords (c-)
1676 @findex c-capitalize-subword
1677 @findex capitalize-subword (c-)
1678 @findex c-upcase-subword
1679 @findex upcase-subword (c-)
1680 @findex c-downcase-subword
1681 @findex downcase-subword (c-)
1682 @multitable @columnfractions .20 .40 .40
1683 @headitem Key @tab Word oriented command @tab Subword oriented command
1684 @item @kbd{M-f} @tab @code{forward-word} @tab @code{c-forward-subword}
1685 @item @kbd{M-b} @tab @code{backward-word} @tab @code{c-backward-subword}
1686 @item @kbd{M-@@} @tab @code{mark-word} @tab @code{c-mark-subword}
1687 @item @kbd{M-d} @tab @code{kill-word} @tab @code{c-kill-subword}
1688 @item @kbd{M-DEL} @tab @code{backward-kill-word} @tab @code{c-backward-kill-subword}
1689 @item @kbd{M-t} @tab @code{transpose-words} @tab @code{c-transpose-subwords}
1690 @item @kbd{M-c} @tab @code{capitalize-word} @tab @code{c-capitalize-subword}
1691 @item @kbd{M-u} @tab @code{upcase-word} @tab @code{c-upcase-subword}
1692 @item @kbd{M-l} @tab @code{downcase-word} @tab @code{c-downcase-subword}
1695 Note that if you have changed the key bindings for the word oriented
1696 commands in your @file{.emacs} or a similar place, the keys you have
1697 configured are also used for the corresponding subword oriented
1700 Type @kbd{C-c C-w} to toggle subword mode on and off. To make the
1701 mode turn on automatically, put the following code in your
1705 (add-hook 'c-mode-common-hook
1706 (lambda () (c-subword-mode 1)))
1709 As a bonus, you can also use @code{c-subword-mode} in non-@ccmode{}
1710 buffers by typing @kbd{M-x c-subword-mode}.
1712 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1713 @node Other Commands, , Subword Movement, Commands
1714 @comment node-name, next, previous, up
1715 @section Other Commands
1716 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1718 Here are the various other commands that didn't fit anywhere else:
1721 @item @kbd{C-c .} (@code{c-set-style})
1724 @findex set-style (c-)
1725 Switch to the specified style in the current buffer. Use like this:
1728 @kbd{C-c . @var{style-name} @key{RET}}
1731 You can use the @key{TAB} in the normal way to do completion on the
1732 style name. Note that all style names are case insensitive, even the
1733 ones you define yourself.
1735 Setting a style in this way does @emph{not} automatically reindent your
1736 file. For commands that you can use to view the effect of your changes,
1737 see @ref{Indentation Commands} and @ref{Filling and Breaking}.
1739 For details of the @ccmode{} style system, see @ref{Styles}.
1740 @item @kbd{C-c :} (@code{c-scope-operator})
1742 @findex c-scope-operator
1743 @findex scope-operator (c-)
1744 In C++, it is also sometimes desirable to insert the double-colon scope
1745 operator without performing the electric behavior of colon insertion.
1746 @kbd{C-c :} does just this.
1748 @item @kbd{C-c C-\} (@code{c-backslash-region})
1750 @findex c-backslash-region
1751 @findex backslash-region (c-)
1752 This function inserts and aligns or deletes end-of-line backslashes in
1753 the current region. These are typically used in multi-line macros.
1755 With no prefix argument, it inserts any missing backslashes and aligns
1756 them according to the @code{c-backslash-column} and
1757 @code{c-backslash-max-column} variables. With a prefix argument, it
1758 deletes any backslashes.
1760 The function does not modify blank lines at the start of the region. If
1761 the region ends at the start of a line, it always deletes the backslash
1762 (if any) at the end of the previous line.
1764 To customize the precise workings of this command, @ref{Custom Macros}.
1768 The recommended line breaking function, @code{c-context-line-break}
1769 (@pxref{Filling and Breaking}), is especially nice if you edit
1770 multiline macros frequently. When used inside a macro, it
1771 automatically inserts and adjusts the mandatory backslash at the end
1772 of the line to keep the macro together, and it leaves the point at the
1773 right indentation column for the code. Thus you can write code inside
1774 macros almost exactly as you can elsewhere, without having to bother
1775 with the trailing backslashes.
1778 @item @kbd{C-c C-e} (@code{c-macro-expand})
1780 @findex c-macro-expand
1781 @findex macro-expand (c-)
1782 This command expands C, C++, Objective C or Pike macros in the region,
1783 using an appropriate external preprocessor program. Normally it
1784 displays its output in a temporary buffer, but if you give it a prefix
1785 arg (with @kbd{C-u C-c C-e}) it will overwrite the original region
1788 The command does not work in any of the other modes, and the key
1789 sequence is not bound in these other modes.
1791 @code{c-macro-expand} isn't actually part of @ccmode{}, even though it
1792 is bound to a @ccmode{} key sequence. If you need help setting it up
1793 or have other problems with it, you can either read its source code or
1794 ask for help in the standard (X)Emacs forums.
1797 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1798 @node Font Locking, Config Basics, Commands, Top
1799 @comment node-name, next, previous, up
1800 @chapter Font Locking
1801 @cindex font locking
1802 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1804 @cindex Font Lock mode
1806 @ccmode{} provides font locking for its supported languages by
1807 supplying patterns for use with Font Lock mode. This means that you
1808 get distinct faces on the various syntactic parts such as comments,
1809 strings, keywords and types, which is very helpful in telling them
1810 apart at a glance and discovering syntactic errors. @xref{Font
1811 Lock,,, emacs, GNU Emacs Manual}, for ways to enable font locking in
1814 @strong{Please note:} The font locking in AWK mode is currently not
1815 integrated with the rest of @ccmode{}. Only the last section of this
1816 chapter, @ref{AWK Mode Font Locking}, applies to AWK. The other
1817 sections apply to the other languages.
1820 * Font Locking Preliminaries::
1823 * AWK Mode Font Locking::
1827 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1828 @node Font Locking Preliminaries, Faces, Font Locking, Font Locking
1829 @comment node-name, next, previous, up
1830 @section Font Locking Preliminaries
1831 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1833 The font locking for most of the @ccmode{} languages were provided
1834 directly by the Font Lock package prior to version 5.30 of @ccmode{}.
1835 In the transition to @ccmode{} the patterns have been reworked
1836 completely and are applied uniformly across all the languages except AWK
1837 mode, just like the indentation rules (although each language still has
1838 some peculiarities of its own, of course). Since the languages
1839 previously had completely separate font locking patterns, this means
1840 that it's a bit different in most languages now.
1842 The main goal for the font locking in @ccmode{} is accuracy, to provide
1843 a dependable aid in recognizing the various constructs. Some, like
1844 strings and comments, are easy to recognize while others, like
1845 declarations and types, can be very tricky. @ccmode{} can go to great
1846 lengths to recognize declarations and casts correctly, especially when
1847 the types aren't recognized by standard patterns. This is a fairly
1848 demanding analysis which can be slow on older hardware, and it can
1849 therefore be disabled by choosing a lower decoration level with the
1850 variable @code{font-lock-maximum-decoration} (@pxref{Font Lock,,,
1851 emacs, GNU Emacs Manual}).
1853 @vindex font-lock-maximum-decoration
1855 The decoration levels are used as follows:
1860 Minimal font locking: Fontify only comments, strings and preprocessor
1861 directives (in the languages that use cpp).
1865 Fast font locking: In addition to level 1, fontify keywords, simple
1866 types and declarations that are easy to recognize. The variables
1867 @code{*-font-lock-extra-types} (where @samp{*} is the name of the
1868 language) are used to recognize types (see below). Documentation
1869 comments like Javadoc are fontified according to
1870 @code{c-doc-comment-style} (@pxref{Doc Comments}).
1872 Use this if you think the font locking is too slow. It's the closest
1873 corresponding level to level 3 in the old font lock patterns.
1877 Accurate font locking: Like level 2 but uses a different approach that
1878 can recognize types and declarations much more accurately. The
1879 @code{*-font-lock-extra-types} variables are still used, but user
1880 defined types are recognized correctly anyway in most cases. Therefore
1881 those variables should be fairly restrictive and not contain patterns
1884 @cindex Lazy Lock mode
1885 @cindex Just-in-time Lock mode
1887 This level is designed for fairly modern hardware and a font lock
1888 support mode like Lazy Lock or Just-in-time Lock mode that only
1889 fontifies the parts that are actually shown. Fontifying the whole
1890 buffer at once can easily get bothersomely slow even on contemporary
1892 @c ACM, 2005/8/28: There should be a page in the (X)Emacs manual
1893 @c describing these support modes. There wasn't in the
1894 @c fourteenth edition of the Emacs manual (released with Emacs 21.3).
1895 @c There might be one in the Emacs CVS for 22.1.
1898 @cindex user defined types
1899 @cindex types, user defined
1901 Since user defined types are hard to recognize you can provide
1902 additional regexps to match those you use:
1904 @defopt c-font-lock-extra-types
1905 @defoptx c++-font-lock-extra-types
1906 @defoptx objc-font-lock-extra-types
1907 @defoptx java-font-lock-extra-types
1908 @defoptx idl-font-lock-extra-types
1909 @defoptx pike-font-lock-extra-types
1910 For each language there's a variable @code{*-font-lock-extra-types},
1911 where @samp{*} stands for the language in question. It contains a list
1912 of regexps that matches identifiers that should be recognized as types,
1913 e.g. @samp{\\sw+_t} to recognize all identifiers ending with @samp{_t}
1914 as is customary in C code. Each regexp should not match more than a
1917 The default values contain regexps for many types in standard runtime
1918 libraries that are otherwise difficult to recognize, and patterns for
1919 standard type naming conventions like the @samp{_t} suffix in C and C++.
1920 Java, Objective-C and Pike have as a convention to start class names
1921 with capitals, so there are patterns for that in those languages.
1923 Despite the names of these variables, they are not only used for
1924 fontification but in other places as well where @ccmode{} needs to
1929 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1930 @node Faces, Doc Comments, Font Locking Preliminaries, Font Locking
1931 @comment node-name, next, previous, up
1934 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1936 @ccmode{} attempts to use the standard faces for programming languages
1937 in accordance with their intended purposes as far as possible. No extra
1938 faces are currently provided, with the exception of a replacement face
1939 @code{c-invalid-face} for emacsen that don't provide
1940 @code{font-lock-warning-face}.
1944 @vindex font-lock-comment-face
1945 Normal comments are fontified in @code{font-lock-comment-face}.
1948 @vindex font-lock-doc-face
1949 @vindex font-lock-doc-string-face
1950 @vindex font-lock-comment-face
1951 Comments that are recognized as documentation (@pxref{Doc Comments})
1952 get @code{font-lock-doc-face} (Emacs) or
1953 @code{font-lock-doc-string-face} (XEmacs) if those faces exist. If
1954 they don't then @code{font-lock-comment-face} is used.
1957 @vindex font-lock-string-face
1958 String and character literals are fontified in
1959 @code{font-lock-string-face}.
1962 @vindex font-lock-keyword-face
1963 Keywords are fontified with @code{font-lock-keyword-face}.
1966 @vindex font-lock-function-name-face
1967 @code{font-lock-function-name-face} is used for function names in
1968 declarations and definitions, and classes in those contexts. It's also
1969 used for preprocessor defines with arguments.
1972 @vindex font-lock-variable-name-face
1973 Variables in declarations and definitions, and other identifiers in such
1974 variable contexts, get @code{font-lock-variable-name-face}. It's also
1975 used for preprocessor defines without arguments.
1978 @vindex font-lock-constant-face
1979 @vindex font-lock-reference-face
1980 Builtin constants are fontified in @code{font-lock-constant-face} if it
1981 exists, @code{font-lock-reference-face} otherwise. As opposed to the
1982 preceding two faces, this is used on the names in expressions, and it's
1983 not used in declarations, even if there happen to be a @samp{const} in
1987 @vindex font-lock-type-face
1988 @code{font-lock-type-face} is put on types (both predefined and user
1989 defined) and classes in type contexts.
1992 @vindex font-lock-constant-face
1993 @vindex font-lock-reference-face
1994 Label identifiers get @code{font-lock-constant-face} if it exists,
1995 @code{font-lock-reference-face} otherwise.
1998 Name qualifiers and identifiers for scope constructs are fontified like
2002 Special markup inside documentation comments are also fontified like
2006 @vindex font-lock-preprocessor-face
2007 @vindex font-lock-builtin-face
2008 @vindex font-lock-reference-face
2009 Preprocessor directives get @code{font-lock-preprocessor-face} if it
2010 exists (i.e. XEmacs). In Emacs they get @code{font-lock-builtin-face}
2011 or @code{font-lock-reference-face}, for lack of a closer equivalent.
2014 @vindex font-lock-warning-face
2015 @vindex c-invalid-face
2016 @vindex invalid-face (c-)
2017 Some kinds of syntactic errors are fontified with
2018 @code{font-lock-warning-face} in Emacs. In older XEmacs versions
2019 there's no corresponding standard face, so there a special
2020 @code{c-invalid-face} is used, which is defined to stand out sharply by
2023 Note that it's not used for @samp{#error} or @samp{#warning} directives,
2024 since those aren't syntactic errors in themselves.
2028 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2029 @node Doc Comments, AWK Mode Font Locking, Faces, Font Locking
2030 @comment node-name, next, previous, up
2031 @section Documentation Comments
2032 @cindex documentation comments
2033 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2035 There are various tools to supply documentation in the source as
2036 specially structured comments, e.g. the standard Javadoc tool in Java.
2037 @ccmode{} provides an extensible mechanism to fontify such comments and
2038 the special markup inside them.
2040 @defopt c-doc-comment-style
2041 @vindex doc-comment-style (c-)
2042 This is a style variable that specifies which documentation comment
2043 style to recognize, e.g. @code{javadoc} for Javadoc comments.
2045 The value may also be a list of styles, in which case all of them are
2046 recognized simultaneously (presumably with markup cues that don't
2049 The value may also be an association list to specify different comment
2050 styles for different languages. The symbol for the major mode is then
2051 looked up in the alist, and the value of that element is interpreted as
2052 above if found. If it isn't found then the symbol `other' is looked up
2053 and its value is used instead.
2055 The default value for @code{c-doc-comment-style} is
2056 @w{@code{((java-mode . javadoc) (pike-mode . autodoc) (c-mode . gtkdoc))}}.
2058 Note that @ccmode{} uses this variable to set other variables that
2059 handle fontification etc. That's done at mode initialization or when
2060 you switch to a style which sets this variable. Thus, if you change it
2061 in some other way, e.g. interactively in a CC Mode buffer, you will need
2062 to do @kbd{M-x java-mode} (or whatever mode you're currently using) to
2065 @findex c-setup-doc-comment-style
2066 @findex setup-doc-comment-style (c-)
2067 Note also that when @ccmode{} starts up, the other variables are
2068 modified before the mode hooks are run. If you change this variable in
2069 a mode hook, you'll have to call @code{c-setup-doc-comment-style}
2070 afterwards to redo that work.
2073 @ccmode{} currently provides handing of the following doc comment
2078 @cindex Javadoc markup
2079 Javadoc comments, the standard tool in Java.
2082 @cindex Pike autodoc markup
2083 For Pike autodoc markup, the standard in Pike.
2086 @cindex GtkDoc markup
2087 For GtkDoc markup, widely used in the Gnome community.
2090 The above is by no means complete. If you'd like to see support for
2091 other doc comment styles, please let us know (@pxref{Mailing Lists and
2094 You can also write your own doc comment fontification support to use
2095 with @code{c-doc-comment-style}: Supply a variable or function
2096 @code{*-font-lock-keywords} where @samp{*} is the name you want to use
2097 in @code{c-doc-comment-style}. If it's a variable, it's prepended to
2098 @code{font-lock-keywords}. If it's a function, it's called at mode
2099 initialization and the result is prepended. For an example, see
2100 @code{javadoc-font-lock-keywords} in @file{cc-fonts.el}.
2102 If you add support for another doc comment style, please consider
2103 contributing it - send a note to @email{bug-cc-mode@@gnu.org}.
2106 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2107 @node AWK Mode Font Locking, , Doc Comments, Font Locking
2108 @comment node-name, next, previous, up
2109 @section AWK Mode Font Locking
2110 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2112 The general appearance of font-locking in AWK mode is much like in any
2113 other programming mode. @xref{Faces For Font Lock,,,elisp, GNU Emacs
2114 Lisp Reference Manual}.
2116 The following faces are, however, used in a non-standard fashion in
2120 @item @code{font-lock-variable-name-face}
2121 This face was intended for variable declarations. Since variables are
2122 not declared in AWK, this face is used instead for AWK system
2123 variables (such as @code{NF}) and ``Special File Names'' (such as
2124 @code{"/dev/stderr"}).
2126 @item @code{font-lock-builtin-face} (Emacs)/@code{font-lock-preprocessor-face} (XEmacs)
2127 This face is normally used for preprocessor directives in @ccmode{}.
2128 There are no such things in AWK, so this face is used instead for
2129 standard functions (such as @code{match}).
2131 @item @code{font-lock-string-face}
2132 As well as being used for strings, including localizable strings,
2133 (delimited by @samp{"} and @samp{_"}), this face is also used for AWK
2134 regular expressions (delimited by @samp{/}).
2136 @item @code{font-lock-warning-face} (Emacs)/@code{c-invalid-face} (XEmacs)
2137 This face highlights the following syntactically invalid AWK
2142 An unterminated string or regular expression. Here the opening
2143 delimiter (@samp{"} or @samp{/} or @samp{_"}) is displayed in
2144 @code{font-lock-warning-face}. This is most noticeable when typing in a
2145 new string/regular expression into a buffer, when the warning-face
2146 serves as a continual reminder to terminate the construct.
2148 AWK mode fontifies unterminated strings/regular expressions
2149 differently from other modes: Only the text up to the end of the line
2150 is fontified as a string (escaped newlines being handled correctly),
2151 rather than the text up to the next string quote.
2154 A space between the function name and opening parenthesis when calling
2155 a user function. The last character of the function name and the
2156 opening parenthesis are highlighted. This font-locking rule will
2157 spuriously highlight a valid concatenation expression where an
2158 identifier precedes a parenthesized expression. Unfortunately.
2161 Whitespace following the @samp{\} in what otherwise looks like an
2162 escaped newline. The @samp{\} is highlighted.
2167 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2168 @node Config Basics, Custom Filling and Breaking, Font Locking, Top
2169 @comment node-name, next, previous, up
2170 @chapter Configuration Basics
2171 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2173 @cindex Emacs Initialization File
2174 @cindex Configuration
2175 You configure @ccmode{} by setting Lisp variables and calling (and
2176 perhaps writing) Lisp functions@footnote{DON'T PANIC!!! This isn't
2177 difficult.}, which is usually done by adding code to an Emacs
2178 initialization file. This file might be @file{site-start.el} or
2179 @file{.emacs} or @file{init.el} or @file{default.el} or perhaps some
2180 other file. @xref{Init File,,,@emacsman{}, @emacsmantitle{}}. For
2181 the sake of conciseness, we just call this file ``your @file{.emacs}''
2182 throughout the rest of the manual.
2184 Several of these variables (currently 16), are known collectively as
2185 @dfn{style variables}. @ccmode{} provides a special mechanism, known
2186 as @dfn{styles} to make it easier to set these variables as a group,
2187 to ``inherit'' settings from one style into another, and so on. Style
2188 variables remain ordinary Lisp variables, whose values can be read and
2189 changed independently of the style system. @xref{Style Variables}.
2191 There are several ways you can write the code, depending on the
2192 precise effect you want---they are described further down on this page.
2193 If you are new to @ccmode{}, we suggest you begin with the simplest
2194 method, ``Top-level commands or the customization interface''.
2196 If you make conflicting settings in several of these ways, the way
2197 that takes precedence is the one that appears latest in this list:
2202 @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.}
2203 @itemx Top-level command or ``customization interface''
2205 @itemx File Local Variable setting
2209 Here is a summary of the different ways of writing your configuration
2213 @item Top-level commands or the ``customization interface''
2214 Most simply, you can write @code{setq} and similar commands at the top
2215 level of your @file{.emacs} file. When you load a @ccmode{} buffer,
2216 it initializes its configuration from these global values (at least,
2217 for those settings you have given values to), so it makes sense to
2218 have these @code{setq} commands run @emph{before} @ccmode{} is first
2219 initialized---in particular, before any call to @code{desktop-read}
2220 (@pxref{Saving Emacs Sessions,,, emacs, GNU Emacs Manual}). For
2221 example, you might set c-basic-offset thus:
2224 (setq c-basic-offset 4)
2227 You can use the more user friendly Customization interface instead,
2228 but this manual does not cover in detail how that works. To do this,
2229 start by typing @kbd{M-x customize-group @key{RET} c @key{RET}}.
2230 @xref{Easy Customization,,,@emacsman{}, @emacsmantitle{}}.
2231 @c The following note really belongs in the Emacs manual.
2232 Emacs normally writes the customizations at the end of your
2233 @file{.emacs} file. If you use @code{desktop-read}, you should edit
2234 your @file{.emacs} to place the call to @code{desktop-read} @emph{after}
2237 The first initialization of @ccmode{} puts a snapshot of the
2238 configuration settings into the special style @code{user}.
2239 @xref{Built-in Styles}.
2241 For basic use of Emacs, either of these ways of configuring is
2242 adequate. However, the settings are then the same in all @ccmode{}
2243 buffers and it can be clumsy to communicate them between programmers.
2244 For more flexibility, you'll want to use one (or both) of @ccmode{}'s
2245 more sophisticated facilities, hooks and styles.
2248 An Emacs @dfn{hook} is a place to put Lisp functions that you want
2249 Emacs to execute later in specific circumstances.
2250 @xref{Hooks,,,@lispref{}, @lispreftitle{}}. @ccmode{} supplies a main
2251 hook and a language-specific hook for each language it supports - any
2252 functions you put onto these hooks get executed as the last part of a
2253 buffer's initialization. Typically you put most of your customization
2254 within the main hook, and use the language-specific hooks to vary the
2255 customization settings between language modes. For example, if you
2256 wanted different (non-standard) values of @code{c-basic-offset} in C
2257 Mode and Java Mode buffers, you could do it like this:
2261 (defun my-c-mode-hook ()
2262 (setq c-basic-offset 3))
2263 (add-hook 'c-mode-hook 'my-c-mode-hook)
2265 (defun my-java-mode-hook ()
2266 (setq c-basic-offset 6))
2267 (add-hook 'java-mode-hook 'my-java-mode-hook)
2271 See @ref{CC Hooks} for more details on the use of @ccmode{} hooks.
2274 A @ccmode{} @dfn{style} is a coherent collection of customizations
2275 with a name. At any time, exactly one style is active in each
2276 @ccmode{} buffer, either the one you have selected or a default.
2277 @ccmode{} is delivered with several existing styles. Additionally,
2278 you can create your own styles, possibly based on these existing
2279 styles. If you worked in a programming team called the ``Free
2280 Group'', which had its own coding standards, you might well have this
2281 in your @file{.emacs} file:
2284 (setq c-default-style '((java-mode . "java")
2286 (other . "free-group-style")))
2289 See @ref{Styles} for fuller details on using @ccmode{} styles and how
2292 @item File Local Variable setting
2293 A @dfn{file local variable setting} is a setting which applies to an
2294 individual source file. You put this in a @dfn{local variables list},
2295 a special block at the end of the source file (@pxref{Specifying File
2296 Variables,,, @emacsman{}}).
2299 A @dfn{file style} is a rarely used variant of the ``style'' mechanism
2300 described above, which applies to an individual source file.
2301 @xref{File Styles}. You use this by setting certain special variables
2302 in a local variables list (@pxref{Specifying File Variables,,,
2305 @item Hooks with Styles
2306 For ultimate flexibility, you can use hooks and styles together. For
2307 example, if your team were developing a product which required a
2308 Linux driver, you'd probably want to use the ``linux'' style for the
2309 driver, and your own team's style for the rest of the code. You
2310 could achieve this with code like this in your @file{.emacs}:
2314 (defun my-c-mode-hook ()
2316 (if (and (buffer-file-name)
2317 (string-match "/usr/src/linux" (buffer-file-name)))
2319 "free-group-style")))
2320 (add-hook 'c-mode-hook 'my-c-mode-hook)
2324 In a programming team, a hook is a also a good place for each member
2325 to put his own personal preferences. For example, you might be the
2326 only person in your team who likes Auto-newline minor mode. You could
2327 have it enabled by default by placing the following in your
2332 (defun my-turn-on-auto-newline ()
2333 (c-toggle-auto-newline 1))
2334 (add-hook 'c-mode-common-hook 'my-turn-on-auto-newline)
2345 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2346 @node CC Hooks, Style Variables, Config Basics, Config Basics
2347 @comment node-name, next, previous, up
2350 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2351 @c The node name is "CC Hooks" rather than "Hooks" because of a bug in
2352 @c some older versions of Info, e.g. the info.el in GNU Emacs 21.3.
2353 @c If you go to "Config Basics" and hit <CR> on the xref to "CC
2354 @c Hooks" the function Info-follow-reference searches for "*Note: CC
2355 @c Hooks" from the beginning of the page. If this node were instead
2356 @c named "Hooks", that search would spuriously find "*Note:
2357 @c Hooks(elisp)" and go to the wrong node.
2359 @ccmode{} provides several hooks that you can use to customize the
2360 mode for your coding style. The main hook is
2361 @code{c-mode-common-hook}; typically, you'll put the bulk of your
2362 customizations here. In addition, each language mode has its own
2363 hook, allowing you to fine tune your settings individually for the
2364 different @ccmode{} languages, and there is a package initialization
2365 hook. Finally, there is @code{c-special-indent-hook}, which enables
2366 you to solve anomalous indentation problems. It is described in
2367 @ref{Other Indentation}, not here. All these hooks adhere to the
2368 standard Emacs conventions.
2370 When you open a buffer, @ccmode{} first initializes it with the
2371 currently active style (@pxref{Styles}). Then it calls
2372 @code{c-mode-common-hook}, and finally it calls the language-specific
2373 hook. Thus, any style settings done in these hooks will override
2374 those set by @code{c-default-style}.
2376 @defvar c-initialization-hook
2377 @vindex initialization-hook (c-)
2378 Hook run only once per Emacs session, when @ccmode{} is initialized.
2379 This is a good place to change key bindings (or add new ones) in any
2380 of the @ccmode{} key maps. @xref{Sample .emacs File}.
2383 @defvar c-mode-common-hook
2384 @vindex mode-common-hook (c-)
2385 Common hook across all languages. It's run immediately before the
2386 language specific hook.
2390 @defvarx c++-mode-hook
2391 @defvarx objc-mode-hook
2392 @defvarx java-mode-hook
2393 @defvarx idl-mode-hook
2394 @defvarx pike-mode-hook
2395 @defvarx awk-mode-hook
2396 The language specific mode hooks. The appropriate one is run as the
2397 last thing when you enter that language mode.
2400 Although these hooks are variables defined in @ccmode{}, you can give
2401 them values before @ccmode{}'s code is loaded---indeed, this is the
2402 only way to use @code{c-initialization-hook}. Their values aren't
2403 overwritten when @ccmode{} gets loaded.
2405 Here's a simplified example of what you can add to your @file{.emacs}
2406 file to do things whenever any @ccmode{} language is edited. See the
2407 Emacs manuals for more information on customizing Emacs via hooks.
2408 @xref{Sample .emacs File}, for a more complete sample @file{.emacs}
2412 (defun my-c-mode-common-hook ()
2413 ;; my customizations for all of c-mode and related modes
2414 (no-case-fold-search)
2416 (add-hook 'c-mode-common-hook 'my-c-mode-common-hook)
2419 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2420 @node Style Variables, Styles, CC Hooks, Config Basics
2421 @comment node-name, next, previous, up
2422 @section Style Variables
2424 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2426 @cindex style variables
2427 The variables that @ccmode{}'s style system control are called
2428 @dfn{style variables}. Note that style variables are ordinary Lisp
2429 variables, which the style system initializes; you can change their
2430 values at any time (e.g. in a hook function). The style system can
2431 also set other variables, to some extent. @xref{Styles}.
2433 @dfn{Style variables} are handled specially in several ways:
2437 Style variables are by default buffer-local variables. However, they
2438 can instead be made global by setting
2439 @code{c-style-variables-are-local-p} to @code{nil} before @ccmode{} is
2443 @vindex c-old-style-variable-behavior
2444 @vindex old-style-variable-behavior (c-)
2445 The default global binding of any style variable (with two exceptions
2446 - see below) is the special symbol @code{set-from-style}. When the
2447 style system initializes a buffer-local copy of a style variable for a
2448 @ccmode{} buffer, if its global binding is still that symbol then it
2449 will be set from the current style. Otherwise it will retain its
2450 global default@footnote{This is a big change from versions of
2451 @ccmode{} earlier than 5.26, where such settings would get overridden
2452 by the style system unless special precautions were taken. That was
2453 changed since it was counterintuitive and confusing, especially to
2454 novice users. If your configuration depends on the old overriding
2455 behavior, you can set the variable
2456 @code{c-old-style-variable-behavior} to non-@code{nil}.}. This
2457 ``otherwise'' happens, for example, when you've set the variable with
2458 @code{setq} at the top level of your @file{.emacs} (@pxref{Config
2462 The style variable @code{c-offsets-alist} (@pxref{c-offsets-alist}) is
2463 an association list with an element for each syntactic symbol. It's
2464 handled a little differently from the other style variables. It's
2465 default global binding is the empty list @code{nil}, rather than
2466 @code{set-from-style}. Before the style system is initialized, you
2467 can add individual elements to @code{c-offsets-alist} by calling
2468 @code{c-set-offset}(@pxref{c-offsets-alist}) just like you would set
2469 other style variables with @code{setq}. Those elements will then
2470 prevail when the style system later initializes a buffer-local copy of
2471 @code{c-offsets-alist}.
2474 The style variable @code{c-special-indent-hook} is also handled in a
2475 special way. Styles can only add functions to this hook, not remove
2476 them, so any global settings you put on it are always
2477 preserved@footnote{This did not change in version 5.26.}. The value
2478 you give this variable in a style definition can be either a function
2479 or a list of functions.
2482 The global bindings of the style variables get captured in the special
2483 @code{user} style when the style system is first initialized.
2484 @xref{Built-in Styles}, for details.
2487 The style variables are:@*
2488 @code{c-indent-comment-alist},
2489 @code{c-indent-comments-syntactically-p} (@pxref{Indentation
2491 @code{c-doc-comment-style} (@pxref{Doc Comments});@*
2492 @code{c-block-comment-prefix}, @code{c-comment-prefix-regexp}
2493 (@pxref{Custom Filling and Breaking});@*
2494 @code{c-hanging-braces-alist} (@pxref{Hanging Braces});@*
2495 @code{c-hanging-colons-alist} (@pxref{Hanging Colons});@*
2496 @code{c-hanging-semi&comma-criteria} (@pxref{Hanging Semicolons and
2498 @code{c-cleanup-list} (@pxref{Clean-ups});@*
2499 @code{c-basic-offset} (@pxref{Customizing Indentation});@*
2500 @code{c-offsets-alist} (@pxref{c-offsets-alist});@*
2501 @code{c-comment-only-line-offset} (@pxref{Comment Line-Up});@*
2502 @code{c-special-indent-hook}, @code{c-label-minimum-indentation}
2503 (@pxref{Other Indentation});@*
2504 @code{c-backslash-column}, @code{c-backslash-max-column}
2505 (@pxref{Custom Macros}).
2507 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2508 @node Styles, , Style Variables, Config Basics
2509 @comment node-name, next, previous, up
2512 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2514 By @dfn{style} we mean the layout of the code---things like how many
2515 columns to indent a block of code, whether an opening brace gets
2516 indented to the level of the code it encloses, or of the construct
2517 that introduces it, or ``hangs'' at the end of a line.
2519 Most people only need to edit code formatted in just a few well-defined
2520 and consistent styles. For example, their organization might impose a
2521 ``blessed'' style that all its programmers must conform to. Similarly,
2522 people who work on GNU software will have to use the GNU coding style.
2523 Some shops are more lenient, allowing a variety of coding styles, and as
2524 programmers come and go, there could be a number of styles in use. For
2525 this reason, @ccmode{} makes it convenient for you to set up logical
2526 groupings of customizations called @dfn{styles}, associate a single name
2527 for any particular style, and pretty easily start editing new or
2528 existing code using these styles.
2530 As an alternative to writing a style definition yourself, you can have
2531 @ccmode{} @dfn{guess} (at least part of) your style by looking at an
2532 already formatted piece of your code, @ref{Guessing the Style}.
2536 * Choosing a Style::
2538 * Guessing the Style::
2543 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2544 @node Built-in Styles, Choosing a Style, Styles, Styles
2545 @comment node-name, next, previous, up
2546 @subsection Built-in Styles
2547 @cindex styles, built-in
2548 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2550 If you're lucky, one of @ccmode{}'s built-in styles might be just
2551 what you're looking for. These are:
2556 Coding style blessed by the Free Software Foundation
2557 for C code in GNU programs.
2561 The classic Kernighan and Ritchie style for C code.
2565 Also known as ``Allman style'' after Eric Allman.
2568 @cindex Whitesmith style
2569 Popularized by the examples that came with Whitesmiths C, an early
2570 commercial C compiler.
2573 @cindex Stroustrup style
2574 The classic Stroustrup style for C++ code.
2577 @cindex Ellemtel style
2578 Popular C++ coding standards as defined by ``Programming in C++, Rules
2579 and Recommendations,'' Erik Nyquist and Mats Henricson,
2580 Ellemtel@footnote{This document is available at
2581 @uref{http://www.doc.ic.ac.uk/lab/cplus/c++.rules/} among other
2583 @c N.B. This URL was still valid at 2005/8/28 (ACM).
2587 C coding standard for Linux (the kernel).
2590 @cindex Python style
2591 C coding standard for Python extension modules@footnote{Python is a
2592 high level scripting language with a C/C++ foreign function interface.
2593 For more information, see @uref{http://www.python.org/}.}.
2597 The style for editing Java code. Note that the default
2598 value for @code{c-default-style} installs this style when you enter
2603 The style for editing AWK code. Note that the default value for
2604 @code{c-default-style} installs this style when you enter
2609 This is a special style created by you. It consists of the factory
2610 defaults for all the style variables as modified by the customizations
2611 you do either with the Customization interface or by writing
2612 @code{setq}s and @code{c-set-offset}s at the top level of your
2613 @file{.emacs} file (@pxref{Config Basics}). The style system creates
2614 this style as part of its initialization and doesn't modify it
2619 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2620 @node Choosing a Style, Adding Styles, Built-in Styles, Styles
2621 @comment node-name, next, previous, up
2622 @subsection Choosing a Style
2623 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2625 When you create a new buffer, its style will be set from
2626 @code{c-default-style}. The factory default is the style @code{gnu},
2627 except in Java and AWK modes where it's @code{java} and @code{awk}.
2629 Remember that if you set a style variable with the Customization
2630 interface or at the top level of your @file{.emacs} file before the
2631 style system is initialized (@pxref{Config Basics}), this setting will
2632 override the one that the style system would have given the variable.
2634 To set a buffer's style interactively, use the command @kbd{C-c .}
2635 (@pxref{Other Commands}). To set it from a file's local variable
2636 list, @ref{File Styles}.
2638 @defopt c-default-style
2639 @vindex default-style (c-)
2640 This variable specifies which style to install by default in new
2641 buffers. It takes either a style name string, or an association list
2642 of major mode symbols to style names:
2646 When @code{c-default-style} is a string, it must be an existing style
2647 name. This style is then used for all modes.
2650 When @code{c-default-style} is an association list, the mode language
2651 is looked up to find a style name string.
2654 If @code{c-default-style} is an association list where the mode
2655 language mode isn't found then the special symbol @samp{other} is
2656 looked up. If it's found then the associated style is used.
2659 If @samp{other} is not found then the @samp{gnu} style is used.
2662 In all cases, the style described in @code{c-default-style} is installed
2663 @emph{before} the language hooks are run, so you can always override
2664 this setting by including an explicit call to @code{c-set-style} in your
2665 language mode hook, or in @code{c-mode-common-hook}.
2667 The standard value of @code{c-default-style} is @w{@code{((java-mode
2668 . "java") (awk-mode . "awk") (other . "gnu"))}}.
2671 @defvar c-indentation-style
2672 @vindex indentation-style (c-)
2673 This variable always contains the buffer's current style name, as a
2677 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2678 @node Adding Styles, Guessing the Style, Choosing a Style, Styles
2679 @comment node-name, next, previous, up
2680 @subsection Adding and Amending Styles
2681 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2683 If none of the built-in styles is appropriate, you'll probably want to
2684 create a new @dfn{style definition}, possibly based on an existing
2685 style. To do this, put the new style's settings into a list with the
2686 following format - the list can then be passed as an argument to the
2687 function @code{c-add-style}. You can see an example of a style
2688 definition in @ref{Sample .emacs File}.
2690 @cindex style definition
2691 @c @defvr {List} style definition
2693 @item Structure of a Style Definition List
2694 ([@var{base-style}] [(@var{variable} . @var{value}) @dots{}])
2696 Optional @var{base-style}, if present, must be a string which is the
2697 name of the @dfn{base style} from which this style inherits. At most
2698 one @var{base-style} is allowed in a style definition. If
2699 @var{base-style} is not specified, the style inherits from the table
2700 of factory default values@footnote{This table is stored internally in
2701 the variable c-fallback-style.} instead. All styles eventually
2702 inherit from this internal table. Style loops generate errors. The
2703 list of pre-existing styles can be seen in @ref{Built-in Styles}.
2705 The dotted pairs (@var{variable} . @var{value}) each consist of a
2706 variable and the value it is to be set to when the style is later
2707 activated.@footnote{Note that if the variable has been given a value
2708 by the Customization interface or a @code{setq} at the top level of
2709 your @file{.emacs}, this value will override the one the style system
2710 tries to give it. @xref{Config Basics}.} The variable can be either a
2711 @ccmode{} style variable or an arbitrary Emacs variable. In the
2712 latter case, it is @emph{not} made buffer-local by the @ccmode{} style
2716 Two variables are treated specially in the dotted pair list:
2719 @item c-offsets-alist
2720 The value is in turn a list of dotted pairs of the form
2723 (@r{@var{syntactic-symbol}} . @r{@var{offset}})
2726 as described in @ref{c-offsets-alist}. These are passed to
2727 @code{c-set-offset} so there is no need to set every syntactic symbol
2728 in your style, only those that are different from the inherited style.
2730 @item c-special-indent-hook
2731 The value is added to @code{c-special-indent-hook} using
2732 @code{add-hook}, so any functions already on it are kept. If the value
2733 is a list, each element of the list is added with @code{add-hook}.
2737 Styles are kept in the @code{c-style-alist} variable, but you
2738 should never modify this variable directly. Instead, @ccmode{}
2739 provides the function @code{c-add-style} for this purpose.
2741 @defun c-add-style stylename description &optional set-p
2742 @findex add-style (c-)
2743 Add or update a style called @var{stylename}, a string.
2744 @var{description} is the new style definition in the form described
2745 above. If @var{stylename} already exists in @code{c-style-alist} then
2746 it is replaced by @var{description}. (Note, this replacement is
2747 total. The old style is @emph{not} merged into the new one.)
2748 Otherwise, a new style is added.
2750 If the optional @var{set-p} is non-@code{nil} then the new style is
2751 applied to the current buffer as well. The use of this facility is
2752 deprecated and it might be removed from @ccmode{} in a future release.
2753 You should use @code{c-set-style} instead.
2755 The sample @file{.emacs} file provides a concrete example of how a new
2756 style can be added and automatically set. @xref{Sample .emacs File}.
2759 @defvar c-style-alist
2760 @vindex style-alist (c-)
2761 This is the variable that holds the definitions for the styles. It
2762 should not be changed directly; use @code{c-add-style} instead.
2765 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2766 @node Guessing the Style, File Styles, Adding Styles, Styles
2767 @comment node-name, next, previous, up
2768 @subsection Guessing the Style
2769 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2771 Instead of specifying a style, you can get @ccmode{} to @dfn{guess}
2772 your style by examining an already formatted code buffer. @ccmode{}
2773 then determines the ''most frequent'' offset (@pxref{c-offsets-alist})
2774 for each of the syntactic symbols (@pxref{Indentation Engine Basics})
2775 encountered in the buffer, and the ''most frequent'' value of
2776 c-basic-offset (@pxref{Customizing Indentation}), then merges the
2777 current style with these ''guesses'' to form a new style. This
2778 combined style is known as the @dfn{guessed style}.
2780 To do this, call @code{c-guess} (or one of the other 5 guessing
2781 commands) on your sample buffer. The analysis of your code may take
2784 You can then set the guessed style in any @ccmode{} buffer with
2785 @code{c-guess-install}. You can display the style with
2786 @code{c-guess-view}, and preserve it by copying it into your
2787 @file{.emacs} for future use, preferably after editing it.
2790 @item @kbd{M-x c-guess-no-install}
2791 @itemx @kbd{M-x c-guess-buffer-no-install}
2792 @itemx @kbd{M-x c-guess-region-no-install}
2793 @findex c-guess-no-install
2794 @findex c-guess-buffer-no-install
2795 @findex c-guess-region-no-install
2796 @findex guess-no-install (c-)
2797 @findex guess-buffer-no-install (c-)
2798 @findex guess-region-no-install (c-)
2799 These commands analyze a part of the current buffer and guess the
2802 The part of the buffer examined is either the region
2803 (@code{c-guess-region-no-install}), the entire buffer
2804 (@code{c-guess-buffer-no-install}), or the first
2805 @code{c-guess-region-max} bytes (@code{c-guess-no-install}).
2807 Each of these commands can be given an optional prefix argument. This
2808 instructs @ccmode{} to combine the new guesses with the current
2809 guesses before forming the guessed style.
2813 @item @kbd{M-x c-guess}
2814 @itemx @kbd{M-x c-guess-buffer}
2815 @itemx @kbd{M-x c-guess-region}
2817 @findex c-guess-buffer
2818 @findex c-guess-region
2820 @findex guess-buffer (c-)
2821 @findex guess-region (c-)
2822 These commands analyze a part of the current buffer, guess the style
2823 from it, then install the guessed style on the buffer. The guessed
2824 style is given a name based on the buffer's absolute file name, and
2825 you can then set this style on any @ccmode{} buffer with @kbd{C-c .}.
2827 The part of the buffer examined is either the region
2828 (@code{c-guess-region}), the entire buffer (@code{c-guess-buffer}), or
2829 the first @code{c-guess-region-max} bytes (@code{c-guess}).
2831 Each of these commands can be given an optional prefix argument. This
2832 instructs @ccmode{} to combine the new guesses with the current
2833 guesses before forming the guessed style.
2836 @defopt c-guess-region-max
2837 @vindex guess-region-max (c-)
2838 This variable, default 50000, is the size in bytes of the buffer
2839 portion examined by c-guess and c-guess-no-install. If set to
2840 @code{nil}, the entire buffer is examined.
2843 @defopt c-guess-offset-threshold
2844 @vindex guess-offset-threshold (c-)
2845 This variable, default 10, is the maximum offset, either outwards or
2846 inwards, which will be taken into account by the analysis process.
2847 Any offset bigger than this will be ignored. For no limit, set this
2848 variable to a large number.
2852 @item @kbd{M-x c-guess-install}
2853 @findex c-guess-install
2854 @findex guess-install (c-)
2856 Set the current buffer's style to the guessed style. This prompts you
2857 to enter an optional new style name to give to the guessed style. By
2858 default, this name is based on the buffer's absolute file name. You
2859 can then use this style like any other.
2861 @item @kbd{M-x c-guess-view}
2862 @findex c-guess-view
2863 @findex guess-view (c-)
2864 Display the most recently guessed style in a temporary buffer. This
2865 display is in the form of a @code{c-add-style} form (@pxref{Adding
2866 Styles}) which can be easily copied to your @file{.emacs}. You will
2867 probably want to edit it first.
2869 The display of the guessed style contains these elements:
2872 @item Placeholder Name
2873 You should replace this with a style name of your own.
2875 The style current when the guessing began, from which the guessed
2876 style inherits (@pxref{Config Basics}) the settings which weren't
2878 @item Guessed Offsets
2879 These are the core result of the guessing process. Each of them is
2880 marked by a comment.
2881 @item Inherited Offsets
2882 These are syntactic offsets which have been taken over from the parent
2883 style. To avoid possible future conflicts, you should remove either
2884 these offsets or the parent style name.
2888 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2889 @node File Styles, , Guessing the Style, Styles
2890 @comment node-name, next, previous, up
2891 @subsection File Styles
2892 @cindex styles, file local
2893 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2895 @cindex file local variables
2897 The Emacs manual describes how you can customize certain variables on a
2898 per-file basis by including a @dfn{file local variable} block at the end
2899 of the file (@pxref{File Variables,, Local Variables in Files, @emacsman{},
2902 So far, you've only seen a functional interface for setting styles in
2903 @ccmode{}, and this can't be used here. @ccmode{} fills the gap by
2904 providing two variables for use in a file's local variable list.
2905 Don't use them anywhere else! These allow you to customize the style
2906 on a per-file basis:
2908 @defvar c-file-style
2909 @vindex file-style (c-)
2910 Set this variable to a style name string in the Local Variables list.
2911 From now on, when you visit the file, @ccmode{} will automatically set
2912 the file's style to this one using @code{c-set-style}.
2915 @defvar c-file-offsets
2916 @vindex file-offsets (c-)
2917 Set this variable (in the Local Variables list) to an association list
2918 of the same format as @code{c-offsets-alist}. From now on, when you
2919 visit the file, @ccmode{} will automatically institute these offsets
2920 using @code{c-set-offset}.
2923 Note that file style settings (i.e. @code{c-file-style}) are applied
2924 before file offset settings
2925 (i.e. @code{c-file-offsets})@footnote{Also, if either of these are set
2926 in a file's local variable section, all the style variable values are
2927 made local to that buffer, even if
2928 @code{c-style-variables-are-local-p} is @code{nil}. Since this
2929 variable is virtually always non-@code{nil} anyhow, you're unlikely to
2930 notice this effect.}.
2932 If you set any variable by the file local variables mechanism, that
2933 setting takes priority over all other settings, even those in your
2934 mode hooks (@pxref{CC Hooks}). Any individual setting of a variable
2935 will override one made through @code{c-file-style} or
2936 @code{c-file-offsets}.
2937 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2938 @node Custom Filling and Breaking, Custom Auto-newlines, Config Basics, Top
2939 @comment node-name, next, previous, up
2940 @chapter Customizing Filling and Line Breaking
2941 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2943 Since there's a lot of normal text in comments and string literals,
2944 @ccmode{} provides features to edit these like in text mode. It does
2945 this by hooking in on the different line breaking functions and tuning
2946 relevant variables as necessary.
2948 @vindex c-comment-prefix-regexp
2949 @vindex comment-prefix-regexp (c-)
2950 @cindex comment line prefix
2951 @vindex comment-start
2953 @vindex comment-start-skip
2954 @vindex paragraph-start
2955 @vindex paragraph-separate
2956 @vindex paragraph-ignore-fill-prefix
2957 @vindex adaptive-fill-mode
2958 @vindex adaptive-fill-regexp
2959 @vindex adaptive-fill-first-line-regexp
2960 To make Emacs recognize comments and treat text in them as normal
2961 paragraphs, @ccmode{} makes several standard
2962 variables@footnote{@code{comment-start}, @code{comment-end},
2963 @code{comment-start-skip}, @code{paragraph-start},
2964 @code{paragraph-separate}, @code{paragraph-ignore-fill-prefix},
2965 @code{adaptive-fill-mode}, @code{adaptive-fill-regexp}, and
2966 @code{adaptive-fill-first-line-regexp}.} buffer-local and modifies them
2967 according to the language syntax and the comment line prefix.
2969 @defopt c-comment-prefix-regexp
2970 @vindex comment-prefix-regexp (c-)
2971 This style variable contains the regexp used to recognize the
2972 @dfn{comment line prefix}, which is the line decoration that starts
2973 every line in a comment. The variable is either the comment line
2974 prefix itself, or (more usually) an association list with different
2975 values for different languages. The symbol for the major mode is
2976 looked up in the alist to get the regexp for the language, and if it
2977 isn't found then the special symbol @samp{other} is looked up instead.
2979 When a comment line gets divided by @kbd{M-j} or the like, @ccmode{}
2980 inserts the comment line prefix from a neighboring line at the start
2981 of the new line. The default value of c-comment-prefix-regexp is
2982 @samp{//+\\|\\**}, which matches C++ style line comments like
2989 with two or more slashes in front of them, and the second and
2990 subsequent lines of C style block comments like
3001 with zero or more stars at the beginning of every line. If you change
3002 this variable, please make sure it still matches the comment starter
3003 (i.e. @code{//}) of line comments @emph{and} the line prefix inside
3006 @findex c-setup-paragraph-variables
3007 @findex setup-paragraph-variables (c-)
3008 Also note that since @ccmode{} uses the value of
3009 @code{c-comment-prefix-regexp} to set up several other variables at
3010 mode initialization, there won't be any effect if you just change it
3011 inside a @ccmode{} buffer. You need to call the command
3012 @code{c-setup-paragraph-variables} too, to update those other
3013 variables. That's also the case if you modify
3014 @code{c-comment-prefix-regexp} in a mode hook, since @ccmode{} will
3015 already have set up these variables before calling the hook.
3018 In comments, @ccmode{} uses @code{c-comment-prefix-regexp} to adapt
3019 the line prefix from the other lines in the comment.
3021 @vindex adaptive-fill-mode
3022 @cindex Adaptive Fill mode
3023 @ccmode{} uses adaptive fill mode (@pxref{Adaptive Fill,,, emacs, GNU
3024 Emacs Manual}) to make Emacs correctly keep the line prefix when
3025 filling paragraphs. That also makes Emacs preserve the text
3026 indentation @emph{inside} the comment line prefix. E.g. in the
3027 following comment, both paragraphs will be filled with the left
3028 margins of the texts kept intact:
3032 /* Make a balanced b-tree of the nodes in the incoming
3033 * stream. But, to quote the famous words of Donald E.
3036 * Beware of bugs in the above code; I have only
3037 * proved it correct, not tried it.
3042 @findex c-setup-filladapt
3043 @findex setup-filladapt (c-)
3044 @findex filladapt-mode
3045 @vindex filladapt-mode
3046 @cindex Filladapt mode
3047 It's also possible to use other adaptive filling packages, notably Kyle
3048 E. Jones' Filladapt package@footnote{It's available from
3049 @uref{http://www.wonderworks.com/}. As of version 2.12, it does however
3050 lack a feature that makes it work suboptimally when
3051 @code{c-comment-prefix-regexp} matches the empty string (which it does
3052 by default). A patch for that is available from
3053 @uref{http://cc-mode.sourceforge.net/,, the CC Mode web site}.},
3054 @c 2005/11/22: The above is still believed to be the case.
3055 which handles things like bulleted lists nicely. There's a convenience
3056 function @code{c-setup-filladapt} that tunes the relevant variables in
3057 Filladapt for use in @ccmode{}. Call it from a mode hook, e.g. with
3058 something like this in your @file{.emacs}:
3061 (defun my-c-mode-common-hook ()
3064 (add-hook 'c-mode-common-hook 'my-c-mode-common-hook)
3067 @defopt c-block-comment-prefix
3068 @vindex block-comment-prefix (c-)
3069 @vindex c-comment-continuation-stars
3070 @vindex comment-continuation-stars (c-)
3071 Normally the comment line prefix inserted for a new line inside a
3072 comment is deduced from other lines in it. However there's one
3073 situation when there's no hint about what the prefix should look like,
3074 namely when a block comment is broken for the first time. This style
3075 variable@footnote{In versions before 5.26, this variable was called
3076 @code{c-comment-continuation-stars}. As a compatibility measure,
3077 @ccmode{} still uses the value on that variable if it's set.} is used
3078 then as the comment prefix. It defaults to @samp{*
3079 }@footnote{Actually, this default setting of
3080 @code{c-block-comment-prefix} typically gets overridden by the default
3081 style @code{gnu}, which sets it to blank. You can see the line
3082 splitting effect described here by setting a different style,
3083 e.g. @code{k&r} @xref{Choosing a Style}.}, which makes a comment
3086 /* Got O(n^2) here, which is a Bad Thing. */
3094 /* Got O(n^2) here, which
3095 * is a Bad Thing. */
3099 Note that it won't work to adjust the indentation by putting leading
3100 spaces in @code{c-block-comment-prefix}, since @ccmode{} still uses the
3101 normal indentation engine to indent the line. Thus, the right way to
3102 fix the indentation is by customizing the @code{c} syntactic symbol. It
3103 defaults to @code{c-lineup-C-comments}, which handles the indentation of
3104 most common comment styles, see @ref{Line-Up Functions}.
3107 @defopt c-ignore-auto-fill
3108 @vindex ignore-auto-fill (c-)
3109 When auto fill mode is enabled, @ccmode{} can selectively ignore it
3110 depending on the context the line break would occur in, e.g. to never
3111 break a line automatically inside a string literal. This variable
3112 takes a list of symbols for the different contexts where auto-filling
3117 Inside a string or character literal.
3119 Inside a C style block comment.
3121 Inside a C++ style line comment.
3123 Inside a preprocessor directive.
3125 Anywhere else, i.e. in normal code.
3128 By default, @code{c-ignore-auto-fill} is set to @code{(string cpp
3129 code)}, which means that when auto-fill mode is activated,
3130 auto-filling only occurs in comments. In literals, it's often
3131 desirable to have explicit control over newlines. In preprocessor
3132 directives, the necessary @samp{\} escape character before the newline
3133 is not automatically inserted, so an automatic line break would
3134 produce invalid code. In normal code, line breaks are normally
3135 dictated by some logical structure in the code rather than the last
3136 whitespace character, so automatic line breaks there will produce poor
3137 results in the current implementation.
3140 @vindex comment-multi-line
3141 If inside a comment and @code{comment-multi-line} (@pxref{Auto Fill,,,
3142 @emacsman{}, @emacsmantitle{}} is non-@code{nil}, the indentation and
3143 line prefix are preserved. If inside a comment and
3144 @code{comment-multi-line} is @code{nil}, a new comment of the same
3145 type is started on the next line and indented as appropriate for
3148 Note that @ccmode{} sets @code{comment-multi-line} to @code{t} at
3149 startup. The reason is that @kbd{M-j} could otherwise produce sequences
3150 of single line block comments for texts that should logically be treated
3151 as one comment, and the rest of the paragraph handling code
3152 (e.g. @kbd{M-q} and @kbd{M-a}) can't cope with that, which would lead to
3153 inconsistent behavior.
3155 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3156 @node Custom Auto-newlines, Clean-ups, Custom Filling and Breaking, Top
3157 @comment node-name, next, previous, up
3158 @chapter Customizing Auto-newlines
3159 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3161 @ccmode{} determines whether to insert auto-newlines in two basically
3162 different ways, depending on the character just typed:
3165 @item Braces and Colons
3166 @ccmode{} first determines the syntactic context of the brace or colon
3167 (@pxref{Syntactic Symbols}), then looks for a corresponding element in
3168 an alist. This element specifies where to put newlines - this is any
3169 combination of before and after the brace or colon. If no alist
3170 element is found, newlines are inserted both before and after a brace,
3171 but none are inserted around a colon. See @ref{Hanging Braces} and
3172 @ref{Hanging Colons}.
3174 @item Semicolons and Commas
3175 The variable @code{c-hanging-semi&comma-criteria} contains a list of
3176 functions which determine whether to insert a newline after a newly
3177 typed semicolon or comma. @xref{Hanging Semicolons and Commas}.
3180 The names of these configuration variables contain @samp{hanging}
3181 because they let you @dfn{hang} the pertinent characters. A character
3182 which introduces a C construct is said to @dfn{hang on the right} when
3183 it appears at the end of a line after other code, being separated by a
3184 line break from the construct it introduces, like the opening brace in:
3196 A character @dfn{hangs on the left} when it appears at the start of
3197 the line after the construct it closes off, like the above closing
3200 The next chapter, ``Clean-ups'', describes how to configure @ccmode{}
3201 to remove these automatically added newlines in certain specific
3202 circumstances. @xref{Clean-ups}.
3207 * Hanging Semicolons and Commas::
3211 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3212 @node Hanging Braces, Hanging Colons, Custom Auto-newlines, Custom Auto-newlines
3213 @comment node-name, next, previous, up
3214 @section Hanging Braces
3215 @cindex hanging braces
3216 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3218 To specify which kinds of braces you want auto-newlines put around,
3219 you set the style variable @code{c-hanging-braces-alist}. Its
3220 structure and semantics are described in this section. Details of how
3221 to set it up, and its relationship to CC Mode's style system are given
3222 in @ref{Style Variables}.
3224 Say you wanted an auto-newline after (but not before) the following
3232 First you need to find the @dfn{syntactic context} of the brace---type
3233 a @key{RET} before the brace to get it on a line of its
3234 own@footnote{Also insert a @samp{\} at the end of the previous line if
3235 you're in AWK Mode.}, then type @kbd{C-c C-s}. That will tell you
3239 ((substatement-open 1061))
3243 So here you need to put the entry @code{(substatement-open . (after))}
3244 into @code{c-hanging-braces-alist}.
3246 If you don't want any auto-newlines for a particular syntactic symbol,
3247 put this into @code{c-hanging-braces-alist}:
3253 If some brace syntactic symbol is not in @code{c-hanging-brace-alist},
3254 its entry is taken by default as @code{(before after)}---insert a
3255 newline both before and after the brace. In place of a
3256 ``before/after'' list you can specify a function in this alist---this
3257 is useful when the auto newlines depend on the code around the brace.
3259 @defopt c-hanging-braces-alist
3260 @vindex hanging-braces-alist (c-)
3262 This variable is an association list which maps syntactic symbols to
3263 lists of places to insert a newline. @xref{Association
3264 Lists,,,@lispref{}, @lispreftitle{}}. The key of each element is the
3265 syntactic symbol, the associated value is either @code{nil}, a list,
3269 @item The Key - the syntactic symbol
3270 The syntactic symbols that are useful as keys in this list are
3271 @code{brace-list-intro}, @code{statement-cont},
3272 @code{inexpr-class-open}, @code{inexpr-class-close}, and all the
3273 @code{*-open} and @code{*-close} symbols. @xref{Syntactic Symbols},
3274 for a more detailed description of these syntactic symbols, except for
3275 @code{inexpr-class-open} and @code{inexpr-class-close}, which aren't
3276 actual syntactic symbols. Elements with any other value as a key get
3279 The braces of anonymous inner classes in Java are given the special
3280 symbols @code{inexpr-class-open} and @code{inexpr-class-close}, so that
3281 they can be distinguished from the braces of normal classes@footnote{The
3282 braces of anonymous classes produce a combination of
3283 @code{inexpr-class}, and @code{class-open} or @code{class-close} in
3284 normal indentation analysis.}.
3286 Note that the aggregate constructs in Pike mode, @samp{(@{}, @samp{@})},
3287 @samp{([}, @samp{])}, and @samp{(<}, @samp{>)}, do not count as brace
3288 lists in this regard, even though they do for normal indentation
3289 purposes. It's currently not possible to set automatic newlines on
3292 @item The associated value - the ``ACTION'' list or function
3293 The value associated with each syntactic symbol in this association
3294 list is called an @var{action}, which can be either a list or a
3295 function which returns a list. @xref{Custom Braces}, for how to use
3296 a function as a brace hanging @var{action}.
3298 The list @var{action} (or the list returned by @var{action} when it's
3299 a function) contains some combination of the symbols @code{before} and
3300 @code{after}, directing @ccmode{} where to put newlines in
3301 relationship to the brace being inserted. Thus, if the list contains
3302 only the symbol @code{after}, then the brace hangs on the right side
3306 // here, open braces always `hang'
3307 void spam( int i ) @{
3314 When the list contains both @code{after} and @code{before}, the braces
3315 will appear on a line by themselves, as shown by the close braces in
3316 the above example. The list can also be empty, in which case newlines
3317 are added neither before nor after the brace.
3320 If a syntactic symbol is missing entirely from
3321 @code{c-hanging-braces-alist}, it's treated in the same way as an
3322 @var{action} with a list containing @code{before} and @code{after}, so
3323 that braces by default end up on their own line.
3325 For example, the default value of @code{c-hanging-braces-alist} is:
3331 (substatement-open after)
3332 (block-close . c-snug-do-while)
3333 (extern-lang-open after)
3334 (namespace-open after)
3336 (composition-open after)
3337 (inexpr-class-open after)
3338 (inexpr-class-close before))
3341 @noindent which says that @code{brace-list-open},
3342 @code{brace-entry-open} and @code{statement-cont}@footnote{Brace lists
3343 inside statements, such as initializers for static array variables
3344 inside functions in C, are recognized as @code{statement-cont}. All
3345 normal substatement blocks are recognized with other symbols.} braces
3346 should both hang on the right side and allow subsequent text to follow
3347 on the same line as the brace. Also, @code{substatement-open},
3348 @code{extern-lang-open}, and @code{inexpr-class-open} braces should hang
3349 on the right side, but subsequent text should follow on the next line.
3350 The opposite holds for @code{inexpr-class-close} braces; they won't
3351 hang, but the following text continues on the same line. Here, in the
3352 @code{block-close} entry, you also see an example of using a function as
3353 an @var{action}. In all other cases, braces are put on a line by
3361 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3362 @node Custom Braces, , Hanging Braces, Hanging Braces
3363 @comment node-name, next, previous, up
3364 @subsection Custom Brace Hanging
3365 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3367 @vindex c-hanging-braces-alist
3368 @vindex hanging-braces-alist (c-)
3369 @cindex action functions
3370 Syntactic symbols aren't the only place where you can customize
3371 @ccmode{} with the lisp equivalent of callback functions. Remember
3372 that @var{action}s are usually a list containing some combination of
3373 the symbols @code{before} and @code{after} (@pxref{Hanging Braces}).
3374 For more flexibility, you can instead specify brace ``hanginess'' by
3375 giving a syntactic symbol an @dfn{action function} in
3376 @code{c-hanging-braces-alist}; this function determines the
3377 ``hanginess'' of a brace, usually by looking at the code near it.
3379 @cindex customization, brace hanging
3380 An action function is called with two arguments: the syntactic symbol
3381 for the brace (e.g. @code{substatement-open}), and the buffer position
3382 where the brace has been inserted. Point is undefined on entry to an
3383 action function, but the function must preserve it (e.g. by using
3384 @code{save-excursion}). The return value should be a list containing
3385 some combination of @code{before} and @code{after}, including neither
3386 of them (i.e. @code{nil}).
3388 @defvar c-syntactic-context
3389 @vindex syntactic-context (c-)
3390 During the call to the indentation or brace hanging @var{action}
3391 function, this variable is bound to the full syntactic analysis list.
3392 This might be, for example, @samp{((block-close 73))}. Don't ever
3393 give @code{c-syntactic-context} a value yourself---this would disrupt
3394 the proper functioning of @ccmode{}.
3396 This variable is also bound in three other circumstances:
3397 (i)@tie{}when calling a c-hanging-semi&comma-criteria function
3398 (@pxref{Hanging Semicolons and Commas}); (ii)@tie{}when calling a
3399 line-up function (@pxref{Custom Line-Up}); (iii)@tie{}when calling a
3400 c-special-indent-hook function (@pxref{Other Indentation}).
3403 As an example, @ccmode{} itself uses this feature to dynamically
3404 determine the hanginess of braces which close ``do-while''
3408 void do_list( int count, char** atleast_one_string )
3412 handle_string( atleast_one_string[i] );
3414 @} while( i < count );
3418 @ccmode{} assigns the @code{block-close} syntactic symbol to the
3419 brace that closes the @code{do} construct, and normally we'd like the
3420 line that follows a @code{block-close} brace to begin on a separate
3421 line. However, with ``do-while'' constructs, we want the
3422 @code{while} clause to follow the closing brace. To do this, we
3423 associate the @code{block-close} symbol with the @var{action} function
3424 @code{c-snug-do-while}:
3427 (defun c-snug-do-while (syntax pos)
3428 "Dynamically calculate brace hanginess for do-while statements."
3431 (if (and (eq syntax 'block-close)
3432 (setq langelem (assq 'block-close c-syntactic-context))
3433 (progn (goto-char (cdr langelem))
3434 (if (= (following-char) ?@{)
3436 (looking-at "\\<do\\>[^_]")))
3441 @findex c-snug-do-while
3442 @findex snug-do-while (c-)
3443 This function simply looks to see if the brace closes a ``do-while''
3444 clause and if so, returns the list @samp{(before)} indicating
3445 that a newline should be inserted before the brace, but not after it.
3446 In all other cases, it returns the list @samp{(before after)} so
3447 that the brace appears on a line by itself.
3449 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3450 @node Hanging Colons, Hanging Semicolons and Commas, Hanging Braces, Custom Auto-newlines
3451 @comment node-name, next, previous, up
3452 @section Hanging Colons
3453 @cindex hanging colons
3454 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3456 @cindex customization, colon hanging
3457 @vindex c-hanging-colons-alist
3458 @vindex hanging-colons-alist (c-)
3460 Using a mechanism similar to brace hanging (@pxref{Hanging Braces}),
3461 colons can also be made to hang using the style variable
3462 @code{c-hanging-colons-alist} - When a colon is typed, @ccmode
3463 determines its syntactic context, looks this up in the alist
3464 @code{c-changing-colons-alist} and inserts up to two newlines
3465 accordingly. Here, however, If @ccmode fails to find an entry for a
3466 syntactic symbol in the alist, no newlines are inserted around the
3469 @defopt c-hanging-colons-alist
3470 @vindex hanging-colons-alist (c-)
3473 @item The Key - the syntactic symbol
3474 The syntactic symbols appropriate as keys in this association list
3475 are: @code{case-label}, @code{label}, @code{access-label},
3476 @code{member-init-intro}, and @code{inher-intro}. @xref{Syntactic
3477 Symbols}. Elements with any other value as a key get ignored.
3479 @item The associate value - the ``ACTION'' list
3480 The @var{action} here is simply a list containing a combination of the
3481 symbols @code{before} and @code{after}. Unlike in
3482 @code{c-hanging-braces-alist}, functions as @var{actions} are not
3483 supported - there doesn't seem to be any need for them.
3487 In C++, double-colons are used as a scope operator but because these
3488 colons always appear right next to each other, newlines before and after
3489 them are controlled by a different mechanism, called @dfn{clean-ups} in
3490 @ccmode{}. @xref{Clean-ups}, for details.
3492 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3493 @node Hanging Semicolons and Commas, , Hanging Colons, Custom Auto-newlines
3494 @comment node-name, next, previous, up
3495 @section Hanging Semicolons and Commas
3496 @cindex hanging semicolons
3497 @cindex hanging commas
3498 @cindex customization, semicolon newlines
3499 @cindex customization, comma newlines
3500 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3502 @defopt c-hanging-semi&comma-criteria
3503 @vindex hanging-semi&comma-criteria (c-)
3504 This style variable takes a list of functions; these get called when
3505 you type a semicolon or comma. The functions are called in order
3506 without arguments. When these functions are entered, point is just
3507 after the newly inserted @samp{;} or @samp{,} and they must preserve
3508 point (e.g., by using @code{save-excursion}). During the call, the
3509 variable @code{c-syntactic-context} is bound to the syntactic context
3510 of the current line@footnote{This was first introduced in @ccmode{}
3511 5.31.} @pxref{Custom Braces}. These functions don't insert newlines
3512 themselves, rather they direct @ccmode{} whether or not to do so.
3513 They should return one of the following values:
3517 A newline is to be inserted after the @samp{;} or @samp{,}, and no
3518 more functions from the list are to be called.
3520 No more functions from the list are to be called, and no newline is to
3523 No determination has been made, and the next function in the list is
3527 Note that auto-newlines are never inserted @emph{before} a semicolon
3528 or comma. If every function in the list is called without a
3529 determination being made, then no newline is added.
3531 In AWK mode, this variable is set by default to @code{nil}. In the
3532 other modes, the default value is a list containing a single function,
3533 @code{c-semi&comma-inside-parenlist}. This inserts newlines after all
3534 semicolons, apart from those separating @code{for}-clause statements.
3537 @defun c-semi&comma-no-newlines-before-nonblanks
3538 @findex semi&comma-no-newlines-before-nonblanks (c-)
3539 This is an example of a criteria function, provided by @ccmode{}. It
3540 prevents newlines from being inserted after semicolons when there is a
3541 non-blank following line. Otherwise, it makes no determination. To
3542 use, add this function to the front of the
3543 @code{c-hanging-semi&comma-criteria} list.
3546 (defun c-semi&comma-no-newlines-before-nonblanks ()
3548 (if (and (eq last-command-char ?\;)
3549 (zerop (forward-line 1))
3550 (not (looking-at "^[ \t]*$")))
3556 @defun c-semi&comma-inside-parenlist
3557 @findex semi&comma-inside-parenlist (c-)
3558 @defunx c-semi&comma-no-newlines-for-oneline-inliners
3559 @findex semi&comma-no-newlines-for-oneline-inliners (c-)
3560 The function @code{c-semi&comma-inside-parenlist} is what prevents
3561 newlines from being inserted inside the parenthesis list of @code{for}
3562 statements. In addition to
3563 @code{c-semi&comma-no-newlines-before-nonblanks} described above,
3564 @ccmode{} also comes with the criteria function
3565 @code{c-semi&comma-no-newlines-for-oneline-inliners}, which suppresses
3566 newlines after semicolons inside one-line inline method definitions
3567 (e.g. in C++ or Java).
3571 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3572 @node Clean-ups, Indentation Engine Basics, Custom Auto-newlines, Top
3573 @comment node-name, next, previous, up
3576 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3578 @dfn{Clean-ups} are mechanisms which remove (or exceptionally, add)
3579 whitespace in specific circumstances and are complementary to colon
3580 and brace hanging. You enable a clean-up by adding its symbol into
3581 @code{c-cleanup-list}, e.g. like this:
3584 (add-to-list 'c-cleanup-list 'space-before-funcall)
3587 On the surface, it would seem that clean-ups overlap the functionality
3588 provided by the @code{c-hanging-*-alist} variables. Clean-ups,
3589 however, are used to adjust code ``after-the-fact'', i.e. to adjust
3590 the whitespace in constructs later than when they were typed.
3592 Most of the clean-ups remove automatically inserted newlines, and are
3593 only active when auto-newline minor mode is turned on. Others will
3594 work all the time. Note that clean-ups are only performed when there
3595 is nothing but whitespace appearing between the individual components
3596 of the construct, and (apart from @code{comment-close-slash}) when the
3597 construct does not occur within a literal (@pxref{Auto-newlines}).
3599 @defopt c-cleanup-list
3600 @vindex cleanup-list (c-)
3603 You configure @ccmode{}'s clean-ups by setting the style variable
3604 @code{c-cleanup-list}, which is a list of clean-up symbols. By
3605 default, @ccmode{} cleans up only the @code{scope-operator} construct,
3606 which is necessary for proper C++ support.
3609 These are the clean-ups that are only active when electric and
3610 auto-newline minor modes are enabled:
3612 @c TBD: Would like to use some sort of @deffoo here; @table indents a
3613 @c bit too much in dvi output.
3615 @item brace-else-brace
3616 Clean up @samp{@} else @{} constructs by placing the entire construct on
3617 a single line. Clean up occurs when the open brace after the
3618 @samp{else} is typed. So for example, this:
3633 appears like this after the last open brace is typed:
3645 @item brace-elseif-brace
3646 Similar to the @code{brace-else-brace} clean-up, but this cleans up
3647 @samp{@} else if (...) @{} constructs. For example:
3662 appears like this after the last open parenthesis is typed:
3675 and like this after the last open brace is typed:
3683 @} else if( i==3 ) @{
3687 @item brace-catch-brace
3688 Analogous to @code{brace-elseif-brace}, but cleans up @samp{@} catch
3689 (...) @{} in C++ and Java mode.
3691 @item empty-defun-braces
3692 Clean up braces following a top-level function or class definition that
3693 contains no body. Clean up occurs when the closing brace is typed.
3705 is transformed into this when the close brace is typed:
3714 @item defun-close-semi
3715 Clean up the terminating semicolon on top-level function or class
3716 definitions when they follow a close brace. Clean up occurs when the
3717 semicolon is typed. So for example, the following:
3730 is transformed into this when the semicolon is typed:
3741 @item list-close-comma
3742 Clean up commas following braces in array and aggregate initializers.
3743 Clean up occurs when the comma is typed. The space before the comma
3744 is zapped just like the space before the semicolon in
3745 @code{defun-close-semi}.
3747 @item scope-operator
3748 Clean up double colons which might designate a C++ scope operator split
3749 across multiple lines@footnote{Certain C++ constructs introduce
3750 ambiguous situations, so @code{scope-operator} clean-ups might not
3751 always be correct. This usually only occurs when scoped identifiers
3752 appear in switch label tags.}. Clean up occurs when the second colon is
3753 typed. You will always want @code{scope-operator} in the
3754 @code{c-cleanup-list} when you are editing C++ code.
3756 @item one-liner-defun
3757 Clean up a single line of code enclosed by defun braces by removing
3758 the whitespace before and after the code. The clean-up happens when
3759 the closing brace is typed. If the variable
3760 @code{c-max-one-liner-length} is set, the cleanup is only done if the
3761 resulting line would be no longer than the value of that variable.
3763 For example, consider this AWK code:
3768 FS = "\t" # use <TAB> as a field separator
3774 It gets compacted to the following when the closing brace is typed:
3778 BEGIN @{FS = "\t"@} # use <TAB> as a field separator
3782 @defopt c-max-one-liner-length
3783 @vindex max-one-liner-length (c-)
3784 The maximum length of the resulting line for which the clean-up
3785 @code{one-liner-defun} will be triggered. This length is that of the entire
3786 line, including any leading whitespace and any trailing comment. Its
3787 default value is 80. If the value is zero or @code{nil}, no limit
3792 The following clean-ups are always active when they occur on
3793 @code{c-cleanup-list}, regardless of whether Electric minor mode or
3794 Auto-newline minor mode are enabled:
3797 @item space-before-funcall
3798 Insert a space between the function name and the opening parenthesis
3799 of a function call. This produces function calls in the style
3800 mandated by the GNU coding standards, e.g. @samp{signal@tie{}(SIGINT,
3801 SIG_IGN)} and @samp{abort@tie{}()}. Clean up occurs when the opening
3802 parenthesis is typed. This clean-up should never be active in AWK
3803 Mode, since such a space is syntactically invalid for user defined
3806 @item compact-empty-funcall
3807 Clean up any space between the function name and the opening parenthesis
3808 of a function call that has no arguments. This is typically used
3809 together with @code{space-before-funcall} if you prefer the GNU function
3810 call style for functions with arguments but think it looks ugly when
3811 it's only an empty parenthesis pair. I.e. you will get @samp{signal
3812 (SIGINT, SIG_IGN)}, but @samp{abort()}. Clean up occurs when the
3813 closing parenthesis is typed.
3815 @item comment-close-slash
3816 When inside a block comment, terminate the comment when you type a slash
3817 at the beginning of a line (i.e. immediately after the comment prefix).
3818 This clean-up removes whitespace preceding the slash and if needed,
3819 inserts a star to complete the token @samp{*/}. Type @kbd{C-q /} in this
3820 situation if you just want a literal @samp{/} inserted.
3824 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3825 @node Indentation Engine Basics, Customizing Indentation, Clean-ups, Top
3826 @comment node-name, next, previous, up
3827 @chapter Indentation Engine Basics
3828 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3830 This chapter will briefly cover how @ccmode{} indents lines of code.
3831 It is helpful to understand the indentation model being used so that
3832 you will know how to customize @ccmode{} for your personal coding
3833 style. All the details are in @ref{Customizing Indentation}.
3835 @ccmode{} has an indentation engine that provides a flexible and
3836 general mechanism for customizing indentation. When @ccmode{} indents
3837 a line of code, it separates its calculations into two steps:
3841 @cindex syntactic symbol
3842 @cindex anchor position
3843 It analyzes the line to determine its @dfn{syntactic symbol(s)} (the
3844 kind of language construct it's looking at) and its @dfn{anchor
3845 position} (the position earlier in the file that @ccmode{} will indent
3846 the line relative to). The anchor position might be the location of
3847 an opening brace in the previous line, for example. @xref{Syntactic
3851 @cindex indentation offset specifications
3852 It looks up the syntactic symbol(s) in the configuration to get the
3853 corresponding @dfn{offset(s)}. The symbol @code{+}, which means
3854 ``indent this line one more level'' is a typical offset. @ccmode{}
3855 then applies these offset(s) to the anchor position, giving the
3856 indentation for the line. The different sorts of offsets are
3857 described in @ref{c-offsets-alist}.
3860 In exceptional circumstances, the syntax directed indentation
3861 described here may be a nuisance rather than a help. You can disable
3862 it by setting @code{c-syntactic-indentation} to @code{nil}. (To set
3863 the variable interactively, @ref{Minor Modes}).
3865 @defopt c-syntactic-indentation
3866 @vindex syntactic-indentation (c-)
3867 When this is non-@code{nil} (which it is by default), the indentation
3868 of code is done according to its syntactic structure. When it's
3869 @code{nil}, every line is just indented to the same level as the
3870 previous one, and @kbd{TAB} (@code{c-indent-command}) adjusts the
3871 indentation in steps of @code{c-basic-offset}. The current style
3872 (@pxref{Config Basics}) then has no effect on indentation, nor do any
3873 of the variables associated with indentation, not even
3874 @code{c-special-indent-hook}.
3878 * Syntactic Analysis::
3879 * Syntactic Symbols::
3880 * Indentation Calculation::
3884 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3885 @node Syntactic Analysis, Syntactic Symbols, Indentation Engine Basics, Indentation Engine Basics
3886 @comment node-name, next, previous, up
3887 @section Syntactic Analysis
3888 @cindex syntactic analysis
3889 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3891 @cindex syntactic element
3892 @cindex syntactic context
3893 The first thing @ccmode{} does when indenting a line of code, is to
3894 analyze the line, determining the @dfn{syntactic context} of the
3895 (first) construct on that line. It's a list of @dfn{syntactic
3896 elements}, where each syntactic element in turn is a list@footnote{In
3897 @ccmode 5.28 and earlier, a syntactic element was a dotted pair; the
3898 cons was the syntactic symbol and the cdr was the anchor position.
3899 For compatibility's sake, the parameter passed to a line-up function
3900 still has this dotted pair form (@pxref{Custom Line-Up}).} Here is a
3901 brief and typical example:
3904 ((defun-block-intro 1959))
3907 @cindex syntactic symbol
3909 The first thing inside each syntactic element is always a
3910 @dfn{syntactic symbol}. It describes the kind of construct that was
3911 recognized, e.g. @code{statement}, @code{substatement},
3912 @code{class-open}, @code{class-close}, etc. @xref{Syntactic Symbols},
3913 for a complete list of currently recognized syntactic symbols and
3914 their semantics. The remaining entries are various data associated
3915 with the recognized construct - there might be zero or more.
3917 @cindex anchor position
3918 Conceptually, a line of code is always indented relative to some
3919 position higher up in the buffer (typically the indentation of the
3920 previous line). That position is the @dfn{anchor position} in the
3921 syntactic element. If there is an entry after the syntactic symbol in
3922 the syntactic element list then it's either nil or that anchor position.
3924 Here is an example. Suppose we had the following code as the only thing
3925 in a C++ buffer @footnote{The line numbers in this and future examples
3926 don't actually appear in the buffer, of course!}:
3929 1: void swap( int& a, int& b )
3938 We can use @kbd{C-c C-s} (@code{c-show-syntactic-information}) to
3939 report what the syntactic analysis is for the current line:
3942 @item @kbd{C-c C-s} (@code{c-show-syntactic-information})
3944 @findex c-show-syntactic-information
3945 @findex show-syntactic-information (c-)
3946 This command calculates the syntactic analysis of the current line and
3947 displays it in the minibuffer. The command also highlights the anchor
3951 Running this command on line 4 of this example, we'd see in the echo
3952 area@footnote{With a universal argument (i.e. @kbd{C-u C-c C-s}) the
3953 analysis is inserted into the buffer as a comment on the current
3961 and the @samp{i} of @code{int} on line 3 would be highlighted. This
3962 tells us that the line is a statement and it is indented relative to
3963 buffer position 35, the highlighted position. If you were to move
3964 point to line 3 and hit @kbd{C-c C-s}, you would see:
3967 ((defun-block-intro 29))
3971 This indicates that the @samp{int} line is the first statement in a top
3972 level function block, and is indented relative to buffer position 29,
3973 which is the brace just after the function header.
3975 Here's another example:
3978 1: int add( int val, int incr, int doit )
3982 5: return( val + incr );
3989 Hitting @kbd{C-c C-s} on line 4 gives us:
3992 ((substatement-open 46))
3995 @cindex substatement
3996 @cindex substatement block
3998 which tells us that this is a brace that @emph{opens} a substatement
3999 block. @footnote{A @dfn{substatement} is the line after a
4000 conditional statement, such as @code{if}, @code{else}, @code{while},
4001 @code{do}, @code{switch}, etc. A @dfn{substatement
4002 block} is a brace block following one of these conditional statements.}
4004 @cindex comment-only line
4005 Syntactic contexts can contain more than one element, and syntactic
4006 elements need not have anchor positions. The most common example of
4007 this is a @dfn{comment-only line}:
4010 1: void draw_list( List<Drawables>& drawables )
4012 3: // call the virtual draw() method on each element in list
4013 4: for( int i=0; i < drawables.count(), ++i )
4015 6: drawables[i].draw();
4021 Hitting @kbd{C-c C-s} on line 3 of this example gives:
4024 ((comment-intro) (defun-block-intro 46))
4028 and you can see that the syntactic context contains two syntactic
4029 elements. Notice that the first element, @samp{(comment-intro)}, has no
4033 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4034 @node Syntactic Symbols, Indentation Calculation, Syntactic Analysis, Indentation Engine Basics
4035 @comment node-name, next, previous, up
4036 @section Syntactic Symbols
4037 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4039 @cindex syntactic symbols, brief list
4040 @vindex c-offsets-alist
4041 @vindex offsets-alist (c-)
4042 This section is a complete list of the syntactic symbols which appear
4043 in the @code{c-offsets-alist} style variable, along with brief
4044 descriptions. The previous section (@pxref{Syntactic Analysis})
4045 states what syntactic symbols are and how the indentation engine uses
4048 More detailed descriptions of these symbols, together with snippets of
4049 source code to which they apply, appear in the examples in the
4050 subsections below. Note that, in the interests of brevity, the anchor
4051 position associated with most syntactic symbols is @emph{not}
4052 specified. In cases of doubt, type @kbd{C-c C-s} on a pertinent
4053 line---this highlights the anchor position.
4055 @ssindex -open symbols
4056 @ssindex -close symbols
4057 @ssindex -block-intro symbols
4058 The syntactic symbols which indicate brace constructs follow a general
4059 naming convention. When a line begins with an open or close brace,
4060 its syntactic symbol will contain the suffix @code{-open} or
4061 @code{-close} respectively. The first line within the brace block
4062 construct will contain the suffix @code{-block-intro}.
4064 @ssindex -intro symbols
4065 @ssindex -cont symbols
4066 In constructs which can span several lines, a distinction is usually
4067 made between the first line that introduces the construct and the
4068 lines that continue it. The syntactic symbols that indicate these
4069 lines will contain the suffixes @code{-intro} or @code{-cont}
4072 The best way to understand how all this works is by looking at some
4073 examples. Remember that you can see the syntax of any source code
4074 line by using @kbd{C-c C-s}.
4078 Inside a multiline string. @ref{Literal Symbols}.
4080 Inside a multiline C style block comment. @ref{Literal Symbols}.
4082 Brace that opens a top-level function definition. @ref{Function
4085 Brace that closes a top-level function definition. @ref{Function
4087 @item defun-block-intro
4088 The first line in a top-level defun. @ref{Function Symbols}.
4090 Brace that opens a class definition. @ref{Class Symbols}.
4092 Brace that closes a class definition. @ref{Class Symbols}.
4094 Brace that opens an in-class inline method. @ref{Class Symbols}.
4096 Brace that closes an in-class inline method. @ref{Class Symbols}.
4097 @item func-decl-cont
4098 The region between a function definition's argument list and the
4099 function opening brace (excluding K&R argument declarations). In C,
4100 you cannot put anything but whitespace and comments in this region,
4101 however in C++ and Java, @code{throws} declarations and other things
4102 can appear here. @ref{Literal Symbols}. @c @emph{FIXME!!! Can it not
4103 @c go somewhere better?}
4104 @item knr-argdecl-intro
4105 First line of a K&R C argument declaration. @ref{K&R Symbols}.
4107 Subsequent lines in a K&R C argument declaration. @ref{K&R Symbols}.
4109 The first line in a ``topmost'' definition. @ref{Function Symbols}.
4110 @item topmost-intro-cont
4111 Topmost definition continuation lines. This is only used in the parts
4112 that aren't covered by other symbols such as @code{func-decl-cont} and
4113 @code{knr-argdecl}. @ref{Function Symbols}.
4114 @item annotation-top-cont
4115 Topmost definition continuation lines where all previous items are
4116 annotations. @ref{Java Symbols}.
4117 @item member-init-intro
4118 First line in a member initialization list. @ref{Class Symbols}.
4119 @item member-init-cont
4120 Subsequent member initialization list lines. @ref{Class Symbols}.
4122 First line of a multiple inheritance list. @ref{Class Symbols}.
4124 Subsequent multiple inheritance lines. @ref{Class Symbols}.
4126 Statement block open brace. @ref{Literal Symbols}.
4128 Statement block close brace. @ref{Conditional Construct Symbols}.
4129 @item brace-list-open
4130 Open brace of an enum or static array list. @ref{Brace List Symbols}.
4131 @item brace-list-close
4132 Close brace of an enum or static array list. @ref{Brace List Symbols}.
4133 @item brace-list-intro
4134 First line in an enum or static array list. @ref{Brace List Symbols}.
4135 @item brace-list-entry
4136 Subsequent lines in an enum or static array list. @ref{Brace List
4138 @item brace-entry-open
4139 Subsequent lines in an enum or static array list where the line begins
4140 with an open brace. @ref{Brace List Symbols}.
4142 A statement. @ref{Function Symbols}.
4143 @item statement-cont
4144 A continuation of a statement. @ref{Function Symbols}.
4145 @item annotation-var-cont
4146 A continuation of a statement where all previous items are
4147 annotations. @ref{Java Symbols}.
4148 @item statement-block-intro
4149 The first line in a new statement block. @ref{Conditional Construct
4151 @item statement-case-intro
4152 The first line in a case block. @ref{Switch Statement Symbols}.
4153 @item statement-case-open
4154 The first line in a case block that starts with a brace. @ref{Switch
4157 The first line after a conditional or loop construct.
4158 @ref{Conditional Construct Symbols}.
4159 @item substatement-open
4160 The brace that opens a substatement block. @ref{Conditional Construct
4162 @item substatement-label
4163 The first line after a conditional or loop construct if it's a label.
4164 @ref{Conditional Construct Symbols}.
4166 A label in a @code{switch} block. @ref{Switch Statement Symbols}.
4168 C++ access control label. @ref{Class Symbols}.
4170 Any other label. @ref{Literal Symbols}.
4171 @item do-while-closure
4172 The @code{while} line that ends a @code{do}-@code{while} construct.
4173 @ref{Conditional Construct Symbols}.
4175 The @code{else} line of an @code{if}-@code{else} construct.
4176 @ref{Conditional Construct Symbols}.
4178 The @code{catch} or @code{finally} (in Java) line of a
4179 @code{try}-@code{catch} construct. @ref{Conditional Construct
4182 A line containing only a comment introduction. @ref{Literal Symbols}.
4184 The first line in an argument list. @ref{Paren List Symbols}.
4186 Subsequent argument list lines when no arguments follow on the same
4187 line as the arglist opening paren. @ref{Paren List Symbols}.
4188 @item arglist-cont-nonempty
4189 Subsequent argument list lines when at least one argument follows on
4190 the same line as the arglist opening paren. @ref{Paren List Symbols}.
4192 The solo close paren of an argument list. @ref{Paren List Symbols}.
4194 Lines continuing a stream operator (C++ only). @ref{Literal
4195 Symbols}. @c @emph{FIXME!!! Can this not be moved somewhere better?}
4197 The line is nested inside a class definition. @ref{Class Symbols}.
4199 The start of a preprocessor macro definition. @ref{Literal Symbols}.
4200 @item cpp-define-intro
4201 The first line inside a multiline preprocessor macro if
4202 @code{c-syntactic-indentation-in-macros} is set. @ref{Multiline Macro
4204 @item cpp-macro-cont
4205 All lines inside multiline preprocessor macros if
4206 @code{c-syntactic-indentation-in-macros} is @code{nil}.
4207 @ref{Multiline Macro Symbols}.
4209 A C++ friend declaration. @ref{Class Symbols}.
4210 @item objc-method-intro
4211 The first line of an Objective-C method definition. @ref{Objective-C
4213 @item objc-method-args-cont
4214 Lines continuing an Objective-C method definition. @ref{Objective-C
4216 @item objc-method-call-cont
4217 Lines continuing an Objective-C method call. @ref{Objective-C Method
4219 @item extern-lang-open
4220 Brace that opens an @code{extern} block (e.g. @code{extern "C"
4221 @{...@}}). @ref{External Scope Symbols}.
4222 @item extern-lang-close
4223 Brace that closes an @code{extern} block. @ref{External Scope
4226 Analogous to @code{inclass} syntactic symbol, but used inside
4227 @code{extern} blocks. @ref{External Scope Symbols}.
4228 @item namespace-open
4229 @itemx namespace-close
4231 These are analogous to the three @code{extern-lang} symbols above, but
4232 are returned for C++ namespace blocks. @ref{External Scope Symbols}.
4236 Analogous to the above, but for CORBA IDL @code{module} blocks.
4237 @ref{External Scope Symbols}.
4238 @item composition-open
4239 @itemx composition-close
4240 @itemx incomposition
4241 Analogous to the above, but for CORBA CIDL @code{composition} blocks.
4242 @ref{External Scope Symbols}.
4243 @item template-args-cont
4244 C++ template argument list continuations. @ref{Class Symbols}.
4246 Analogous to @code{inclass} syntactic symbol, but used inside lambda
4247 (i.e. anonymous) functions. Only used in Pike mode. @ref{Statement
4249 @item lambda-intro-cont
4250 Lines continuing the header of a lambda function, i.e. between the
4251 @code{lambda} keyword and the function body. Only used in Pike mode.
4252 @ref{Statement Block Symbols}.
4253 @item inexpr-statement
4254 A statement block inside an expression. The gcc C and C++ extension
4255 for this is recognized. It's also used for the special functions that
4256 take a statement block as an argument in Pike. @ref{Statement Block
4259 A class definition inside an expression. This is used for anonymous
4260 classes in Java. It's also used for anonymous array initializers in
4261 Java. @ref{Java Symbols}.
4265 * Function Symbols::
4267 * Conditional Construct Symbols::
4268 * Switch Statement Symbols::
4269 * Brace List Symbols::
4270 * External Scope Symbols::
4271 * Paren List Symbols::
4273 * Multiline Macro Symbols::
4274 * Objective-C Method Symbols::
4276 * Statement Block Symbols::
4280 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4281 @node Function Symbols, Class Symbols, Syntactic Symbols, Syntactic Symbols
4282 @comment node-name, next, previous, up
4283 @subsection Function Symbols
4284 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4286 This example shows a typical function declaration.
4290 2: swap( int& a, int& b )
4300 @ssindex topmost-intro
4301 @ssindex topmost-intro-cont
4303 @ssindex defun-close
4304 @ssindex defun-block-intro
4305 Line 1 shows a @code{topmost-intro} since it is the first line that
4306 introduces a top-level construct. Line 2 is a continuation of the
4307 top-level construct introduction so it has the syntax
4308 @code{topmost-intro-cont}. Line 3 shows a @code{defun-open} since it is
4309 the brace that opens a top-level function definition. Line 9 is the
4311 @code{defun-close} since it contains the brace that closes the top-level
4312 function definition. Line 4 is a @code{defun-block-intro}, i.e. it is
4313 the first line of a brace-block, enclosed in a
4314 top-level function definition.
4317 @ssindex statement-cont
4318 Lines 5, 6, and 7 are all given @code{statement} syntax since there
4319 isn't much special about them. Note however that line 8 is given
4320 @code{statement-cont} syntax since it continues the statement begun
4321 on the previous line.
4323 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4324 @node Class Symbols, Conditional Construct Symbols, Function Symbols, Syntactic Symbols
4325 @comment node-name, next, previous, up
4326 @subsection Class related Symbols
4327 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4329 Here's an example which illustrates some C++ class syntactic symbols:
4334 3: public Amplifiable
4338 7: : eString( new BassString( 0.105 )),
4339 8: aString( new BassString( 0.085 )),
4340 9: dString( new BassString( 0.065 )),
4341 10: gString( new BassString( 0.045 ))
4343 12: eString.tune( 'E' );
4344 13: aString.tune( 'A' );
4345 14: dString.tune( 'D' );
4346 15: gString.tune( 'G' );
4348 17: friend class Luthier;
4353 @ssindex class-close
4354 As in the previous example, line 1 has the @code{topmost-intro} syntax.
4355 Here however, the brace that opens a C++ class definition on line 4 is
4356 assigned the @code{class-open} syntax. Note that in C++, classes,
4357 structs, and unions are essentially equivalent syntactically (and are
4358 very similar semantically), so replacing the @code{class} keyword in the
4359 example above with @code{struct} or @code{union} would still result in a
4360 syntax of @code{class-open} for line 4 @footnote{This is the case even
4361 for C and Objective-C. For consistency, structs in all supported
4362 languages are syntactically equivalent to classes. Note however that
4363 the keyword @code{class} is meaningless in C and Objective-C.}.
4364 Similarly, line 18 is assigned @code{class-close} syntax.
4366 @ssindex inher-intro
4368 Line 2 introduces the inheritance list for the class so it is assigned
4369 the @code{inher-intro} syntax, and line 3, which continues the
4370 inheritance list is given @code{inher-cont} syntax.
4372 @ssindex access-label
4374 Hitting @kbd{C-c C-s} on line 5 shows the following analysis:
4377 ((inclass 58) (access-label 58))
4381 The primary syntactic symbol for this line is @code{access-label} as
4382 this is a label keyword that specifies access protection in C++. However,
4383 because this line is also a top-level construct inside a class
4384 definition, the analysis actually shows two syntactic symbols. The
4385 other syntactic symbol assigned to this line is @code{inclass}.
4386 Similarly, line 6 is given both @code{inclass} and @code{topmost-intro}
4390 ((inclass 58) (topmost-intro 60))
4393 @ssindex member-init-intro
4394 @ssindex member-init-cont
4395 Line 7 introduces a C++ member initialization list and as such is given
4396 @code{member-init-intro} syntax. Note that in this case it is
4397 @emph{not} assigned @code{inclass} since this is not considered a
4398 top-level construct. Lines 8 through 10 are all assigned
4399 @code{member-init-cont} since they continue the member initialization
4400 list started on line 7.
4402 @cindex in-class inline methods
4403 @ssindex inline-open
4404 @ssindex inline-close
4405 Line 11's analysis is a bit more complicated:
4408 ((inclass 58) (inline-open))
4411 This line is assigned a syntax of both @code{inline-open} and
4412 @code{inclass} because it opens an @dfn{in-class} C++ inline method
4413 definition. This is distinct from, but related to, the C++ notion of an
4414 inline function in that its definition occurs inside an enclosing class
4415 definition, which in C++ implies that the function should be inlined.
4416 However, if the definition of the @code{Bass} constructor appeared
4417 outside the class definition, the construct would be given the
4418 @code{defun-open} syntax, even if the keyword @code{inline} appeared
4419 before the method name, as in:
4424 3: public Amplifiable
4432 11: : eString( new BassString( 0.105 )),
4433 12: aString( new BassString( 0.085 )),
4434 13: dString( new BassString( 0.065 )),
4435 14: gString( new BassString( 0.045 ))
4437 16: eString.tune( 'E' );
4438 17: aString.tune( 'A' );
4439 18: dString.tune( 'D' );
4440 19: gString.tune( 'G' );
4445 Returning to the previous example, line 16 is given @code{inline-close}
4446 syntax, while line 12 is given @code{defun-block-open} syntax, and lines
4447 13 through 15 are all given @code{statement} syntax. Line 17 is
4448 interesting in that its syntactic analysis list contains three
4452 ((inclass 58) (topmost-intro 380) (friend))
4455 The @code{friend} and @code{inline-open} syntactic symbols are
4456 modifiers that do not have anchor positions.
4458 @ssindex template-args-cont
4459 Template definitions introduce yet another syntactic symbol:
4462 1: ThingManager <int,
4463 2: Framework::Callback *,
4464 3: Mutex> framework_callbacks;
4467 Here, line 1 is analyzed as a @code{topmost-intro}, but lines 2 and 3
4468 are both analyzed as @code{template-args-cont} lines.
4470 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4471 @node Conditional Construct Symbols, Switch Statement Symbols, Class Symbols, Syntactic Symbols
4472 @comment node-name, next, previous, up
4473 @subsection Conditional Construct Symbols
4474 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4476 Here is a (totally contrived) example which illustrates how syntax is
4477 assigned to various conditional constructs:
4480 1: void spam( int index )
4482 3: for( int i=0; i<index; i++ )
4485 6: do_something_special();
4488 9: do_something( i );
4491 12: another_thing( i-- );
4497 Only the lines that illustrate new syntactic symbols will be discussed.
4499 @ssindex substatement-open
4500 @ssindex statement-block-intro
4501 @ssindex block-close
4502 Line 4 has a brace which opens a conditional's substatement block. It
4503 is thus assigned @code{substatement-open} syntax, and since line 5 is
4504 the first line in the substatement block, it is assigned
4505 @code{statement-block-intro} syntax. Line 10 contains the brace
4506 that closes the inner substatement block, and is therefore given the
4507 syntax @code{block-close}@footnote{@code{block-open} is used only for
4508 ``free-standing'' blocks, and is somewhat rare (@pxref{Literal
4509 Symbols} for an example.)}. Line 13 is treated the same way.
4511 @ssindex substatement
4512 Lines 6 and 9 are also substatements of conditionals, but since they
4513 don't start blocks they are given @code{substatement} syntax
4514 instead of @code{substatement-open}.
4516 @ssindex substatement-label
4517 Line 8 contains a label, which is normally given @code{label} syntax.
4518 This one is however a bit special since it's between a conditional and
4519 its substatement. It's analyzed as @code{substatement-label} to let you
4520 handle this rather odd case differently from normal labels.
4522 @ssindex else-clause
4523 @ssindex catch-clause
4524 Line 7 start with an @code{else} that matches the @code{if} statement on
4525 line 5. It is therefore given the @code{else-clause} syntax and is
4526 anchored on the matching @code{if}. The @code{try}-@code{catch}
4527 constructs in C++ and Java are treated this way too, except that
4528 @code{catch} and (in Java) @code{finally}, are marked with
4529 @code{catch-clause}.
4531 @ssindex do-while-closure
4532 The @code{while} construct on line 14 that closes a @code{do}
4533 conditional is given the special syntax @code{do-while-closure} if it
4534 appears on a line by itself. Note that if the @code{while} appeared on
4535 the same line as the preceding close brace, that line would still have
4536 @code{block-close} syntax.
4538 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4539 @node Switch Statement Symbols, Brace List Symbols, Conditional Construct Symbols, Syntactic Symbols
4540 @comment node-name, next, previous, up
4541 @subsection Switch Statement Symbols
4542 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4544 Switch statements have their own set of syntactic symbols. Here's an
4548 1: void spam( enum Ingredient i )
4555 8: drink_some_water();
4567 @ssindex statement-case-intro
4568 @ssindex statement-case-open
4569 Here, lines 4, 7, and 10 are all assigned @code{case-label} syntax,
4570 while lines 5 and 8 are assigned @code{statement-case-intro}. Line 11
4571 is treated slightly differently since it contains a brace that opens a
4572 block --- it is given @code{statement-case-open} syntax.
4574 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4575 @node Brace List Symbols, External Scope Symbols, Switch Statement Symbols, Syntactic Symbols
4576 @comment node-name, next, previous, up
4577 @subsection Brace List Symbols
4578 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4581 There are a set of syntactic symbols that are used to recognize
4582 constructs inside of brace lists. A brace list is defined as an
4583 @code{enum} or aggregate initializer list, such as might statically
4584 initialize an array of structs. The three special aggregate constructs
4585 in Pike, @code{(@{ @})}, @code{([ ])} and @code{(< >)}, are treated as
4586 brace lists too. An example:
4589 1: static char* ingredients[] =
4597 @ssindex brace-list-open
4598 @ssindex brace-list-intro
4599 @ssindex brace-list-close
4600 @ssindex brace-list-entry
4601 Following convention, line 2 in this example is assigned
4602 @code{brace-list-open} syntax, and line 3 is assigned
4603 @code{brace-list-intro} syntax. Likewise, line 6 is assigned
4604 @code{brace-list-close} syntax. Lines 4 and 5 however, are assigned
4605 @code{brace-list-entry} syntax, as would all subsequent lines in this
4608 @ssindex brace-entry-open
4609 Your static initializer might be initializing nested structures, for
4613 1: struct intpairs[] =
4626 Here, you've already seen the analysis of lines 1, 2, 3, and 11. On
4627 line 4, things get interesting; this line is assigned
4628 @code{brace-entry-open} syntactic symbol because it's a bracelist entry
4629 line that starts with an open brace. Lines 5 and 6 (and line 9) are
4630 pretty standard, and line 7 is a @code{brace-list-close} as you'd
4631 expect. Once again, line 8 is assigned as @code{brace-entry-open} as is
4634 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4635 @node External Scope Symbols, Paren List Symbols, Brace List Symbols, Syntactic Symbols
4636 @comment node-name, next, previous, up
4637 @subsection External Scope Symbols
4638 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4640 External language definition blocks also have their own syntactic
4641 symbols. In this example:
4646 3: int thing_one( int );
4647 4: int thing_two( double );
4651 @ssindex extern-lang-open
4652 @ssindex extern-lang-close
4653 @ssindex inextern-lang
4656 line 2 is given the @code{extern-lang-open} syntax, while line 5 is given
4657 the @code{extern-lang-close} syntax. The analysis for line 3 yields:
4660 ((inextern-lang) (topmost-intro 14))
4664 where @code{inextern-lang} is a modifier similar in purpose to
4667 There are various other top level blocks like @code{extern}, and they
4668 are all treated in the same way except that the symbols are named after
4669 the keyword that introduces the block. E.g. C++ namespace blocks get
4670 the three symbols @code{namespace-open}, @code{namespace-close} and
4671 @code{innamespace}. The currently recognized top level blocks are:
4674 @item @code{extern-lang-open}, @code{extern-lang-close}, @code{inextern-lang}
4675 @code{extern} blocks in C and C++.@footnote{These should logically be
4676 named @code{extern-open}, @code{extern-close} and @code{inextern}, but
4677 that isn't the case for historical reasons.}
4679 @item @code{namespace-open}, @code{namespace-close}, @code{innamespace}
4680 @ssindex namespace-open
4681 @ssindex namespace-close
4682 @ssindex innamespace
4683 @code{namespace} blocks in C++.
4685 @item @code{module-open}, @code{module-close}, @code{inmodule}
4686 @ssindex module-open
4687 @ssindex module-close
4689 @code{module} blocks in CORBA IDL.
4691 @item @code{composition-open}, @code{composition-close}, @code{incomposition}
4692 @ssindex composition-open
4693 @ssindex composition-close
4694 @ssindex incomposition
4695 @code{composition} blocks in CORBA CIDL.
4698 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4699 @node Paren List Symbols, Literal Symbols, External Scope Symbols, Syntactic Symbols
4700 @comment node-name, next, previous, up
4701 @subsection Parenthesis (Argument) List Symbols
4702 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4704 A number of syntactic symbols are associated with parenthesis lists,
4705 a.k.a argument lists, as found in function declarations and function
4706 calls. This example illustrates these:
4709 1: void a_function( int line1,
4712 4: void a_longer_function(
4717 9: void call_them( int line1, int line2 )
4724 16: a_longer_function( line1,
4729 @ssindex arglist-intro
4730 @ssindex arglist-close
4731 Lines 5 and 12 are assigned @code{arglist-intro} syntax since they are
4732 the first line following the open parenthesis, and lines 7 and 14 are
4733 assigned @code{arglist-close} syntax since they contain the parenthesis
4734 that closes the argument list.
4736 @ssindex arglist-cont-nonempty
4737 @ssindex arglist-cont
4738 Lines that continue argument lists can be assigned one of two syntactic
4739 symbols. For example, Lines 2 and 17
4740 are assigned @code{arglist-cont-nonempty} syntax. What this means
4741 is that they continue an argument list, but that the line containing the
4742 parenthesis that opens the list is @emph{not empty} following the open
4743 parenthesis. Contrast this against lines 6 and 13 which are assigned
4744 @code{arglist-cont} syntax. This is because the parenthesis that opens
4745 their argument lists is the last character on that line.
4747 Syntactic elements with @code{arglist-intro},
4748 @code{arglist-cont-nonempty}, and @code{arglist-close} contain two
4749 buffer positions: the anchor position (the beginning of the
4750 declaration or statement) and the position of the open parenthesis.
4751 The latter position can be used in a line-up function (@pxref{Line-Up
4754 Note that there is no @code{arglist-open} syntax. This is because any
4755 parenthesis that opens an argument list, appearing on a separate line,
4756 is assigned the @code{statement-cont} syntax instead.
4758 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4759 @node Literal Symbols, Multiline Macro Symbols, Paren List Symbols, Syntactic Symbols
4760 @comment node-name, next, previous, up
4761 @subsection Comment String Label and Macro Symbols
4762 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4764 A few miscellaneous syntactic symbols that haven't been previously
4765 covered are illustrated by this C++ example:
4768 1: void Bass::play( int volume )
4771 4: /* this line starts a multiline
4772 5: * comment. This line should get `c' syntax */
4774 7: char* a_multiline_string = "This line starts a multiline \
4775 8: string. This line should get `string' syntax.";
4783 16: cout << "I played "
4789 The lines to note in this example include:
4793 @ssindex func-decl-cont
4794 Line 2 is assigned the @code{func-decl-cont} syntax.
4797 @ssindex comment-intro
4798 Line 4 is assigned both @code{defun-block-intro} @emph{and}
4799 @code{comment-intro} syntax. A syntactic element with
4800 @code{comment-intro} has no anchor point --- It is always accompanied
4801 by another syntactic element which does have one.
4805 Line 5 is assigned @code{c} syntax.
4808 @cindex syntactic whitespace
4809 Line 6 which, even though it contains nothing but whitespace, is
4810 assigned @code{defun-block-intro}. Note that the appearance of the
4811 comment on lines 4 and 5 do not cause line 6 to be assigned
4812 @code{statement} syntax because comments are considered to be
4813 @dfn{syntactic whitespace}, which are ignored when analyzing
4818 Line 8 is assigned @code{string} syntax.
4822 Line 10 is assigned @code{label} syntax.
4826 Line 11 is assigned @code{block-open} as well as @code{statement}
4827 syntax. A @code{block-open} syntactic element doesn't have an anchor
4828 position, since it always appears with another syntactic element which
4833 Lines 12 and 14 are assigned @code{cpp-macro} syntax in addition to the
4834 normal syntactic symbols (@code{statement-block-intro} and
4835 @code{statement}, respectively). Normally @code{cpp-macro} is
4836 configured to cancel out the normal syntactic context to make all
4837 preprocessor directives stick to the first column, but that's easily
4838 changed if you want preprocessor directives to be indented like the rest
4839 of the code. Like @code{comment-intro}, a syntactic element with
4840 @code{cpp-macro} doesn't contain an anchor position.
4844 Line 17 is assigned @code{stream-op} syntax.
4847 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4848 @node Multiline Macro Symbols, Objective-C Method Symbols, Literal Symbols, Syntactic Symbols
4849 @comment node-name, next, previous, up
4850 @subsection Multiline Macro Symbols
4851 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4853 @cindex multiline macros
4854 @cindex syntactic whitespace
4855 @ssindex cpp-define-intro
4856 @ssindex cpp-macro-cont
4857 Multiline preprocessor macro definitions are normally handled just like
4858 other code, i.e. the lines inside them are indented according to the
4859 syntactic analysis of the preceding lines inside the macro. The first
4860 line inside a macro definition (i.e. the line after the starting line of
4861 the cpp directive itself) gets @code{cpp-define-intro}. In this example:
4864 1: #define LIST_LOOP(cons, listp) \
4865 2: for (cons = listp; !NILP (cons); cons = XCDR (cons)) \
4866 3: if (!CONSP (cons)) \
4867 4: signal_error ("Invalid list format", listp); \
4872 line 1 is given the syntactic symbol @code{cpp-macro}. The first line
4873 of a cpp directive is always given that symbol. Line 2 is given
4874 @code{cpp-define-intro}, so that you can give the macro body as a whole
4875 some extra indentation. Lines 3 through 5 are then analyzed as normal
4876 code, i.e. @code{substatement} on lines 3 and 4, and @code{else-clause}
4879 The syntactic analysis inside macros can be turned off with
4880 @code{c-syntactic-indentation-in-macros} (@pxref{Custom Macros}). In
4881 that case, lines 2 through 5 would all be given @code{cpp-macro-cont}
4882 with an anchor position pointing to the @code{#} which starts the cpp
4883 directive@footnote{This is how @ccmode{} 5.28 and earlier analyzed
4886 @xref{Custom Macros}, for more info about the treatment of macros.
4888 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4889 @node Objective-C Method Symbols, Java Symbols, Multiline Macro Symbols, Syntactic Symbols
4890 @comment node-name, next, previous, up
4891 @subsection Objective-C Method Symbols
4892 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4894 In Objective-C buffers, there are three additional syntactic symbols
4895 assigned to various message calling constructs. Here's an example
4899 1: - (void)setDelegate:anObject
4902 4: [delegate masterWillRebind:self
4903 5: toDelegate:anObject
4904 6: withExtraStuff:stuff];
4908 @ssindex objc-method-intro
4909 @ssindex objc-method-args-cont
4910 @ssindex objc-method-call-cont
4911 Here, line 1 is assigned @code{objc-method-intro} syntax, and line 2 is
4912 assigned @code{objc-method-args-cont} syntax. Lines 5 and 6 are both
4913 assigned @code{objc-method-call-cont} syntax.
4915 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4916 @node Java Symbols, Statement Block Symbols, Objective-C Method Symbols, Syntactic Symbols
4917 @comment node-name, next, previous, up
4918 @subsection Java Symbols
4919 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4921 Java has a concept of anonymous classes which can look something like
4926 2: public void watch(Observable o) @{
4928 4: Observer obs = new Observer() @{
4929 5: public void update(Observable o, Object arg) @{
4930 6: history.addElement(arg);
4933 9: o.addObserver(obs);
4937 @ssindex inexpr-class
4938 The brace following the @code{new} operator opens the anonymous class.
4939 Lines 5 and 8 are assigned the @code{inexpr-class} syntax, besides the
4940 @code{inclass} symbol used in normal classes. Thus, the class will be
4941 indented just like a normal class, with the added indentation given to
4942 @code{inexpr-class}. An @code{inexpr-class} syntactic element doesn't
4943 have an anchor position.
4945 @ssindex annotation-top-cont
4946 @ssindex annotation-var-cont
4947 Line 2 is assigned the @code{annotation-top-cont} syntax, due to it being a
4948 continuation of a topmost introduction with an annotation symbol preceding
4949 the current line. Similarly, line 4 is assigned the @code{annotation-var-cont}
4950 syntax due to it being a continuation of a variable declaration where preceding
4951 the declaration is an annotation.
4953 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4954 @node Statement Block Symbols, K&R Symbols, Java Symbols, Syntactic Symbols
4955 @comment node-name, next, previous, up
4956 @subsection Statement Block Symbols
4957 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4959 There are a few occasions where a statement block might be used inside
4960 an expression. One is in C or C++ code using the gcc extension for
4965 2: int y = foo (); int z;
4966 3: if (y > 0) z = y; else z = - y;
4971 @ssindex inexpr-statement
4972 Lines 2 and 5 get the @code{inexpr-statement} syntax, besides the
4973 symbols they'd get in a normal block. Therefore, the indentation put on
4974 @code{inexpr-statement} is added to the normal statement block
4975 indentation. An @code{inexpr-statement} syntactic element doesn't
4976 contain an anchor position.
4978 In Pike code, there are a few other situations where blocks occur inside
4979 statements, as illustrated here:
4984 3: string s = map (backtrace()[-2][3..],
4988 7: return sprintf ("%t", arg);
4989 8: @}) * ", " + "\n";
4991 10: write (s + "\n");
4997 @ssindex lambda-intro-cont
4998 Lines 4 through 8 contain a lambda function, which @ccmode{} recognizes
4999 by the @code{lambda} keyword. If the function argument list is put
5000 on a line of its own, as in line 5, it gets the @code{lambda-intro-cont}
5001 syntax. The function body is handled as an inline method body, with the
5002 addition of the @code{inlambda} syntactic symbol. This means that line
5003 6 gets @code{inlambda} and @code{inline-open}, and line 8 gets
5004 @code{inline-close}@footnote{You might wonder why it doesn't get
5005 @code{inlambda} too. It's because the closing brace is relative to the
5006 opening brace, which stands on its own line in this example. If the
5007 opening brace was hanging on the previous line, then the closing brace
5008 would get the @code{inlambda} syntax too to be indented correctly.}.
5010 @ssindex inexpr-statement
5011 On line 9, @code{catch} is a special function taking a statement block
5012 as its argument. The block is handled as an in-expression statement
5013 with the @code{inexpr-statement} syntax, just like the gcc extended C
5014 example above. The other similar special function, @code{gauge}, is
5015 handled like this too.
5017 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5018 @node K&R Symbols, , Statement Block Symbols, Syntactic Symbols
5019 @comment node-name, next, previous, up
5020 @subsection K&R Symbols
5021 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5023 @ssindex knr-argdecl-intro
5024 @ssindex knr-argdecl
5025 Two other syntactic symbols can appear in old style, non-prototyped C
5026 code @footnote{a.k.a. K&R C, or Kernighan & Ritchie C}:
5029 1: int add_three_integers(a, b, c)
5034 6: return a + b + c;
5038 Here, line 2 is the first line in an argument declaration list and so is
5039 given the @code{knr-argdecl-intro} syntactic symbol. Subsequent lines
5040 (i.e. lines 3 and 4 in this example), are given @code{knr-argdecl}
5044 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5045 @node Indentation Calculation, , Syntactic Symbols, Indentation Engine Basics
5046 @comment node-name, next, previous, up
5047 @section Indentation Calculation
5049 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5051 Indentation for a line is calculated from the syntactic context
5052 (@pxref{Syntactic Analysis}).
5054 First, a buffer position is found whose column will be the base for the
5055 indentation calculation. It's the anchor position in the first
5056 syntactic element that provides one that is used. If no syntactic
5057 element has an anchor position then column zero is used.
5059 Second, the syntactic symbols in each syntactic element are looked up
5060 in the @code{c-offsets-alist} style variable
5061 (@pxref{c-offsets-alist}), which is an association list of syntactic
5062 symbols and the offsets to apply for those symbols. These offsets are
5063 added together with the base column to produce the new indentation
5066 Let's use our two code examples above to see how this works. Here is
5067 our first example again:
5070 1: void swap( int& a, int& b )
5078 Let's say point is on line 3 and we hit the @key{TAB} key to reindent
5079 the line. The syntactic context for that line is:
5082 ((defun-block-intro 29))
5086 Since buffer position 29 is the first and only anchor position in the
5087 list, @ccmode{} goes there and asks for the current column. This brace
5088 is in column zero, so @ccmode{} uses @samp{0} as the base column.
5090 Next, @ccmode{} looks up @code{defun-block-intro} in the
5091 @code{c-offsets-alist} style variable. Let's say it finds the value
5092 @samp{4}; it adds this to the base column @samp{0}, yielding a running
5093 total indentation of 4 spaces.
5095 Since there is only one syntactic element on the list for this line,
5096 indentation calculation is complete, and the total indentation for the
5099 Here's another example:
5102 1: int add( int val, int incr, int doit )
5106 5: return( val + incr );
5112 If we were to hit @kbd{TAB} on line 4 in the above example, the same
5113 basic process is performed, despite the differences in the syntactic
5114 context. The context for this line is:
5117 ((substatement-open 46))
5120 Here, @ccmode{} goes to buffer position 46, which is the @samp{i} in
5121 @code{if} on line 3. This character is in the fourth column on that
5122 line so the base column is @samp{4}. Then @ccmode{} looks up the
5123 @code{substatement-open} symbol in @code{c-offsets-alist}. Let's say it
5124 finds the value @samp{4}. It's added with the base column and yields an
5125 indentation for the line of 8 spaces.
5129 Actually, it's a bit more complicated than that since the entries on
5130 @code{c-offsets-alist} can be much more than plain offsets.
5131 @xref{c-offsets-alist}, for the full story.
5133 Anyway, the mode usually just does The Right Thing without you having to
5134 think about it in this much detail. But when customizing indentation,
5135 it's helpful to understand the general indentation model being used.
5137 As you configure @ccmode{}, you might want to set the variable
5138 @code{c-echo-syntactic-information-p} to non-@code{nil} so that the
5139 syntactic context and calculated offset always is echoed in the
5140 minibuffer when you hit @kbd{TAB}.
5143 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5144 @node Customizing Indentation, Custom Macros, Indentation Engine Basics, Top
5145 @comment node-name, next, previous, up
5146 @chapter Customizing Indentation
5147 @cindex customization, indentation
5149 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5151 The principal variable for customizing indentation is the style
5152 variable @code{c-offsets-alist}, which gives an @dfn{offset} (an
5153 indentation rule) for each syntactic symbol. Its structure and
5154 semantics are completely described in @ref{c-offsets-alist}. The
5155 various ways you can set the variable, including the use of the
5156 @ccmode{} style system, are described in @ref{Config Basics} and its
5157 sections, in particular @ref{Style Variables}.
5159 The simplest and most used kind of ``offset'' setting in
5160 @code{c-offsets-alist} is in terms of multiples of
5161 @code{c-basic-offset}:
5163 @defopt c-basic-offset
5164 @vindex basic-offset (c-)
5165 This style variable holds the basic offset between indentation levels.
5166 It's factory default is 4, but all the built-in styles set it
5167 themselves, to some value between 2 (for @code{gnu} style) and 8 (for
5168 @code{bsd}, @code{linux}, and @code{python} styles).
5171 The most flexible ``offset'' setting you can make in
5172 @code{c-offsets-alist} is a line-up function (or even a list of them),
5173 either one supplied by @ccmode{} (@pxref{Line-Up Functions}) or one
5174 you write yourself (@pxref{Custom Line-Up}).
5176 Finally, in @ref{Other Indentation} you'll find the tool of last
5177 resort: a hook which is called after a line has been indented. You
5178 can install functions here to make ad-hoc adjustments to any line's
5183 * Interactive Customization::
5184 * Line-Up Functions::
5186 * Other Indentation::
5190 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5191 @node c-offsets-alist, Interactive Customization, Customizing Indentation, Customizing Indentation
5192 @comment node-name, next, previous, up
5193 @section c-offsets-alist
5194 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5196 This section explains the structure and semantics of the style
5197 variable @code{c-offsets-alist}, the principal variable for configuring
5198 indentation. Details of how to set it up, and its relationship to
5199 @ccmode{}'s style system are given in @ref{Style Variables}.
5201 @defopt c-offsets-alist
5202 @vindex offsets-alist (c-)
5203 This is an alist which associates an offset with each syntactic
5204 symbol. This @dfn{offset} is a rule specifying how to indent a line
5205 whose syntactic context matches the symbol. @xref{Syntactic
5208 Note that the buffer-local binding of this alist in a @ccmode{} buffer
5209 contains an entry for @emph{every} syntactic symbol. Its global
5210 binding and its settings within style specifications usually contain
5211 only a few entries. @xref{Style Variables}.
5213 The offset specification associated with any particular syntactic
5214 symbol can be an integer, a variable name, a vector, a function or
5215 lambda expression, a list, or one of the following special symbols:
5216 @code{+}, @code{-}, @code{++}, @code{--}, @code{*}, or @code{/}. The
5217 meanings of these values are described in detail below.
5219 Here is an example fragment of a @code{c-offsets-alist}, showing some
5220 of these kinds of offsets:
5226 (topmost-intro-cont . c-lineup-topmost-intro-cont)
5227 (statement-block-intro . (add c-lineup-whitesmith-in-block
5228 c-indent-multi-line-block))
5234 @deffn Command c-set-offset (@kbd{C-c C-o})
5235 @findex set-offset (c-)
5237 This command changes the entry for a syntactic symbol in the current
5238 binding of @code{c-offsets-alist}, or it inserts a new entry if there
5239 isn't already one for that syntactic symbol.
5241 You can use @code{c-set-offset} interactively within a @ccmode{}
5242 buffer to make experimental changes to your indentation settings.
5243 @kbd{C-c C-o} prompts you for the syntactic symbol to change
5244 (defaulting to that of the current line) and the new offset
5245 (defaulting to the current offset).
5247 @code{c-set-offset} takes two arguments when used programmatically:
5248 @var{symbol}, the syntactic element symbol to change and @var{offset},
5249 the new offset for that syntactic element. You can call the command
5250 in your @file{.emacs} to change the global binding of
5251 @code{c-offsets-alist} (@pxref{Style Variables}); you can use it in a
5252 hook function to make changes from the current style. @ccmode{}
5253 itself uses this function when initializing styles.
5256 @cindex offset specification
5257 The ``offset specifications'' in @code{c-offsets-alist} can be any of
5262 The integer specifies a relative offset. All relative
5263 offsets@footnote{The syntactic context @code{@w{((defun-block-intro
5264 2724) (comment-intro))}} would likely have two relative offsets.} will
5265 be added together and used to calculate the indentation relative to an
5266 anchor position earlier in the buffer. @xref{Indentation
5267 Calculation}, for details. Most of the time, it's probably better to
5268 use one of the special symbols like @code{+} than an integer (apart
5271 @item One of the symbols @code{+}, @code{-}, @code{++}, @code{--}, @code{*}, or @code{/}
5272 These special symbols describe a relative offset in multiples of
5273 @code{c-basic-offset}:
5275 By defining a style's indentation in terms of @code{c-basic-offset},
5276 you can change the amount of whitespace given to an indentation level
5277 while maintaining the same basic shape of your code. Here are the
5278 values that the special symbols correspond to:
5282 @code{c-basic-offset} times 1
5284 @code{c-basic-offset} times -1
5286 @code{c-basic-offset} times 2
5288 @code{c-basic-offset} times -2
5290 @code{c-basic-offset} times 0.5
5292 @code{c-basic-offset} times -0.5
5296 The first element of the vector, an integer, sets the absolute
5297 indentation column. This will override any previously calculated
5298 indentation, but won't override relative indentation calculated from
5299 syntactic elements later on in the syntactic context of the line being
5300 indented. @xref{Indentation Calculation}. Any elements in the vector
5301 beyond the first will be ignored.
5303 @item A function or lambda expression
5304 The function will be called and its return value will in turn be
5305 evaluated as an offset specification. Functions are useful when more
5306 context than just the syntactic symbol is needed to get the desired
5307 indentation. @xref{Line-Up Functions}, and @ref{Custom Line-Up}, for
5310 @item A symbol with a variable binding
5311 If the symbol also has a function binding, the function takes
5312 precedence over the variable. Otherwise the value of the variable is
5313 used. It must be an integer (which is used as relative offset) or a
5314 vector (an absolute offset).
5317 The offset can also be a list containing several offset
5318 specifications; these are evaluated recursively and combined. A list
5319 is typically only useful when some of the offsets are line-up
5320 functions. A common strategy is calling a sequence of functions in
5321 turn until one of them recognizes that it is appropriate for the
5322 source line and returns a non-@code{nil} value.
5324 @code{nil} values are always ignored when the offsets are combined.
5325 The first element of the list specifies the method of combining the
5326 non-@code{nil} offsets from the remaining elements:
5330 Use the first offset that doesn't evaluate to @code{nil}. Subsequent
5331 elements of the list don't get evaluated.
5333 Use the minimum of all the offsets. All must be either relative or
5334 absolute - they can't be mixed.
5336 Use the maximum of all the offsets. All must be either relative or
5337 absolute - they can't be mixed.
5339 Add all the evaluated offsets together. Exactly one of them may be
5340 absolute, in which case the result is absolute. Any relative offsets
5341 that preceded the absolute one in the list will be ignored in that case.
5344 As a compatibility measure, if the first element is none of the above
5345 then it too will be taken as an offset specification and the whole list
5346 will be combined according to the method @code{first}.
5349 @vindex c-strict-syntax-p
5350 @vindex strict-syntax-p (c-)
5351 If an offset specification evaluates to @code{nil}, then a relative
5352 offset of 0 (zero) is used@footnote{There is however a variable
5353 @code{c-strict-syntax-p} that when set to non-@code{nil} will cause an
5354 error to be signaled in that case. It's now considered obsolete since
5355 it doesn't work well with some of the alignment functions that return
5356 @code{nil} instead of zero. You should therefore leave
5357 @code{c-strict-syntax-p} set to @code{nil}.}.
5359 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5360 @node Interactive Customization, Line-Up Functions, c-offsets-alist, Customizing Indentation
5361 @comment node-name, next, previous, up
5362 @section Interactive Customization
5363 @cindex customization, interactive
5364 @cindex interactive customization
5365 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5367 As an example of how to customize indentation, let's change the
5368 style of this example@footnote{In this and subsequent examples, the
5369 original code is formatted using the @samp{gnu} style unless otherwise
5370 indicated. @xref{Styles}.}:
5374 1: int add( int val, int incr, int doit )
5378 5: return( val + incr );
5390 1: int add( int val, int incr, int doit )
5394 5: return( val + incr );
5401 In other words, we want to change the indentation of braces that open a
5402 block following a condition so that the braces line up under the
5403 conditional, instead of being indented. Notice that the construct we
5404 want to change starts on line 4. To change the indentation of a line,
5405 we need to see which syntactic symbols affect the offset calculations
5406 for that line. Hitting @kbd{C-c C-s} on line 4 yields:
5409 ((substatement-open 44))
5413 so we know that to change the offset of the open brace, we need to
5414 change the indentation for the @code{substatement-open} syntactic
5417 To do this interactively, just hit @kbd{C-c C-o}. This prompts
5418 you for the syntactic symbol to change, providing a reasonable default.
5419 In this case, the default is @code{substatement-open}, which is just the
5420 syntactic symbol we want to change!
5422 After you hit return, @ccmode{} will then prompt you for the new
5423 offset value, with the old value as the default. The default in this
5424 case is @samp{+}, but we want no extra indentation so enter
5425 @samp{0} and @kbd{RET}. This will associate the offset 0 with the
5426 syntactic symbol @code{substatement-open}.
5428 To check your changes quickly, just hit @kbd{C-c C-q}
5429 (@code{c-indent-defun}) to reindent the entire function. The example
5430 should now look like:
5434 1: int add( int val, int incr, int doit )
5438 5: return( val + incr );
5445 Notice how just changing the open brace offset on line 4 is all we
5446 needed to do. Since the other affected lines are indented relative to
5447 line 4, they are automatically indented the way you'd expect. For more
5448 complicated examples, this might not always work. The general approach
5449 to take is to always start adjusting offsets for lines higher up in the
5450 file, then reindent and see if any following lines need further
5453 @c Move this bit to "Styles" (2005/10/7)
5454 @deffn Command c-set-offset symbol offset
5455 @findex set-offset (c-)
5457 This is the command bound to @kbd{C-c C-o}. It provides a convenient
5458 way to set offsets on @code{c-offsets-alist} both interactively (see
5459 the example above) and from your mode hook.
5461 It takes two arguments when used programmatically: @var{symbol} is the
5462 syntactic element symbol to change and @var{offset} is the new offset
5463 for that syntactic element.
5465 @c End of MOVE THIS BIT.
5467 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5468 @node Line-Up Functions, Custom Line-Up, Interactive Customization, Customizing Indentation
5469 @comment node-name, next, previous, up
5470 @section Line-Up Functions
5471 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5473 @cindex line-up function
5474 @cindex indentation function
5475 Often there are cases when a simple offset setting on a syntactic
5476 symbol isn't enough to get the desired indentation---for example, you
5477 might want to line up a closing parenthesis with the matching opening
5478 one rather than indenting relative to its ``anchor point''. @ccmode{}
5479 provides this flexibility with @dfn{line-up functions}.
5481 The way you associate a line-up function with a syntactic symbol is
5482 described in @ref{c-offsets-alist}. @ccmode{} comes with many
5483 predefined line-up functions for common situations. If none of these
5484 does what you want, you can write your own. @xref{Custom Line-Up}.
5485 Sometimes, it is easier to tweak the standard indentation by adding a
5486 function to @code{c-special-indent-hook} (@pxref{Other Indentation}).
5488 The line-up functions haven't been adapted for AWK buffers or tested
5489 with them. Some of them might work serendipitously. There shouldn't be
5490 any problems writing custom line-up functions for AWK mode.
5492 The calling convention for line-up functions is described fully in
5493 @ref{Custom Line-Up}. Roughly speaking, the return value is either an
5494 offset itself (such as @code{+} or @code{[0]}) or it's @code{nil},
5495 meaning ``this function is inappropriate in this case - try a
5496 different one''. @xref{c-offsets-alist}.
5498 The subsections below describe all the standard line-up functions,
5499 categorized by the sort of token the lining-up centers around. For
5500 each of these functions there is a ``works with'' list that indicates
5501 which syntactic symbols the function is intended to be used with.
5504 @emph{Works with:@ }
5513 @macro sssTBasicOffset
5514 <--> @i{c-basic-offset}@c
5517 @macro sssTsssTBasicOffset
5518 <--><--> @i{c-basic-offset}@c
5525 @c The TeX backend seems to insert extra spaces around the argument. :P
5534 * Brace/Paren Line-Up::
5536 * Operator Line-Up::
5541 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5542 @node Brace/Paren Line-Up, List Line-Up, Line-Up Functions, Line-Up Functions
5543 @comment node-name, next, previous, up
5544 @subsection Brace and Parenthesis Line-Up Functions
5545 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5547 The line-up functions here calculate the indentation for braces,
5548 parentheses and statements within brace blocks.
5550 @defun c-lineup-close-paren
5551 @findex lineup-close-paren (c-)
5552 Line up the closing paren under its corresponding open paren if the
5553 open paren is followed by code. If the open paren ends its line, no
5554 indentation is added. E.g:
5560 ) @hereFn{c-lineup-close-paren}
5571 ) @hereFn{c-lineup-close-paren}
5575 As a special case, if a brace block is opened at the same line as the
5576 open parenthesis of the argument list, the indentation is
5577 @code{c-basic-offset} instead of the open paren column. See
5578 @code{c-lineup-arglist} for further discussion of this ``DWIM'' measure.
5580 @workswith All @code{*-close} symbols.
5583 @comment ------------------------------------------------------------
5585 @anchor{c-lineup-arglist-close-under-paren}
5586 @defun c-lineup-arglist-close-under-paren
5587 @findex lineup-arglist-close-under-paren (c-)
5588 Set your @code{arglist-close} syntactic symbol to this line-up function
5589 so that parentheses that close argument lists will line up under the
5590 parenthesis that opened the argument list. It can also be used with
5591 @code{arglist-cont} and @code{arglist-cont-nonempty} to line up all
5592 lines inside a parenthesis under the open paren.
5594 As a special case, if a brace block is opened at the same line as the
5595 open parenthesis of the argument list, the indentation is
5596 @code{c-basic-offset} only. See @code{c-lineup-arglist} for further
5597 discussion of this ``DWIM'' measure.
5599 @workswith Almost all symbols, but are typically most useful on
5600 @code{arglist-close}, @code{brace-list-close}, @code{arglist-cont} and
5601 @code{arglist-cont-nonempty}.
5604 @comment ------------------------------------------------------------
5606 @defun c-indent-one-line-block
5607 @findex indent-one-line-block (c-)
5608 Indent a one line block @code{c-basic-offset} extra. E.g:
5613 @{m+=n; n=0;@} @hereFn{c-indent-one-line-block}
5624 @{ @hereFn{c-indent-one-line-block}
5630 The block may be surrounded by any kind of parenthesis characters.
5631 @code{nil} is returned if the line doesn't start with a one line block,
5632 which makes the function usable in list expressions.
5634 @workswith Almost all syntactic symbols, but most useful on the
5635 @code{-open} symbols.
5638 @comment ------------------------------------------------------------
5640 @defun c-indent-multi-line-block
5641 @findex indent-multi-line-block (c-)
5642 Indent a multiline block @code{c-basic-offset} extra. E.g:
5648 @{17@}, @hereFn{c-indent-multi-line-block}
5659 @{ @hereFn{c-indent-multi-line-block}
5666 The block may be surrounded by any kind of parenthesis characters.
5667 @code{nil} is returned if the line doesn't start with a multiline
5668 block, which makes the function usable in list expressions.
5670 @workswith Almost all syntactic symbols, but most useful on the
5671 @code{-open} symbols.
5674 @comment ------------------------------------------------------------
5676 @defun c-lineup-runin-statements
5677 @findex lineup-runin-statements (c-)
5678 Line up statements for coding standards which place the first statement
5679 in a block on the same line as the block opening brace@footnote{Run-in
5680 style doesn't really work too well. You might need to write your own
5681 custom line-up functions to better support this style.}. E.g:
5687 return 0; @hereFn{c-lineup-runin-statements}
5692 If there is no statement after the opening brace to align with,
5693 @code{nil} is returned. This makes the function usable in list
5696 @workswith The @code{statement} syntactic symbol.
5699 @comment ------------------------------------------------------------
5701 @defun c-lineup-inexpr-block
5702 @findex lineup-inexpr-block (c-)
5703 This can be used with the in-expression block symbols to indent the
5704 whole block to the column where the construct is started. E.g. for Java
5705 anonymous classes, this lines up the class under the @samp{new} keyword,
5706 and in Pike it lines up the lambda function body under the @samp{lambda}
5707 keyword. Returns @code{nil} if the block isn't part of such a
5710 @workswith @code{inlambda}, @code{inexpr-statement},
5711 @code{inexpr-class}.
5714 @comment ------------------------------------------------------------
5716 @defun c-lineup-after-whitesmith-blocks
5717 @findex lineup-after-whitesmith-blocks (c-)
5718 Compensate for Whitesmith style indentation of blocks. Due to the way
5719 @ccmode{} calculates anchor positions for normal lines inside blocks,
5720 this function is necessary for those lines to get correct Whitesmith
5721 style indentation. Consider the following examples:
5728 x; @hereFn{c-lineup-after-whitesmith-blocks}
5739 x; @hereFn{c-lineup-after-whitesmith-blocks}
5743 The fact that the line with @code{x} is preceded by a Whitesmith style
5744 indented block in the latter case and not the first should not affect
5745 its indentation. But since CC Mode in cases like this uses the
5746 indentation of the preceding statement as anchor position, the @code{x}
5747 would in the second case be indented too much if the offset for
5748 @code{statement} was set simply to zero.
5750 This lineup function corrects for this situation by detecting if the
5751 anchor position is at an open paren character. In that case, it instead
5752 indents relative to the surrounding block just like
5753 @code{c-lineup-whitesmith-in-block}.
5755 @workswith @code{brace-list-entry}, @code{brace-entry-open},
5756 @code{statement}, @code{arglist-cont}.
5759 @comment ------------------------------------------------------------
5761 @defun c-lineup-whitesmith-in-block
5762 @findex lineup-whitesmith-in-block (c-)
5763 Line up lines inside a block in Whitesmith style. It's done in a way
5764 that works both when the opening brace hangs and when it doesn't. E.g:
5770 foo; @hereFn{c-lineup-whitesmith-in-block}
5781 foo; @hereFn{c-lineup-whitesmith-in-block}
5787 In the first case the indentation is kept unchanged, in the second
5788 @code{c-basic-offset} is added.
5790 @workswith @code{defun-close}, @code{defun-block-intro},
5791 @code{inline-close}, @code{block-close}, @code{brace-list-close},
5792 @code{brace-list-intro}, @code{statement-block-intro},
5793 @code{arglist-intro}, @code{arglist-cont-nonempty},
5794 @code{arglist-close}, and all @code{in*} symbols, e.g. @code{inclass}
5795 and @code{inextern-lang}.
5798 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5799 @node List Line-Up, Operator Line-Up, Brace/Paren Line-Up, Line-Up Functions
5800 @comment node-name, next, previous, up
5801 @subsection List Line-Up Functions
5802 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5804 The line-up functions here calculate the indentation for lines which
5805 form lists of items, usually separated by commas.
5807 The function @ref{c-lineup-arglist-close-under-paren}, which is mainly
5808 for indenting a close parenthesis, is also useful for the lines
5809 contained within parentheses.
5811 @defun c-lineup-arglist
5812 @findex lineup-arglist (c-)
5813 Line up the current argument line under the first argument.
5815 As a special case, if an argument on the same line as the open
5816 parenthesis starts with a brace block opener, the indentation is
5817 @code{c-basic-offset} only. This is intended as a ``DWIM'' measure in
5818 cases like macros that contain statement blocks, e.g:
5822 A_VERY_LONG_MACRO_NAME (@{
5823 some (code, with + long, lines * in[it]);
5829 This is motivated partly because it's more in line with how code
5830 blocks are handled, and partly since it approximates the behavior of
5831 earlier CC Mode versions, which due to inaccurate analysis tended to
5832 indent such cases this way.
5834 @workswith @code{arglist-cont-nonempty}, @code{arglist-close}.
5837 @comment ------------------------------------------------------------
5839 @defun c-lineup-arglist-intro-after-paren
5840 @findex lineup-arglist-intro-after-paren (c-)
5841 Line up a line to just after the open paren of the surrounding paren or
5844 @workswith @code{defun-block-intro}, @code{brace-list-intro},
5845 @code{statement-block-intro}, @code{statement-case-intro},
5846 @code{arglist-intro}.
5849 @comment ------------------------------------------------------------
5851 @defun c-lineup-multi-inher
5852 @findex lineup-multi-inher (c-)
5853 Line up the classes in C++ multiple inheritance clauses and member
5854 initializers under each other. E.g:
5858 Foo::Foo (int a, int b):
5860 Bar (b) @hereFn{c-lineup-multi-inher}
5871 public Bar @hereFn{c-lineup-multi-inher}
5880 Foo::Foo (int a, int b)
5882 , Bar (b) @hereFn{c-lineup-multi-inher}
5886 @workswith @code{inher-cont}, @code{member-init-cont}.
5889 @comment ------------------------------------------------------------
5891 @defun c-lineup-java-inher
5892 @findex lineup-java-inher (c-)
5893 Line up Java implements and extends declarations. If class names
5894 follow on the same line as the @samp{implements}/@samp{extends}
5895 keyword, they are lined up under each other. Otherwise, they are
5896 indented by adding @code{c-basic-offset} to the column of the keyword.
5903 Bar @hereFn{c-lineup-java-inher}
5915 Bar @hereFn{c-lineup-java-inher}
5919 @workswith @code{inher-cont}.
5922 @comment ------------------------------------------------------------
5924 @defun c-lineup-java-throws
5925 @findex lineup-java-throws (c-)
5926 Line up Java throws declarations. If exception names follow on the
5927 same line as the throws keyword, they are lined up under each other.
5928 Otherwise, they are indented by adding @code{c-basic-offset} to the
5929 column of the @samp{throws} keyword. The @samp{throws} keyword itself
5930 is also indented by @code{c-basic-offset} from the function declaration
5931 start if it doesn't hang. E.g:
5936 throws @hereFn{c-lineup-java-throws}
5937 Bar @hereFn{c-lineup-java-throws}
5938 @sssTsssTBasicOffset{}
5947 int foo() throws Cyphr,
5948 Bar, @hereFn{c-lineup-java-throws}
5949 Vlod @hereFn{c-lineup-java-throws}
5953 @workswith @code{func-decl-cont}.
5956 @comment ------------------------------------------------------------
5958 @defun c-lineup-template-args
5959 @findex lineup-template-args (c-)
5960 Line up the arguments of a template argument list under each other, but
5961 only in the case where the first argument is on the same line as the
5964 To allow this function to be used in a list expression, @code{nil} is
5965 returned if there's no template argument on the first line.
5967 @workswith @code{template-args-cont}.
5970 @comment ------------------------------------------------------------
5972 @defun c-lineup-ObjC-method-call
5973 @findex lineup-ObjC-method-call (c-)
5974 For Objective-C code, line up selector args as Emacs Lisp mode does
5975 with function args: go to the position right after the message receiver,
5976 and if you are at the end of the line, indent the current line
5977 c-basic-offset columns from the opening bracket; otherwise you are
5978 looking at the first character of the first method call argument, so
5979 lineup the current line with it.
5981 @workswith @code{objc-method-call-cont}.
5984 @comment ------------------------------------------------------------
5986 @defun c-lineup-ObjC-method-args
5987 @findex lineup-ObjC-method-args (c-)
5988 For Objective-C code, line up the colons that separate args. The colon
5989 on the current line is aligned with the one on the first line.
5991 @workswith @code{objc-method-args-cont}.
5994 @comment ------------------------------------------------------------
5996 @defun c-lineup-ObjC-method-args-2
5997 @findex lineup-ObjC-method-args-2 (c-)
5998 Similar to @code{c-lineup-ObjC-method-args} but lines up the colon on
5999 the current line with the colon on the previous line.
6001 @workswith @code{objc-method-args-cont}.
6004 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6005 @node Operator Line-Up, Comment Line-Up, List Line-Up, Line-Up Functions
6006 @comment node-name, next, previous, up
6007 @subsection Operator Line-Up Functions
6008 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6010 The line-up functions here calculate the indentation for lines which
6011 start with an operator, by lining it up with something on the previous
6014 @defun c-lineup-argcont
6015 @findex lineup-argcont (c-)
6016 Line up a continued argument. E.g:
6020 foo (xyz, aaa + bbb + ccc
6021 + ddd + eee + fff); @hereFn{c-lineup-argcont}
6025 Only continuation lines like this are touched, @code{nil} is returned on
6026 lines which are the start of an argument.
6028 Within a gcc @code{asm} block, @code{:} is recognized as an argument
6029 separator, but of course only between operand specifications, not in the
6030 expressions for the operands.
6032 @workswith @code{arglist-cont}, @code{arglist-cont-nonempty}.
6035 @comment ------------------------------------------------------------
6037 @defun c-lineup-arglist-operators
6038 @findex lineup-arglist-operators (c-)
6039 Line up lines starting with an infix operator under the open paren.
6040 Return @code{nil} on lines that don't start with an operator, to leave
6041 those cases to other line-up functions. Example:
6046 || at_limit (x, @hereFn{c-lineup-arglist-operators}
6047 list) @hereFn{c-lineup-arglist-operators@r{ returns nil}}
6052 Since this function doesn't do anything for lines without an infix
6053 operator you typically want to use it together with some other lineup
6054 settings, e.g. as follows (the @code{arglist-close} setting is just a
6055 suggestion to get a consistent style):
6058 (c-set-offset 'arglist-cont
6059 '(c-lineup-arglist-operators 0))
6060 (c-set-offset 'arglist-cont-nonempty
6061 '(c-lineup-arglist-operators c-lineup-arglist))
6062 (c-set-offset 'arglist-close
6063 '(c-lineup-arglist-close-under-paren))
6066 @workswith @code{arglist-cont}, @code{arglist-cont-nonempty}.
6069 @comment ------------------------------------------------------------
6071 @defun c-lineup-assignments
6072 @findex lineup-assignments (c-)
6073 Line up the current line after the assignment operator on the first line
6074 in the statement. If there isn't any, return nil to allow stacking with
6075 other line-up functions. If the current line contains an assignment
6076 operator too, try to align it with the first one.
6078 @workswith @code{topmost-intro-cont}, @code{statement-cont},
6079 @code{arglist-cont}, @code{arglist-cont-nonempty}.
6083 @comment ------------------------------------------------------------
6085 @defun c-lineup-math
6086 @findex lineup-math (c-)
6087 Like @code{c-lineup-assignments} but indent with @code{c-basic-offset}
6088 if no assignment operator was found on the first line. I.e. this
6089 function is the same as specifying a list @code{(c-lineup-assignments
6090 +)}. It's provided for compatibility with old configurations.
6092 @workswith @code{topmost-intro-cont}, @code{statement-cont},
6093 @code{arglist-cont}, @code{arglist-cont-nonempty}.
6096 @comment ------------------------------------------------------------
6098 @defun c-lineup-cascaded-calls
6099 @findex lineup-cascaded-calls (c-)
6100 Line up ``cascaded calls'' under each other. If the line begins with
6101 @code{->} or @code{.} and the preceding line ends with one or more
6102 function calls preceded by the same token, then the arrow is lined up
6103 with the first of those tokens. E.g:
6107 r = proc->add(17)->add(18)
6108 ->add(19) + @hereFn{c-lineup-cascaded-calls}
6109 offset; @hereFn{c-lineup-cascaded-calls@r{ (inactive)}}
6113 In any other situation @code{nil} is returned to allow use in list
6116 @workswith @code{topmost-intro-cont}, @code{statement-cont},
6117 @code{arglist-cont}, @code{arglist-cont-nonempty}.
6120 @comment ------------------------------------------------------------
6122 @defun c-lineup-streamop
6123 @findex lineup-streamop (c-)
6124 Line up C++ stream operators (i.e. @samp{<<} and @samp{>>}).
6126 @workswith @code{stream-op}.
6129 @comment ------------------------------------------------------------
6131 @defun c-lineup-string-cont
6132 @findex lineup-string-cont (c-)
6133 Line up a continued string under the one it continues. A continued
6134 string in this sense is where a string literal follows directly after
6139 result = prefix + "A message "
6140 "string."; @hereFn{c-lineup-string-cont}
6144 @code{nil} is returned in other situations, to allow stacking with other
6147 @workswith @code{topmost-intro-cont}, @code{statement-cont},
6148 @code{arglist-cont}, @code{arglist-cont-nonempty}.
6152 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6153 @node Comment Line-Up, Misc Line-Up, Operator Line-Up, Line-Up Functions
6154 @comment node-name, next, previous, up
6155 @subsection Comment Line-Up Functions
6156 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6158 The lineup functions here calculate the indentation for several types
6159 of comment structure.
6161 @defun c-lineup-C-comments
6162 @findex lineup-C-comments (c-)
6163 Line up C block comment continuation lines. Various heuristics are used
6164 to handle most of the common comment styles. Some examples:
6177 text ** text ** text
6184 /**************************************************
6186 *************************************************/
6190 @vindex comment-start-skip
6193 /**************************************************
6194 Free form text comments:
6195 In comments with a long delimiter line at the
6196 start, the indentation is kept unchanged for lines
6197 that start with an empty comment line prefix. The
6198 delimiter line is whatever matches the
6199 @code{comment-start-skip} regexp.
6200 **************************************************/
6204 The style variable @code{c-comment-prefix-regexp} is used to recognize
6205 the comment line prefix, e.g. the @samp{*} that usually starts every
6206 line inside a comment.
6208 @workswith The @code{c} syntactic symbol.
6211 @comment ------------------------------------------------------------
6213 @defun c-lineup-comment
6214 @findex lineup-comment (c-)
6215 Line up a comment-only line according to the style variable
6216 @code{c-comment-only-line-offset}. If the comment is lined up with a
6217 comment starter on the previous line, that alignment is preserved.
6219 @defopt c-comment-only-line-offset
6220 @vindex comment-only-line-offset (c-)
6221 This style variable specifies the extra offset for the line. It can
6222 contain an integer or a cons cell of the form
6225 (@r{@var{non-anchored-offset}} . @r{@var{anchored-offset}})
6229 where @var{non-anchored-offset} is the amount of offset given to
6230 non-column-zero anchored lines, and @var{anchored-offset} is the amount
6231 of offset to give column-zero anchored lines. Just an integer as value
6232 is equivalent to @code{(@r{@var{value}} . -1000)}.
6235 @workswith @code{comment-intro}.
6238 @comment ------------------------------------------------------------
6240 @defun c-lineup-knr-region-comment
6241 @findex lineup-knr-region-comment (c-)
6242 Line up a comment in the ``K&R region'' with the declaration. That is
6243 the region between the function or class header and the beginning of the
6249 /* Called at startup. */ @hereFn{c-lineup-knr-region-comment}
6256 Return @code{nil} if called in any other situation, to be useful in list
6259 @workswith @code{comment-intro}.
6262 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6263 @node Misc Line-Up, , Comment Line-Up, Line-Up Functions
6264 @comment node-name, next, previous, up
6265 @subsection Miscellaneous Line-Up Functions
6266 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6268 The line-up functions here are the odds and ends which didn't fit into
6269 any earlier category.
6271 @defun c-lineup-dont-change
6272 @findex lineup-dont-change (c-)
6273 This lineup function makes the line stay at whatever indentation it
6274 already has; think of it as an identity function for lineups.
6276 @workswith Any syntactic symbol.
6279 @comment ------------------------------------------------------------
6281 @defun c-lineup-cpp-define
6282 @findex lineup-cpp-define (c-)
6283 Line up macro continuation lines according to the indentation of the
6284 construct preceding the macro. E.g:
6288 const char msg[] = @hereFn{@r{The beginning of the preceding construct.}}
6292 do @{ \ @hereFn{c-lineup-cpp-define}
6304 if (!running) @hereFn{@r{The beginning of the preceding construct.}}
6305 error(\"Not running!\");
6308 do @{ \ @hereFn{c-lineup-cpp-define}
6314 If @code{c-syntactic-indentation-in-macros} is non-@code{nil}, the
6315 function returns the relative indentation to the macro start line to
6316 allow accumulation with other offsets. E.g. in the following cases,
6317 @code{cpp-define-intro} is combined with the
6318 @code{statement-block-intro} that comes from the @samp{do @{} that hangs
6319 on the @samp{#define} line:
6326 #define X(A, B) do @{ \
6327 printf (A, B); \ @hereFn{c-lineup-cpp-define}
6329 @} while (0) @hereFn{c-lineup-cpp-define}
6340 error(\"Not running!\");
6342 #define X(A, B) do @{ \
6343 printf (A, B); \ @hereFn{c-lineup-cpp-define}
6345 @} while (0) @hereFn{c-lineup-cpp-define}
6349 The relative indentation returned by @code{c-lineup-cpp-define} is zero
6350 and two, respectively, on the two lines in each of these examples. They
6351 are then added to the two column indentation that
6352 @code{statement-block-intro} gives in both cases here.
6354 If the relative indentation is zero, then @code{nil} is returned
6355 instead. That is useful in a list expression to specify the default
6356 indentation on the top level.
6358 If @code{c-syntactic-indentation-in-macros} is @code{nil} then this
6359 function keeps the current indentation, except for empty lines (ignoring
6360 the ending backslash) where it takes the indentation from the closest
6361 preceding nonempty line in the macro. If there's no such line in the
6362 macro then the indentation is taken from the construct preceding it, as
6365 @workswith @code{cpp-define-intro}.
6368 @comment ------------------------------------------------------------
6370 @defun c-lineup-gcc-asm-reg
6371 @findex lineup-gcc-asm-reg (c-)
6372 Line up a gcc asm register under one on a previous line.
6385 The @samp{x} line is aligned to the text after the @samp{:} on the
6386 @samp{w} line, and similarly @samp{z} under @samp{y}.
6388 This is done only in an @samp{asm} or @samp{__asm__} block, and only to
6389 those lines mentioned. Anywhere else @code{nil} is returned. The usual
6390 arrangement is to have this routine as an extra feature at the start of
6391 arglist lineups, e.g.
6394 (c-lineup-gcc-asm-reg c-lineup-arglist)
6397 @workswith @code{arglist-cont}, @code{arglist-cont-nonempty}.
6400 @comment ------------------------------------------------------------
6402 @defun c-lineup-topmost-intro-cont
6403 @findex lineup-topmost-intro-cont (c-)
6404 Line up declaration continuation lines zero or one indentation
6405 step@footnote{This function is mainly provided to mimic the behavior of
6406 CC Mode 5.28 and earlier where this case wasn't handled consistently so
6407 that those lines could be analyzed as either topmost-intro-cont or
6408 statement-cont. It's used for @code{topmost-intro-cont} by default, but
6409 you might consider using @code{+} instead.}. For lines preceding a
6410 definition, zero is used. For other lines, @code{c-basic-offset} is
6411 added to the indentation. E.g:
6416 neg (int i) @hereFn{c-lineup-topmost-intro-cont}
6429 larch @hereFn{c-lineup-topmost-intro-cont}
6433 the_larch, @hereFn{c-lineup-topmost-intro-cont}
6434 another_larch; @hereFn{c-lineup-topmost-intro-cont}
6445 the_larch, @hereFn{c-lineup-topmost-intro-cont}
6446 another_larch; @hereFn{c-lineup-topmost-intro-cont}
6450 @workswith @code{topmost-intro-cont}.
6453 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6454 @node Custom Line-Up, Other Indentation, Line-Up Functions, Customizing Indentation
6455 @comment node-name, next, previous, up
6456 @section Custom Line-Up Functions
6457 @cindex customization, indentation functions
6458 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6460 The most flexible way to customize indentation is by writing custom
6461 line-up functions, and associating them with specific syntactic
6462 symbols (@pxref{c-offsets-alist}). Depending on the effect you want,
6463 it might be better to write a @code{c-special-indent-hook} function
6464 rather than a line-up function (@pxref{Other Indentation}).
6466 @ccmode{} comes with an extensive set of predefined line-up functions,
6467 not all of which are used by the default styles. So there's a good
6468 chance the function you want already exists. @xref{Line-Up
6469 Functions}, for a list of them. If you write your own line-up
6470 function, it's probably a good idea to start working from one of these
6471 predefined functions, which can be found in the file
6472 @file{cc-align.el}. If you have written a line-up function that you
6473 think is generally useful, you're very welcome to contribute it;
6474 please contact @email{bug-cc-mode@@gnu.org}.
6476 Line-up functions are passed a single argument, the syntactic
6477 element (see below). At the time of the call, point will be somewhere
6478 on the line being indented. The return value is a
6479 @code{c-offsets-alist} offset specification: for example, an integer,
6480 a symbol such as @code{+}, a vector, @code{nil}@footnote{Returning
6481 @code{nil} is useful when the offset specification for a syntactic
6482 element is a list containing the line-up function
6483 (@pxref{c-offsets-alist}).}, or even another line-up function. Full
6484 details of these are in @ref{c-offsets-alist}.
6486 Line-up functions must not move point or change the content of the
6487 buffer (except temporarily). They are however allowed to do
6488 @dfn{hidden buffer changes}, i.e. setting text properties for caching
6489 purposes etc. Buffer undo recording is disabled while they run.
6491 The syntactic element passed as the parameter to a line-up function is
6492 a cons cell of the form
6495 (@r{@var{syntactic-symbol}} . @r{@var{anchor-position}})
6499 @c FIXME!!! The following sentence might be better omitted, since the
6500 @c information is in the cross reference "Syntactic Analysis". 2005/10/2.
6501 where @var{syntactic-symbol} is the symbol that the function was
6502 called for, and @var{anchor-position} is the anchor position (if any)
6503 for the construct that triggered the syntactic symbol
6504 (@pxref{Syntactic Analysis}). This cons cell is how the syntactic
6505 element of a line used to be represented in @ccmode{} 5.28 and
6506 earlier. Line-up functions are still passed this cons cell, so as to
6507 preserve compatibility with older configurations. In the future, we
6508 may decide to convert to using the full list format---you can prepare
6509 your setup for this by using the access functions
6510 (@code{c-langelem-sym}, etc.) described below.
6512 @vindex c-syntactic-element
6513 @vindex syntactic-element (c-)
6514 @vindex c-syntactic-context
6515 @vindex syntactic-context (c-)
6516 Some syntactic symbols, e.g. @code{arglist-cont-nonempty}, have more
6517 info in the syntactic element - typically other positions that can be
6518 interesting besides the anchor position. That info can't be accessed
6519 through the passed argument, which is a cons cell. Instead, you can
6520 get this information from the variable @code{c-syntactic-element},
6521 which is dynamically bound to the complete syntactic element. The
6522 variable @code{c-syntactic-context} might also be useful - it gets
6523 dynamically bound to the complete syntactic context. @xref{Custom
6526 @ccmode{} provides a few functions to access parts of syntactic
6527 elements in a more abstract way. Besides making the code easier to
6528 read, they also hide the difference between the old cons cell form
6529 used in the line-up function argument and the new list form used in
6530 @code{c-syntactic-element} and everywhere else. The functions are:
6532 @defun c-langelem-sym langelem
6533 @findex langelem-sym (c-)
6534 Return the syntactic symbol in @var{langelem}.
6537 @defun c-langelem-pos langelem
6538 @findex langelem-pos (c-)
6539 Return the anchor position in @var{langelem}, or nil if there is none.
6542 @defun c-langelem-col langelem &optional preserve-point
6543 @findex langelem-col (c-)
6544 Return the column of the anchor position in @var{langelem}. Also move
6545 the point to that position unless @var{preserve-point} is
6549 @defun c-langelem-2nd-pos langelem
6550 @findex langelem-2nd-pos (c-)
6551 Return the secondary position in @var{langelem}, or @code{nil} if there
6554 Note that the return value of this function is always @code{nil} if
6555 @var{langelem} is in the old cons cell form. Thus this function is
6556 only meaningful when used on syntactic elements taken from
6557 @code{c-syntactic-element} or @code{c-syntactic-context}.
6560 Custom line-up functions can be as simple or as complex as you like, and
6561 any syntactic symbol that appears in @code{c-offsets-alist} can have a
6562 custom line-up function associated with it.
6564 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6565 @node Other Indentation, , Custom Line-Up, Customizing Indentation
6566 @comment node-name, next, previous, up
6567 @section Other Special Indentations
6568 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6570 To configure macros which you invoke without a terminating @samp{;},
6571 see @xref{Macros with ;}.
6573 Here are the remaining odds and ends regarding indentation:
6575 @defopt c-label-minimum-indentation
6576 @vindex label-minimum-indentation (c-)
6577 In @samp{gnu} style (@pxref{Built-in Styles}), a minimum indentation is
6578 imposed on lines inside code blocks. This minimum indentation is
6579 controlled by this style variable. The default value is 1.
6581 @findex c-gnu-impose-minimum
6582 @findex gnu-impose-minimum (c-)
6583 It's the function @code{c-gnu-impose-minimum} that enforces this minimum
6584 indentation. It must be present on @code{c-special-indent-hook} to
6588 @defopt c-special-indent-hook
6589 @vindex special-indent-hook (c-)
6590 This style variable is a standard hook variable that is called after
6591 every line is indented by @ccmode{}. It is called only if
6592 @code{c-syntactic-indentation} is non-@code{nil} (which it is by
6593 default (@pxref{Indentation Engine Basics})). You can put a function
6594 on this hook to do any special indentation or ad hoc line adjustments
6595 your style dictates, such as adding extra indentation to constructors
6596 or destructor declarations in a class definition, etc. Sometimes it
6597 is better to write a custom Line-up Function instead (@pxref{Custom
6600 The indentation engine calls each function on this hook with no
6601 parameters, with point somewhere on the pertinent line, and with the
6602 variable @code{c-syntactic-context} bound to the current syntactic
6603 context (i.e. what you would get by typing @kbd{C-c C-s} on the source
6604 line. @xref{Custom Braces}.). Note that you should not change
6605 @code{c-syntactic-context} or point or mark inside a
6606 @code{c-special-indent-hook} function; thus you'll probably want to
6607 wrap your function in a @code{save-excursion}@footnote{The numerical
6608 value returned by @code{point} will change if you change the
6609 indentation of the line within a @code{save-excursion} form, but point
6610 itself will still be over the same piece of text.}.
6612 Setting @code{c-special-indent-hook} in style definitions is handled
6613 slightly differently from other variables---A style can only add
6614 functions to this hook, not remove them. @xref{Style Variables}.
6618 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6619 @node Custom Macros, Odds and Ends, Customizing Indentation, Top
6620 @comment node-name, next, previous, up
6621 @chapter Customizing Macros
6623 @cindex preprocessor directives
6624 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6626 Preprocessor macros in C, C++, and Objective C (introduced by
6627 @code{#define}) have a syntax different from the main language---for
6628 example, a macro declaration is not terminated by a semicolon, and if
6629 it is more than a line long, line breaks in it must be escaped with
6630 backslashes. @ccmode{} has some commands to manipulate these, see
6631 @ref{Macro Backslashes}.
6633 Normally, the lines in a multi-line macro are indented relative to
6634 each other as though they were code. You can suppress this behavior
6635 by setting the following user option:
6637 @defopt c-syntactic-indentation-in-macros
6638 @vindex syntactic-indentation-in-macros (c-)
6639 Enable syntactic analysis inside macros, which is the default. If this
6640 is @code{nil}, all lines inside macro definitions are analyzed as
6641 @code{cpp-macro-cont}.
6644 Because a macro can expand into anything at all, near where one is
6645 invoked @ccmode{} can only indent and fontify code heuristically.
6646 Sometimes it gets it wrong. Usually you should try to design your
6647 macros so that they ''look like ordinary code'' when you invoke them.
6648 However, one situation is so common that @ccmode{} handles it
6649 specially: that is when certain macros needn't (or mustn't) be
6650 followed by a @samp{;}. You need to configure @ccmode{} to handle
6651 these macros properly, see @ref{Macros with ;}.
6653 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6655 * Macro Backslashes::
6659 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6660 @node Macro Backslashes, Macros with ;, Custom Macros, Custom Macros
6661 @comment node-name, next, previous, up
6662 @section Customizing Macro Backslashes
6664 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6666 @ccmode{} provides some tools to help keep the line continuation
6667 backslashes in macros neat and tidy. Their precise action is
6668 customized with these variables:
6670 @defopt c-backslash-column
6671 @vindex backslash-column (c-)
6672 @defoptx c-backslash-max-column
6673 @vindex backslash-max-column (c-)
6674 These variables control the alignment columns for line continuation
6675 backslashes in multiline macros. They are used by the functions that
6676 automatically insert or align such backslashes,
6677 e.g. @code{c-backslash-region} and @code{c-context-line-break}.
6679 @code{c-backslash-column} specifies the minimum column for the
6680 backslashes. If any line in the macro goes past this column, then the
6681 next tab stop (i.e. next multiple of @code{tab-width}) in that line is
6682 used as the alignment column for all the backslashes, so that they
6683 remain in a single column. However, if any lines go past
6684 @code{c-backslash-max-column} then the backslashes in the rest of the
6685 macro will be kept at that column, so that the lines which are too
6686 long ``stick out'' instead.
6688 Don't ever set these variables to @code{nil}. If you want to disable
6689 the automatic alignment of backslashes, use
6690 @code{c-auto-align-backslashes}.
6693 @defopt c-auto-align-backslashes
6694 @vindex auto-align-backslashes (c-)
6695 Align automatically inserted line continuation backslashes if
6696 non-@code{nil}. When line continuation backslashes are inserted
6697 automatically for line breaks in multiline macros, e.g. by
6698 @code{c-context-line-break}, they are aligned with the other
6699 backslashes in the same macro if this flag is set.
6701 If @code{c-auto-align-backslashes} is @code{nil}, automatically
6702 inserted backslashes are preceded by a single space, and backslashes
6703 get aligned only when you explicitly invoke the command
6704 @code{c-backslash-region} (@kbd{C-c C-\}).
6707 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6708 @node Macros with ;, , Macro Backslashes, Custom Macros
6709 @comment node-name, next, previous, up
6710 @section Macros with semicolons
6711 @cindex macros with semicolons
6712 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6713 Macros which needn't (or mustn't) be followed by a semicolon when you
6714 invoke them, @dfn{macros with semicolons}, are very common. These can
6715 cause @ccmode{} to parse the next line wrongly as a
6716 @code{statement-cont} (@pxref{Function Symbols}) and thus mis-indent
6719 You can prevent this by specifying which macros have semicolons. It
6720 doesn't matter whether or not such a macro has a parameter list:
6722 @defopt c-macro-names-with-semicolon
6723 @vindex macro-names-with-semicolon (c-)
6724 This buffer-local variable specifies which macros have semicolons.
6725 After setting its value, you need to call
6726 @code{c-make-macro-with-semi-re} for it to take effect. It should be
6727 set to one of these values:
6731 There are no macros with semicolons.
6732 @item a list of strings
6733 Each string is the name of a macro with a semicolon. Only valid
6734 @code{#define} names are allowed here. For example, to set the
6735 default value, you could write the following into your @file{.emacs}:
6738 (setq c-macro-names-with-semicolon
6739 '("Q_OBJECT" "Q_PROPERTY" "Q_DECLARE" "Q_ENUMS"))
6742 @item a regular expression
6743 This matches each symbol which is a macro with a semicolon. It must
6744 not match any string which isn't a valid @code{#define} name. For
6748 (setq c-macro-names-with-semicolon
6749 "\\<\\(CLEAN_UP_AND_RETURN\\|Q_[[:upper:]]+\\)\\>")
6754 @defun c-make-macro-with-semi-re
6755 @findex make-macro-with-semi-re (c-)
6756 Call this (non-interactive) function, which sets internal variables,
6757 each time you change the value of
6758 @code{c-macro-names-with-semicolon}. It takes no arguments, and its
6759 return value has no meaning. This function is called by @ccmode{}'s
6760 initialization code.
6763 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6764 @node Odds and Ends, Sample .emacs File, Custom Macros, Top
6765 @comment node-name, next, previous, up
6766 @chapter Odds and Ends
6767 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6769 The stuff that didn't fit in anywhere else is documented here.
6771 @defopt c-require-final-newline
6772 @vindex require-final-newline (c-)
6773 Controls whether a final newline is enforced when the file is saved.
6774 The value is an association list that for each language mode specifies
6775 the value to give to @code{require-final-newline} (@pxref{Saving
6776 Buffers,,, @lispref{}, @lispreftitle{}}) at mode initialization. If a
6777 language isn't present on the association list, CC Mode won't touch
6778 @code{require-final-newline} in buffers for that language.
6780 The default is to set @code{require-final-newline} to @code{t} in the
6781 languages that mandate that source files should end with newlines.
6782 These are C, C++ and Objective-C.
6785 @defopt c-echo-syntactic-information-p
6786 @vindex echo-syntactic-information-p (c-)
6787 If non-@code{nil}, the syntactic analysis for the current line is shown
6788 in the echo area when it's indented (unless
6789 @code{c-syntactic-indentation} is @code{nil}). That's useful when
6790 finding out which syntactic symbols to modify to get the indentation you
6794 @defopt c-report-syntactic-errors
6795 @vindex report-syntactic-errors (c-)
6796 If non-@code{nil}, certain syntactic errors are reported with a ding and
6797 a message, for example when an @code{else} is indented for which there
6798 is no corresponding @code{if}.
6800 Note however that @ccmode{} doesn't make any special effort to check for
6801 syntactic errors; that's the job of the compiler. The reason it can
6802 report cases like the one above is that it can't find the correct
6803 anchoring position to indent the line in that case.
6807 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6808 @node Sample .emacs File, Performance Issues, Odds and Ends, Top
6809 @comment node-name, next, previous, up
6810 @appendix Sample .emacs File
6811 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6813 Here's a sample .emacs file fragment that might help you along the way.
6814 Just copy this region and paste it into your .emacs file. You might want
6815 to change some of the actual values.
6818 ;; Make a non-standard key binding. We can put this in
6819 ;; c-mode-base-map because c-mode-map, c++-mode-map, and so on,
6821 (defun my-c-initialization-hook ()
6822 (define-key c-mode-base-map "\C-m" 'c-context-line-break))
6823 (add-hook 'c-initialization-hook 'my-c-initialization-hook)
6825 ;; offset customizations not in my-c-style
6826 ;; This will take precedence over any setting of the syntactic symbol
6828 (setq c-offsets-alist '((member-init-intro . ++)))
6830 ;; Create my personal style.
6831 (defconst my-c-style
6832 '((c-tab-always-indent . t)
6833 (c-comment-only-line-offset . 4)
6834 (c-hanging-braces-alist . ((substatement-open after)
6836 (c-hanging-colons-alist . ((member-init-intro before)
6840 (access-label after)))
6841 (c-cleanup-list . (scope-operator
6844 (c-offsets-alist . ((arglist-close . c-lineup-arglist)
6845 (substatement-open . 0)
6848 (knr-argdecl-intro . -)))
6849 (c-echo-syntactic-information-p . t))
6850 "My C Programming Style")
6851 (c-add-style "PERSONAL" my-c-style)
6853 ;; Customizations for all modes in CC Mode.
6854 (defun my-c-mode-common-hook ()
6855 ;; set my personal style for the current buffer
6856 (c-set-style "PERSONAL")
6857 ;; other customizations
6859 ;; this will make sure spaces are used instead of tabs
6860 indent-tabs-mode nil)
6861 ;; we like auto-newline, but not hungry-delete
6862 (c-toggle-auto-newline 1))
6863 (add-hook 'c-mode-common-hook 'my-c-mode-common-hook)
6866 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6867 @node Performance Issues, Limitations and Known Bugs, Sample .emacs File, Top
6868 @comment node-name, next, previous, up
6869 @appendix Performance Issues
6871 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6873 @comment FIXME: (ACM, 2003/5/24). Check whether AWK needs mentioning here.
6875 C and its derivative languages are highly complex creatures. Often,
6876 ambiguous code situations arise that require @ccmode{} to scan large
6877 portions of the buffer to determine syntactic context. Such
6878 pathological code can cause @ccmode{} to perform fairly badly. This
6879 section gives some insight in how @ccmode{} operates, how that interacts
6880 with some coding styles, and what you can use to improve performance.
6882 The overall goal is that @ccmode{} shouldn't be overly slow (i.e. take
6883 more than a fraction of a second) in any interactive operation.
6884 I.e. it's tuned to limit the maximum response time in single operations,
6885 which is sometimes at the expense of batch-like operations like
6886 reindenting whole blocks. If you find that @ccmode{} gradually gets
6887 slower and slower in certain situations, perhaps as the file grows in
6888 size or as the macro or comment you're editing gets bigger, then chances
6889 are that something isn't working right. You should consider reporting
6890 it, unless it's something that's mentioned in this section.
6892 Because @ccmode{} has to scan the buffer backwards from the current
6893 insertion point, and because C's syntax is fairly difficult to parse in
6894 the backwards direction, @ccmode{} often tries to find the nearest
6895 position higher up in the buffer from which to begin a forward scan
6896 (it's typically an opening or closing parenthesis of some kind). The
6897 farther this position is from the current insertion point, the slower it
6900 @findex beginning-of-defun
6901 In earlier versions of @ccmode{}, we used to recommend putting the
6902 opening brace of a top-level construct@footnote{E.g. a function in C,
6903 or outermost class definition in C++ or Java.} into the leftmost
6904 column. Earlier still, this used to be a rigid Emacs constraint, as
6905 embodied in the @code{beginning-of-defun} function. @ccmode now
6906 caches syntactic information much better, so that the delay caused by
6907 searching for such a brace when it's not in column 0 is minimal,
6908 except perhaps when you've just moved a long way inside the file.
6910 @findex defun-prompt-regexp
6911 @vindex c-Java-defun-prompt-regexp
6912 @vindex Java-defun-prompt-regexp (c-)
6913 A special note about @code{defun-prompt-regexp} in Java mode: The common
6914 style is to hang the opening braces of functions and classes on the
6915 right side of the line, and that doesn't work well with the Emacs
6916 approach. @ccmode{} comes with a constant
6917 @code{c-Java-defun-prompt-regexp} which tries to define a regular
6918 expression usable for this style, but there are problems with it. In
6919 some cases it can cause @code{beginning-of-defun} to hang@footnote{This
6920 has been observed in Emacs 19.34 and XEmacs 19.15.}. For this reason,
6921 it is not used by default, but if you feel adventurous, you can set
6922 @code{defun-prompt-regexp} to it in your mode hook. In any event,
6923 setting and relying on @code{defun-prompt-regexp} will definitely slow
6924 things down because (X)Emacs will be doing regular expression searches a
6925 lot, so you'll probably be taking a hit either way!
6927 @ccmode{} maintains a cache of the opening parentheses of the blocks
6928 surrounding the point, and it adapts that cache as the point is moved
6929 around. That means that in bad cases it can take noticeable time to
6930 indent a line in a new surrounding, but after that it gets fast as long
6931 as the point isn't moved far off. The farther the point is moved, the
6932 less useful is the cache. Since editing typically is done in ``chunks''
6933 rather than on single lines far apart from each other, the cache
6934 typically gives good performance even when the code doesn't fit the
6935 Emacs approach to finding the defun starts.
6937 @vindex c-enable-xemacs-performance-kludge-p
6938 @vindex enable-xemacs-performance-kludge-p (c-)
6939 XEmacs users can set the variable
6940 @code{c-enable-xemacs-performance-kludge-p} to non-@code{nil}. This
6941 tells @ccmode{} to use XEmacs-specific built-in functions which, in some
6942 circumstances, can locate the top-most opening brace much more quickly than
6943 @code{beginning-of-defun}. Preliminary testing has shown that for
6944 styles where these braces are hung (e.g. most JDK-derived Java styles),
6945 this hack can improve performance of the core syntax parsing routines
6946 from 3 to 60 times. However, for styles which @emph{do} conform to
6947 Emacs' recommended style of putting top-level braces in column zero,
6948 this hack can degrade performance by about as much. Thus this variable
6949 is set to @code{nil} by default, since the Emacs-friendly styles should
6950 be more common (and encouraged!). Note that this variable has no effect
6951 in Emacs since the necessary built-in functions don't exist (in Emacs
6952 22.1 as of this writing in February 2007).
6954 Text properties are used to speed up skipping over syntactic whitespace,
6955 i.e. comments and preprocessor directives. Indenting a line after a
6956 huge macro definition can be slow the first time, but after that the
6957 text properties are in place and it should be fast (even after you've
6958 edited other parts of the file and then moved back).
6960 Font locking can be a CPU hog, especially the font locking done on
6961 decoration level 3 which tries to be very accurate. Note that that
6962 level is designed to be used with a font lock support mode that only
6963 fontifies the text that's actually shown, i.e. Lazy Lock or Just-in-time
6964 Lock mode, so make sure you use one of them. Fontification of a whole
6965 buffer with some thousand lines can often take over a minute. That is
6966 a known weakness; the idea is that it never should happen.
6968 The most effective way to speed up font locking is to reduce the
6969 decoration level to 2 by setting @code{font-lock-maximum-decoration}
6970 appropriately. That level is designed to be as pretty as possible
6971 without sacrificing performance. @xref{Font Locking Preliminaries}, for
6975 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6976 @node Limitations and Known Bugs, FAQ, Performance Issues, Top
6977 @comment node-name, next, previous, up
6978 @appendix Limitations and Known Bugs
6981 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6985 @ccmode{} doesn't support trigraphs. (These are character sequences
6986 such as @samp{??(}, which represents @samp{[}. They date from a time
6987 when some character sets didn't have all the characters that C needs,
6988 and are now utterly obsolete.)
6991 There is no way to apply auto newline settings (@pxref{Auto-newlines})
6992 on already typed lines. That's only a feature to ease interactive
6995 To generalize this issue a bit: @ccmode{} is not intended to be used as
6996 a reformatter for old code in some more or less batch-like way. With
6997 the exception of some functions like @code{c-indent-region}, it's only
6998 geared to be used interactively to edit new code. There's currently no
6999 intention to change this goal.
7002 @c If you change the way the following reference to GNU indent gets
7003 @c compiled into the HTML version of the manual, make sure that
7004 @c 2www.gnu.org.sh still strips out the broken pointer, amending the
7005 @c script if necessary.
7006 If you want to reformat old code, you're probably better off using some
7007 other tool instead, e.g. @ref{Top, , GNU indent, indent, The `indent'
7008 Manual}, which has more powerful reformatting capabilities than
7012 The support for C++ templates (in angle brackets) is not yet complete.
7013 When a non-nested template is used in a declaration, @ccmode{} indents
7014 it and font-locks it OK. Templates used in expressions, and nested
7015 templates do not fare so well. Sometimes a workaround is to refontify
7016 the expression after typing the closing @samp{>}.
7019 In a @dfn{k&r region} (the part of an old-fashioned C function
7020 declaration which specifies the types of its parameters, coming
7021 between the parameter list and the opening brace), there should be at
7022 most 20 top-level parenthesis and bracket pairs. This limit has been
7023 imposed for performance reasons. If it is violated, the source file
7024 might be incorrectly indented or fontified.
7027 On loading @ccmode{}, sometimes this error message appears:
7030 File mode specification error: (void-variable c-font-lock-keywords-3)
7033 This is due to a bug in the function @code{eval-after-load} in some
7034 versions of (X)Emacs. It can manifest itself when there is a symbolic
7035 link in the path of the directory which contains (X)Emacs. As a
7036 workaround, put the following into your @file{.emacs} file, fairly
7040 (defun my-load-cc-fonts ()
7041 (require "cc-fonts"))
7042 (add-hook 'c-initialization-hook 'my-load-cc-fonts)
7046 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
7047 @node FAQ, Updating CC Mode, Limitations and Known Bugs, Top
7048 @comment node-name, next, previous, up
7049 @appendix Frequently Asked Questions
7050 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
7054 @emph{How can I change the indent level from 4 spaces to 2 spaces?}
7056 Set the variable @code{c-basic-offset}. @xref{Getting Started}.
7061 @emph{Why doesn't the @kbd{RET} key indent the new line?}
7063 Emacs' convention is that @kbd{RET} just adds a newline, and that
7064 @kbd{C-j} adds a newline and indents it. You can make @kbd{RET} do this
7065 too by adding this to your @code{c-initialization-hook}:
7068 (define-key c-mode-base-map "\C-m" 'c-context-line-break)
7071 @xref{Getting Started}. This is a very common question. If you want
7072 this to be the default behavior, don't lobby us, lobby RMS! @t{:-)}
7075 @emph{How do I stop my code jumping all over the place when I type?}
7077 Deactivate ``electric minor mode'' with @kbd{C-c C-l}. @xref{Getting
7083 @emph{How do I reindent the whole file?}
7085 Visit the file and hit @kbd{C-x h} to mark the whole buffer. Then hit
7086 @kbd{C-M-\}. @xref{Indentation Commands}.
7091 @emph{How do I reindent the current block?}
7093 First move to the brace which opens the block with @kbd{C-M-u}, then
7094 reindent that expression with @kbd{C-M-q}. @xref{Indentation
7098 @emph{I put @code{(c-set-offset 'substatement-open 0)} in my
7099 @file{.emacs} file but I get an error saying that @code{c-set-offset}'s
7100 function definition is void. What's wrong?}
7102 This means that @ccmode{} hasn't yet been loaded into your Emacs
7103 session by the time the @code{c-set-offset} call is reached, most
7104 likely because @ccmode{} is being autoloaded. Instead of putting the
7105 @code{c-set-offset} line in your top-level @file{.emacs} file, put it
7106 in your @code{c-initialization-hook} (@pxref{CC Hooks}), or simply
7107 modify @code{c-offsets-alist} directly:
7110 (setq c-offsets-alist '((substatement-open . 0)))
7114 @cindex open paren in column zero
7115 @emph{I have an open paren character at column zero inside a comment or
7116 multiline string literal, and it causes the fontification and/or
7117 indentation to go haywire. What gives?}
7119 It's due to the ad-hoc rule in (X)Emacs that such open parens always
7120 start defuns (which translates to functions, classes, namespaces or any
7121 other top-level block constructs in the @ccmode{} languages).
7123 @xref{Defuns,,, xemacs, XEmacs User's Manual}, for details.
7126 @xref{Left Margin Paren,,, emacs, GNU Emacs Manual}, for details
7127 (@xref{Defuns,,, emacs, GNU Emacs Manual}, in the Emacs 20 manual).
7130 This heuristic is built into the core syntax analysis routines in
7131 (X)Emacs, so it's not really a @ccmode{} issue. However, in Emacs
7132 21.1 it became possible to turn it off@footnote{Using the variable
7133 @code{open-paren-in-column-0-is-defun-start}.} and @ccmode{} does so
7134 there since it's got its own system to keep track of blocks.
7139 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
7140 @node Updating CC Mode, Mailing Lists and Bug Reports, FAQ, Top
7141 @comment node-name, next, previous, up
7142 @appendix Getting the Latest CC Mode Release
7143 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
7145 @ccmode{} has been standard with all versions of Emacs since 19.34 and
7146 of XEmacs since 19.16.
7149 Due to release schedule skew, it is likely that all of these Emacsen
7150 have old versions of @ccmode{} and so should be upgraded. Access to the
7151 @ccmode{} source code, as well as more detailed information on Emacsen
7152 compatibility, etc. are all available on the web site:
7155 @uref{http://cc-mode.sourceforge.net/}
7159 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
7160 @node Mailing Lists and Bug Reports, Command and Function Index, Updating CC Mode, Top
7161 @comment node-name, next, previous, up
7162 @appendix Mailing Lists and Submitting Bug Reports
7163 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
7166 @findex c-submit-bug-report
7167 @findex submit-bug-report (c-)
7168 To report bugs, use the @kbd{C-c C-b} (bound to
7169 @code{c-submit-bug-report}) command. This provides vital information
7170 we need to reproduce your problem. Make sure you include a concise,
7171 but complete code example. Please try to boil your example down to
7172 just the essential code needed to reproduce the problem, and include
7173 an exact recipe of steps needed to expose the bug. Be especially sure
7174 to include any code that appears @emph{before} your bug example, if
7175 you think it might affect our ability to reproduce it.
7177 Please try to produce the problem in an Emacs instance without any
7178 customizations loaded (i.e. start it with the @samp{-q --no-site-file}
7179 arguments). If it works correctly there, the problem might be caused
7180 by faulty customizations in either your own or your site
7181 configuration. In that case, we'd appreciate it if you isolate the
7182 Emacs Lisp code that triggers the bug and include it in your report.
7184 @cindex bug report mailing list
7185 Bug reports should be sent to @email{bug-cc-mode@@gnu.org}. You can
7186 also send other questions and suggestions (kudos? @t{;-)} to that
7187 address. It's a mailing list which you can join or browse an archive
7188 of; see the web site at @uref{http://cc-mode.sourceforge.net/} for
7191 @cindex announcement mailing list
7192 If you want to get announcements of new @ccmode{} releases, send the
7193 word @emph{subscribe} in the body of a message to
7194 @email{cc-mode-announce-request@@lists.sourceforge.net}. It's possible
7195 to subscribe from the web site too. Announcements will also be posted
7196 to the Usenet newsgroups @code{gnu.emacs.sources}, @code{comp.emacs},
7197 @code{comp.emacs.xemacs}, @code{comp.lang.c}, @code{comp.lang.c++},
7198 @code{comp.lang.objective-c}, @code{comp.lang.java.softwaretools},
7199 @code{comp.lang.idl}, and @code{comp.lang.awk}.
7200 @c There is no newsgroup for Pike. :-(
7202 @c Removed the tentative node "Mode Initialization" from here, 2005/8/27.
7203 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
7204 @node Command and Function Index, Variable Index, Mailing Lists and Bug Reports, Top
7205 @comment node-name, next, previous, up
7206 @unnumbered Command and Function Index
7207 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
7209 Since most @ccmode{} commands are prepended with the string
7210 @samp{c-}, each appears under its @code{c-@var{thing}} name and its
7211 @code{@var{thing} (c-)} name.
7218 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
7219 @node Variable Index, Concept and Key Index, Command and Function Index, Top
7220 @comment node-name, next, previous, up
7221 @unnumbered Variable Index
7222 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
7224 Since most @ccmode{} variables are prepended with the string
7225 @samp{c-}, each appears under its @code{c-@var{thing}} name and its
7226 @code{@var{thing} (c-)} name.
7233 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
7234 @node Concept and Key Index, , Variable Index, Top
7235 @comment node-name, next, previous, up
7236 @unnumbered Concept and Key Index
7237 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
7242 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
7244 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!