2 @c Notes to self regarding line handling:
4 @c Empty lines are often significant before @end directives; avoid them.
6 @c Empty lines before and after @example directives are significant in
7 @c info output but not in TeX. Empty lines inside @example directives
10 @c Conventions for formatting examples:
11 @c o If the example contains empty lines then put the surrounding empty
12 @c lines inside the @example directives. Put them outside otherwise.
13 @c o Use @group inside the example only if it shows indentation where
14 @c the relation between lines inside is relevant.
15 @c o Format line number columns like this:
19 @c ^^ two columns, right alignment
20 @c o Check line lengths in TeX output; they can typically be no longer
21 @c than 70 chars, 60 if the paragraph is indented.
23 @comment TBD: Document the finer details of statement anchoring?
25 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
26 @comment %**start of header (This is for running Texinfo on a region)
27 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
30 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
31 @comment How to make the various output formats:
32 @comment (Thanks to Robert Chassell for supplying this information.)
33 @comment Note that Texinfo 4.7 (or later) is needed.
34 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
36 In each of the following pairs of commands, the first generates a
37 version with cross references pointing to the GNU Emacs manuals,
38 the second with them pointing to the XEmacs manuals.
41 makeinfo -DXEMACS cc-mode.texi
44 ## You may need to set up the environment variable TEXINPUTS so
45 ## that tex can find the file texinfo.tex - See the tex
48 texi2dvi -t "@set XEMACS " cc-mode.texi
50 ## HTML output. (The --no-split parameter is optional)
51 makeinfo --html --no-split cc-mode.texi
52 makeinfo --html --no-split -DXEMACS cc-mode.texi
55 makeinfo --fill-column=70 --no-split --paragraph-indent=0 \
56 --no-headers --output=cc-mode.txt cc-mode.texi
57 makeinfo --fill-column=70 --no-split --paragraph-indent=0 \
58 --no-headers --output=cc-mode.txt -DXEMACS cc-mode.texi
61 makeinfo --docbook --no-split --paragraph-indent=0 \
63 makeinfo --docbook --no-split --paragraph-indent=0 \
67 makeinfo --xml --no-split --paragraph-indent=0 \
69 makeinfo --xml --no-split --paragraph-indent=0 \
72 #### (You must be in the same directory as the viewed file.)
81 @comment No overfull hbox marks in the dvi file.
84 @setfilename ../../info/ccmode
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 This manual is for CC Mode in Emacs.
162 Copyright @copyright{} 1995-2011 Free Software Foundation, Inc.
165 Permission is granted to copy, distribute and/or modify this document
166 under the terms of the GNU Free Documentation License, Version 1.3 or
167 any later version published by the Free Software Foundation; with no
168 Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
169 and with the Back-Cover Texts as in (a) below. A copy of the license
170 is included in the section entitled ``GNU Free Documentation License''.
172 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
173 modify this GNU manual. Buying copies from the FSF supports it in
174 developing GNU and promoting software freedom.''
178 @comment Info directory entry for use by install-info. The indentation
179 @comment here is by request from the FSF folks.
180 @dircategory Emacs editing modes
182 * CC Mode: (ccmode). Emacs mode for editing C, C++, Objective-C,
183 Java, Pike, AWK, and CORBA IDL code.
186 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
187 @comment TeX title page
188 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
193 @center @titlefont{CC Mode 5.31}
195 @center @subtitlefont{A GNU Emacs mode for editing C and C-like languages}
197 @center Barry A. Warsaw, Martin Stjernholm, Alan Mackenzie
200 @vskip 0pt plus 1filll
203 This manual was generated from cc-mode.texi, which is distributed with Emacs,
204 or can be downloaded from @url{http://savannah.gnu.org/projects/emacs/}.
207 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
208 @comment The Top node contains the master menu for the Info file.
209 @comment This appears only in the Info file, not the printed manual.
210 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
215 @node Top, Introduction, (dir), (dir)
216 @comment node-name, next, previous, up
221 @ccmode{} is a GNU Emacs mode for editing files containing C, C++,
222 Objective-C, Java, CORBA IDL (and the variants PSDL and CIDL), Pike
223 and AWK code. It provides syntax-based indentation, font locking, and
224 has several handy commands and some minor modes to make the editing
225 easier. It does not provide tools to look up and navigate between
226 functions, classes etc - there are other packages for that.
231 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
232 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
241 * Custom Filling and Breaking::
242 * Custom Auto-newlines::
244 * Indentation Engine Basics::
245 * Customizing Indentation::
248 * Sample .emacs File::
249 * Performance Issues::
250 * Limitations and Known Bugs::
253 * Mailing Lists and Bug Reports::
254 * GNU Free Documentation License::
255 * Command and Function Index::
257 * Concept and Key Index::
260 --- The Detailed Node Listing ---
264 * Indentation Commands::
266 * Movement Commands::
267 * Filling and Breaking::
271 * Hungry WS Deletion::
277 * Font Locking Preliminaries::
280 * AWK Mode Font Locking::
293 * Guessing the Style::
296 Customizing Auto-newlines
300 * Hanging Semicolons and Commas::
306 Indentation Engine Basics
308 * Syntactic Analysis::
309 * Syntactic Symbols::
310 * Indentation Calculation::
316 * Conditional Construct Symbols::
317 * Switch Statement Symbols::
318 * Brace List Symbols::
319 * External Scope Symbols::
320 * Paren List Symbols::
322 * Multiline Macro Symbols::
323 * Objective-C Method Symbols::
325 * Statement Block Symbols::
328 Customizing Indentation
331 * Interactive Customization::
332 * Line-Up Functions::
334 * Other Indentation::
338 * Brace/Paren Line-Up::
347 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
348 @node Introduction, Overview, Top, Top
349 @comment node-name, next, previous, up
350 @chapter Introduction
351 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
359 Welcome to @ccmode{}, a GNU Emacs mode for editing files containing C,
360 C++, Objective-C, Java, CORBA IDL (and the variants CORBA PSDL and
361 CIDL), Pike and AWK code. This incarnation of the mode is descended
362 from @file{c-mode.el} (also called ``Boring Old C Mode'' or BOCM
363 @t{:-)}, @file{c++-mode.el} version 2, which Barry Warsaw had been
364 maintaining since 1992, and @file{awk-mode.el}, a long neglected mode
365 in the (X)Emacs base.
367 Late in 1997, Martin Stjernholm joined Barry on the @ccmode{}
368 Maintainers Team, and implemented the Pike support. In 2000 Martin
369 took over as the sole maintainer. In 2001 Alan Mackenzie joined the
370 team, implementing AWK support in version 5.30. @ccmode{} did not
371 originally contain the font lock support for its languages --- that
372 was added in version 5.30.
374 This manual describes @ccmode{}
375 @comment The following line must appear on its own, so that the
377 @comment Release.py script can update the version number automatically
379 @ccmode{} supports the editing of K&R and ANSI C, C++, Objective-C,
380 Java, CORBA's Interface Definition Language, Pike@footnote{A C-like
381 scripting language with its roots in the LPC language used in some MUD
382 engines. See @uref{http://pike.ida.liu.se/}.} and AWK files. In this
383 way, you can easily set up consistent font locking and coding styles for
384 use in editing all of these languages, although AWK is not yet as
385 uniformly integrated as the other languages.
394 Note that the name of this package is ``@ccmode{}'', but there is no top
395 level @code{cc-mode} entry point. All of the variables, commands, and
396 functions in @ccmode{} are prefixed with @code{c-@var{thing}}, and
397 @code{c-mode}, @code{c++-mode}, @code{objc-mode}, @code{java-mode},
398 @code{idl-mode}, @code{pike-mode}, and @code{awk-mode} entry points are
399 provided. This package is intended to be a replacement for
400 @file{c-mode.el}, @file{c++-mode.el} and @file{awk-mode.el}.
402 A special word of thanks goes to Krishna Padmasola for his work in
403 converting the original @file{README} file to Texinfo format. I'd
404 also like to thank all the @ccmode{} victims who help enormously
405 during the early beta stages of @ccmode{}'s development.
407 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
408 @node Overview, Getting Started, Introduction, Top
409 @comment node-name, next, previous, up@cindex organization of the manual
410 @chapter Overview of the Manual
411 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
414 The manual starts with several introductory chapters (including this
418 The next chunk of the manual describes the day to day @emph{use} of
419 @ccmode{} (as contrasted with how to customize it).
423 The chapter ``Commands'' describes in detail how to use (nearly) all
424 of @ccmode{}'s features. There are extensive cross-references from
425 here to the corresponding sections later in the manual which tell you
426 how to customize these features.
429 ``Font Locking'' describes how ``syntax highlighting'' is applied to
430 your buffers. It is mainly background information and can be skipped
431 over at a first reading.
435 The next chunk of the manual describes how to @emph{customize}
436 @ccmode{}. Typically, an overview of a topic is given at the chapter
437 level, then the sections and subsections describe the material in
442 The chapter ``Configuration Basics'' tells you @emph{how} to write
443 customizations - whether in hooks, in styles, in both, or in neither,
444 depending on your needs. It describes the @ccmode{} style system and
445 lists the standard styles that @ccmode{} supplies.
448 The next few chapters describe in detail how to customize the various
449 features of @ccmode{}.
452 Finally, there is a sample @file{.emacs} fragment, which might help you
453 in creating your own customization.
457 The manual ends with ``this and that'', things that don't fit cleanly
458 into any of the previous chunks.
462 Two chapters discuss the performance of @ccmode{} and known
466 The FAQ contains a list of common problems and questions.
469 The next two chapters tell you how to get in touch with the @ccmode{}
470 project - whether for updating @ccmode{} or submitting bug reports.
474 Finally, there are the customary indices.
476 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
477 @node Getting Started, Commands, Overview, Top
478 @comment node-name, next, previous, up
479 @chapter Getting Started
480 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
482 If you got this version of @ccmode{} with Emacs or XEmacs, it should
483 work just fine right out of the box. Note however that you might not
484 have the latest @ccmode{} release and might want to upgrade your copy
487 You should probably start by skimming through the entire Commands chapter
488 (@pxref{Commands}) to get an overview of @ccmode{}'s capabilities.
490 After trying out some commands, you may dislike some aspects of
491 @ccmode{}'s default configuration. Here is an outline of how to
492 change some of the settings that newcomers to @ccmode{} most often
497 This Lisp variable holds an integer, the number of columns @ccmode{}
498 indents nested code. To set this value to 6, customize
499 @code{c-basic-offset} or put this into your @file{.emacs}:
502 (setq c-basic-offset 6)
505 @item The (indentation) style
506 The basic ``shape'' of indentation created by @ccmode{}---by default,
507 this is @code{gnu} style (except for Java and AWK buffers). A list of
508 the available styles and their descriptions can be found in
509 @ref{Built-in Styles}. A complete specification of the @ccmode{}
510 style system, including how to create your own style, can be found in
511 the chapter @ref{Styles}. To set your style to @code{linux}, either
512 customize @code{c-default-style} or put this into your @file{.emacs}:
515 (setq c-default-style '((java-mode . "java")
520 @item Electric Indentation
521 Normally, when you type ``punctuation'' characters such as @samp{;} or
522 @samp{@{}, @ccmode{} instantly reindents the current line. This can
523 be disconcerting until you get used to it. To disable @dfn{electric
524 indentation} in the current buffer, type @kbd{C-c C-l}. Type the same
525 thing to enable it again. To have electric indentation disabled by
526 default, put the following into your @file{.emacs} file@footnote{There
527 is no ``easy customization'' facility for making this change.}:
530 (setq-default c-electric-flag nil)
534 Details of this and other similar ``Minor Modes'' appear in the
535 section @ref{Minor Modes}.
537 @item Making the @key{RET} key indent the new line
538 The standard Emacs binding for @key{RET} just adds a new line. If you
539 want it to reindent the new line as well, rebind the key. Note that
540 the action of rebinding would fail if the pertinent keymap didn't yet
541 exist---we thus need to delay the action until after @ccmode{} has
542 been loaded. Put the following code into your @file{.emacs}:
545 (defun my-make-CR-do-indent ()
546 (define-key c-mode-base-map "\C-m" 'c-context-line-break))
547 (add-hook 'c-initialization-hook 'my-make-CR-do-indent)
551 This example demonstrates the use of a very powerful @ccmode{} (and
552 Emacs) facility, the hook. The use of @ccmode{}'s hooks is described
556 All these settings should occur in your @file{.emacs} @emph{before}
557 any @ccmode{} buffers get loaded---in particular, before any call of
560 As you get to know the mode better, you may want to make more
561 ambitious changes to your configuration. For this, you should start
562 reading the chapter @ref{Config Basics}.
564 If you are upgrading an existing @ccmode{} installation, please see
565 the @file{README} file for installation details. In particular, if
566 you are going to be editing AWK files, @file{README} describes how to
567 configure your (X)Emacs so that @ccmode{} will supersede the obsolete
568 @code{awk-mode.el} which might have been supplied with your (X)Emacs.
569 @ccmode{} might not work with older versions of Emacs or XEmacs. See
570 the @ccmode{} release notes at @uref{http://cc-mode.sourceforge.net}
571 for the latest information on Emacs version and package compatibility
572 (@pxref{Updating CC Mode}).
574 @deffn Command c-version
576 You can find out what version of @ccmode{} you are using by visiting a C
577 file and entering @kbd{M-x c-version RET}. You should see this message in
581 Using CC Mode version 5.XX
585 where @samp{XX} is the minor release number.
588 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
589 @node Commands, Font Locking, Getting Started, Top
590 @comment node-name, next, previous, up
592 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
594 This chapter specifies all of CC Mode's commands, and thus contains
595 nearly everything you need to know to @emph{use} @ccmode{} (as
596 contrasted with configuring it). @dfn{Commands} here means both
597 control key sequences and @dfn{electric keys}, these being characters
598 such as @samp{;} which, as well as inserting themselves into the
599 buffer, also do other things.
601 You might well want to review
603 @ref{Lists,,,@emacsman{}, @emacsmantitle{}},
606 @ref{Moving by Parens,,,@emacsman{}, @emacsmantitle{}},
608 which describes commands for moving around brace and parenthesis
613 * Indentation Commands::
615 * Movement Commands::
616 * Filling and Breaking::
620 * Hungry WS Deletion::
625 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
626 @node Indentation Commands, Comment Commands, Commands, Commands
627 @comment node-name, next, previous,up
628 @section Indentation Commands
630 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
632 The following commands reindent C constructs. Note that when you
633 change your coding style, either interactively or through some other
634 means, your file does @emph{not} automatically get reindented. You
635 will need to execute one of the following commands to see the effects
638 @cindex GNU indent program
639 Also, variables like @code{c-hanging-*} and @code{c-cleanup-list}
640 (@pxref{Custom Auto-newlines}) only affect how on-the-fly code is
641 formatted. Changing the ``hanginess'' of a brace and then
642 reindenting, will not move the brace to a different line. For this,
643 you're better off getting an external program like GNU @code{indent},
644 which will rearrange brace location, amongst other things.
646 Preprocessor directives are handled as syntactic whitespace from other
647 code, i.e. they can be interspersed anywhere without affecting the
648 indentation of the surrounding code, just like comments.
650 The code inside macro definitions is, by default, still analyzed
651 syntactically so that you get relative indentation there just as you'd
652 get if the same code was outside a macro. However, since there is no
653 hint about the syntactic context, i.e. whether the macro expands to an
654 expression, to some statements, or perhaps to whole functions, the
655 syntactic recognition can be wrong. @ccmode{} manages to figure it
656 out correctly most of the time, though.
658 Reindenting large sections of code can take a long time. When
659 @ccmode{} reindents a region of code, it is essentially equivalent to
660 hitting @key{TAB} on every line of the region.
662 These commands indent code:
665 @item @kbd{@key{TAB}} (@code{c-indent-command})
667 @findex c-indent-command
668 @findex indent-command (c-)
669 This command indents the current line. That is all you need to know
670 about it for normal use.
672 @code{c-indent-command} does different things, depending on the
673 setting of @code{c-syntactic-indentation} (@pxref{Indentation Engine
678 When it's non-@code{nil} (which it normally is), the command indents
679 the line according to its syntactic context. With a prefix argument
680 (@kbd{C-u @key{TAB}}), it will re-indent the entire
681 expression@footnote{this is only useful for a line starting with a
682 comment opener or an opening brace, parenthesis, or string quote.}
683 that begins at the line's left margin.
686 When it's @code{nil}, the command indents the line by an extra
687 @code{c-basic-offset} columns. A prefix argument acts as a
688 multiplier. A bare prefix (@kbd{C-u @key{TAB}}) is equivalent to -1,
689 removing @code{c-basic-offset} columns from the indentation.
692 The precise behavior is modified by several variables: With
693 @code{c-tab-always-indent}, you can make @key{TAB} insert whitespace
694 in some circumstances---@code{c-insert-tab-function} then defines
695 precisely what sort of ``whitespace'' this will be. Set the standard
696 Emacs variable @code{indent-tabs-mode} to @code{t} if you want real
697 @samp{tab} characters to be used in the indentation, to @code{nil} if
698 you want only spaces. @xref{Just Spaces,,, @emacsman{},
701 @defopt c-tab-always-indent
702 @vindex tab-always-indent (c-)
704 This variable modifies how @key{TAB} operates.
707 When it is @code{t} (the default), @key{TAB} simply indents the
710 When it is @code{nil}, @key{TAB} (re)indents the line only if point is
711 to the left of the first non-whitespace character on the line.
712 Otherwise it inserts some whitespace (a tab or an equivalent number of
713 spaces - see below) at point.
715 With some other value, the line is reindented. Additionally, if point
716 is within a string or comment, some whitespace is inserted.
720 @defopt c-insert-tab-function
721 @vindex insert-tab-function (c-)
722 @findex tab-to-tab-stop
723 When ``some whitespace'' is inserted as described above, what actually
724 happens is that the function stored in @code{c-insert-tab-function} is
725 called. Normally, this is @code{insert-tab}, which inserts a real tab
726 character or the equivalent number of spaces (depending on
727 @code{indent-tabs-mode}). Some people, however, set
728 @code{c-insert-tab-function} to @code{tab-to-tab-stop} so as to get
729 hard tab stops when indenting.
734 The kind of indentation the next five commands do depends on the
735 setting of @code{c-syntactic-indentation} (@pxref{Indentation Engine
739 when it is non-@code{nil} (the default), the commands indent lines
740 according to their syntactic context;
742 when it is @code{nil}, they just indent each line the same amount as
743 the previous non-blank line. The commands that indent a region aren't
744 very useful in this case.
748 @item @kbd{C-j} (@code{newline-and-indent})
750 @findex newline-and-indent
751 Inserts a newline and indents the new blank line, ready to start
752 typing. This is a standard (X)Emacs command.
754 @item @kbd{C-M-q} (@code{c-indent-exp})
757 @findex indent-exp (c-)
758 Indents an entire balanced brace or parenthesis expression. Note that
759 point must be on the opening brace or parenthesis of the expression
762 @item @kbd{C-c C-q} (@code{c-indent-defun})
764 @findex c-indent-defun
765 @findex indent-defun (c-)
766 Indents the entire top-level function, class or macro definition
767 encompassing point. It leaves point unchanged. This function can't be
768 used to reindent a nested brace construct, such as a nested class or
769 function, or a Java method. The top-level construct being reindented
770 must be complete, i.e. it must have both a beginning brace and an ending
773 @item @kbd{C-M-\} (@code{indent-region})
775 @findex indent-region
776 Indents an arbitrary region of code. This is a standard Emacs command,
777 tailored for C code in a @ccmode{} buffer. Note, of course, that point
778 and mark must delineate the region you want to indent.
780 @item @kbd{C-M-h} (@code{c-mark-function})
782 @findex c-mark-function
783 @findex mark-function (c-)
784 While not strictly an indentation command, this is useful for marking
785 the current top-level function or class definition as the current
786 region. As with @code{c-indent-defun}, this command operates on
787 top-level constructs, and can't be used to mark say, a Java method.
790 These variables are also useful when indenting code:
792 @defopt indent-tabs-mode
793 This is a standard Emacs variable that controls how line indentation
794 is composed. When it's non-@code{nil}, tabs can be used in a line's
795 indentation, otherwise only spaces are used.
798 @defopt c-progress-interval
799 @vindex progress-interval (c-)
800 When indenting large regions of code, this variable controls how often a
801 progress message is displayed. Set this variable to @code{nil} to
802 inhibit the progress messages, or set it to an integer which is how
803 often (in seconds) progress messages are to be displayed.
806 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
807 @node Comment Commands, Movement Commands, Indentation Commands, Commands
808 @comment node-name, next, previous, up
809 @section Comment Commands
810 @cindex comments (insertion of)
811 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
814 @item @kbd{C-c C-c} (@code{comment-region})
816 @findex comment-region
817 This command comments out the lines that start in the region. With a
818 negative argument, it does the opposite - it deletes the comment
819 delimiters from these lines. @xref{Multi-Line Comments,,, emacs, GNU
820 Emacs Manual}, for fuller details. @code{comment-region} isn't
821 actually part of @ccmode{} - it is given a @ccmode{} binding for
824 @item @kbd{M-;} (@code{comment-dwim} or @code{indent-for-comment} @footnote{The name of this command varies between (X)Emacs versions.})
827 @findex indent-for-comment
828 Insert a comment at the end of the current line, if none is there
829 already. Then reindent the comment according to @code{comment-column}
831 (@pxref{Options for Comments,,, emacs, GNU Emacs Manual})
834 (@pxref{Comments,,, xemacs, XEmacs User's Manual})
836 and the variables below. Finally, position the point after the
837 comment starter. @kbd{C-u M-;} kills any comment on the current line,
838 together with any whitespace before it. This is a standard Emacs
839 command, but @ccmode{} enhances it a bit with two variables:
841 @defopt c-indent-comment-alist
842 @vindex indent-comment-alist (c-)
843 @vindex comment-column
844 This style variable allows you to vary the column that @kbd{M-;} puts
845 the comment at, depending on what sort of code is on the line, and
846 possibly the indentation of any similar comment on the preceding line.
847 It is an association list that maps different types of lines to
848 actions describing how they should be handled. If a certain line type
849 isn't present on the list then the line is indented to the column
850 specified by @code{comment-column}.
852 See the documentation string for a full description of this
853 variable (use @kbd{C-h v c-indent-comment-alist}).
856 @defopt c-indent-comments-syntactically-p
857 @vindex indent-comments-syntactically-p (c-)
858 Normally, when this style variable is @code{nil}, @kbd{M-;} will
859 indent comment-only lines according to @code{c-indent-comment-alist},
860 just as it does with lines where other code precede the comments.
861 However, if you want it to act just like @key{TAB} for comment-only
862 lines you can get that by setting
863 @code{c-indent-comments-syntactically-p} to non-@code{nil}.
865 If @code{c-indent-comments-syntactically-p} is non-@code{nil} then
866 @code{c-indent-comment-alist} won't be consulted at all for comment-only
871 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
872 @node Movement Commands, Filling and Breaking, Comment Commands, Commands
873 @comment node-name, next, previous, up
874 @section Movement Commands
876 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
878 @ccmode{} contains some useful commands for moving around in C code.
881 @item @kbd{C-M-a} (@code{c-beginning-of-defun})
882 @itemx @kbd{C-M-e} (@code{c-end-of-defun})
883 @findex c-beginning-of-defun
884 @findex c-end-of-defun
885 @vindex c-defun-tactic
886 @vindex defun-tactic (c-)
888 Move to the beginning or end of the current or next function. Other
889 constructs (such as a structs or classes) which have a brace block
890 also count as ``functions'' here. To move over several functions, you
891 can give these commands a repeat count.
893 The start of a function is at its header. The end of the function is
894 after its closing brace, or after the semicolon of a construct (such
895 as a @code{struct}) which doesn't end at the brace. These two
896 commands try to leave point at the beginning of a line near the actual
897 start or end of the function. This occasionally causes point not to
900 By default, these commands will recognize functions contained within a
901 @dfn{declaration scope} such as a C++ @code{class} or @code{namespace}
902 construct, should the point start inside it. If @ccmode fails to find
903 function beginnings or ends inside the current declaration scope, it
904 will search the enclosing scopes. If you want @ccmode to recognize
905 functions only at the top level@footnote{this was @ccmode{}'s
906 behaviour prior to version 5.32.}, set @code{c-defun-tatic} to
909 These functions are analogous to the Emacs built-in commands
910 @code{beginning-of-defun} and @code{end-of-defun}, except they
911 eliminate the constraint that the top-level opening brace of the defun
912 must be in column zero. See @ref{Defuns,,,@emacsman{},
913 @emacsmantitle{}}, for more information.
915 @item @kbd{C-M-a} (AWK Mode) (@code{c-awk-beginning-of-defun})
916 @itemx @kbd{C-M-e} (AWK Mode) (@code{c-awk-end-of-defun})
917 @kindex C-M-a (AWK Mode)
918 @kindex C-M-e (AWK Mode)
919 @findex c-awk-beginning-of-defun
920 @findex awk-beginning-of-defun (c-)
921 @findex c-awk-end-of-defun
922 @findex awk-end-of-defun (c-)
923 Move to the beginning or end of the current or next AWK defun. These
924 commands can take prefix-arguments, their functionality being entirely
925 equivalent to @code{beginning-of-defun} and @code{end-of-defun}.
927 AWK Mode @dfn{defuns} are either pattern/action pairs (either of which
928 might be implicit) or user defined functions. Having the @samp{@{} and
929 @samp{@}} (if there are any) in column zero, as is suggested for some
930 modes, is neither necessary nor helpful in AWK mode.
932 @item @kbd{M-a} (@code{c-beginning-of-statement})
933 @itemx @kbd{M-e} (@code{c-end-of-statement})
936 @findex c-beginning-of-statement
937 @findex c-end-of-statement
938 @findex beginning-of-statement (c-)
939 @findex end-of-statement (c-)
940 Move to the beginning or end of the innermost C statement. If point
941 is already there, move to the next beginning or end of a statement,
942 even if that means moving into a block. (Use @kbd{C-M-b} or
943 @kbd{C-M-f} to move over a balanced block.) A prefix argument @var{n}
944 means move over @var{n} statements.
946 If point is within or next to a comment or a string which spans more
947 than one line, these commands move by sentences instead of statements.
949 When called from a program, these functions take three optional
950 arguments: the repetition count, a buffer position limit which is the
951 farthest back to search for the syntactic context, and a flag saying
952 whether to do sentence motion in or near comments and multiline
955 @item @kbd{C-c C-u} (@code{c-up-conditional})
957 @findex c-up-conditional
958 @findex up-conditional (c-)
959 Move back to the containing preprocessor conditional, leaving the mark
960 behind. A prefix argument acts as a repeat count. With a negative
961 argument, move forward to the end of the containing preprocessor
964 @samp{#elif} is treated like @samp{#else} followed by @samp{#if}, so the
965 function stops at them when going backward, but not when going
968 This key sequence is not bound in AWK Mode, which doesn't have
969 preprocessor statements.
971 @item @kbd{M-x c-up-conditional-with-else}
972 @findex c-up-conditional-with-else
973 @findex up-conditional-with-else (c-)
974 A variety of @code{c-up-conditional} that also stops at @samp{#else}
975 lines. Normally those lines are ignored.
977 @item @kbd{M-x c-down-conditional}
978 @findex c-down-conditional
979 @findex down-conditional (c-)
980 Move forward into the next nested preprocessor conditional, leaving
981 the mark behind. A prefix argument acts as a repeat count. With a
982 negative argument, move backward into the previous nested preprocessor
985 @samp{#elif} is treated like @samp{#else} followed by @samp{#if}, so the
986 function stops at them when going forward, but not when going backward.
988 @item @kbd{M-x c-down-conditional-with-else}
989 @findex c-down-conditional-with-else
990 @findex down-conditional-with-else (c-)
991 A variety of @code{c-down-conditional} that also stops at @samp{#else}
992 lines. Normally those lines are ignored.
994 @item @kbd{C-c C-p} (@code{c-backward-conditional})
995 @itemx @kbd{C-c C-n} (@code{c-forward-conditional})
998 @findex c-backward-conditional
999 @findex c-forward-conditional
1000 @findex backward-conditional (c-)
1001 @findex forward-conditional (c-)
1002 Move backward or forward across a preprocessor conditional, leaving
1003 the mark behind. A prefix argument acts as a repeat count. With a
1004 negative argument, move in the opposite direction.
1006 These key sequences are not bound in AWK Mode, which doesn't have
1007 preprocessor statements.
1009 @item @kbd{M-x c-backward-into-nomenclature}
1010 @itemx @kbd{M-x c-forward-into-nomenclature}
1011 @findex c-backward-into-nomenclature
1012 @findex c-forward-into-nomenclature
1013 @findex backward-into-nomenclature (c-)
1014 @findex forward-into-nomenclature (c-)
1015 A popular programming style, especially for object-oriented languages
1016 such as C++ is to write symbols in a mixed case format, where the
1017 first letter of each word is capitalized, and not separated by
1018 underscores. E.g. @samp{SymbolsWithMixedCaseAndNoUnderlines}.
1020 These commands move backward or forward to the beginning of the next
1021 capitalized word. With prefix argument @var{n}, move @var{n} times.
1022 If @var{n} is negative, move in the opposite direction.
1024 Note that these two commands have been superseded by
1025 @code{subword-mode}, which you should use instead. @xref{Subword
1026 Movement}. They might be removed from a future release of @ccmode{}.
1029 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1030 @node Filling and Breaking, Minor Modes, Movement Commands, Commands
1031 @comment node-name, next, previous, up
1032 @section Filling and Line Breaking Commands
1033 @cindex text filling
1034 @cindex line breaking
1035 @cindex comment handling
1036 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1038 Since there's a lot of normal text in comments and string literals,
1039 @ccmode{} provides features to edit these like in text mode. The goal
1040 is to do it seamlessly, i.e. you can use auto fill mode, sentence and
1041 paragraph movement, paragraph filling, adaptive filling etc. wherever
1042 there's a piece of normal text without having to think much about it.
1043 @ccmode{} keeps the indentation, fixes suitable comment line prefixes,
1046 You can configure the exact way comments get filled and broken, and
1047 where Emacs does auto-filling (see @pxref{Custom Filling and
1048 Breaking}). Typically, the style system (@pxref{Styles}) will have
1049 set this up for you, so you probably won't have to bother.
1051 @findex auto-fill-mode
1052 @cindex Auto Fill mode
1053 @cindex paragraph filling
1054 Line breaks are by default handled (almost) the same regardless of
1055 whether they are made by auto fill mode (@pxref{Auto Fill,,,
1056 @emacsman{}, @emacsmantitle{}}), by paragraph filling (e.g. with
1057 @kbd{M-q}), or explicitly with @kbd{M-j} or similar methods. In
1058 string literals, the new line gets the same indentation as the
1059 previous nonempty line.@footnote{You can change this default by
1060 setting the @code{string} syntactic symbol (@pxref{Syntactic Symbols}
1061 and @pxref{Customizing Indentation})}.
1064 @item @kbd{M-q} (@code{c-fill-paragraph})
1066 @findex c-fill-paragraph
1067 @findex fill-paragraph (c-)
1068 @cindex Javadoc markup
1069 @cindex Pike autodoc markup
1070 This command fills multiline string literals and both block
1071 and line style comments. In Java buffers, the Javadoc markup words
1072 are recognized as paragraph starters. The line oriented Pike autodoc
1073 markup words are recognized in the same way in Pike mode.
1075 The formatting of the starters (@code{/*}) and enders (@code{*/}) of
1076 block comments are kept as they were before the filling. I.e., if
1077 either the starter or ender were on a line of its own, then it stays
1078 on its own line; conversely, if the delimiter has comment text on its
1079 line, it keeps at least one word of that text with it on the line.
1081 This command is the replacement for @code{fill-paragraph} in @ccmode{}
1084 @item @kbd{M-j} (@code{c-indent-new-comment-line})
1086 @findex c-indent-new-comment-line
1087 @findex indent-new-comment-line (c-)
1088 This breaks the current line at point and indents the new line. If
1089 point was in a comment, the new line gets the proper comment line
1090 prefix. If point was inside a macro, a backslash is inserted before
1091 the line break. It is the replacement for
1092 @code{indent-new-comment-line}.
1094 @item @kbd{M-x c-context-line-break}
1095 @findex c-context-line-break
1096 @findex context-line-break (c-)
1097 Insert a line break suitable to the context: If the point is inside a
1098 comment, the new line gets the suitable indentation and comment line
1099 prefix like @code{c-indent-new-comment-line}. In normal code it's
1100 indented like @code{newline-and-indent} would do. In macros it acts
1101 like @code{newline-and-indent} but additionally inserts and optionally
1102 aligns the line ending backslash so that the macro remains unbroken.
1103 @xref{Custom Macros}, for details about the backslash alignment. In a
1104 string, a backslash is inserted only if the string is within a
1105 macro@footnote{In GCC, unescaped line breaks within strings are
1108 This function is not bound to a key by default, but it's intended to be
1109 used on the @kbd{RET} key. If you like the behavior of
1110 @code{newline-and-indent} on @kbd{RET}, you should consider switching to
1111 this function. @xref{Sample .emacs File}.
1113 @item @kbd{M-x c-context-open-line}
1114 @findex c-context-open-line
1115 @findex context-open-line (c-)
1116 This is to @kbd{C-o} (@kbd{M-x open-line}) as
1117 @code{c-context-line-break} is to @kbd{RET}. I.e. it works just like
1118 @code{c-context-line-break} but leaves the point before the inserted
1123 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1124 @node Minor Modes, Electric Keys, Filling and Breaking, Commands
1125 @comment node-name, next, previous, up
1126 @section Minor Modes
1128 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1130 @ccmode{} contains several minor-mode-like features that you might
1131 find useful while writing new code or editing old code:
1135 When this is enabled, certain visible characters cause reformatting as
1136 they are typed. This is normally helpful, but can be a nuisance when
1137 editing chaotically formatted code. It can also be disconcerting,
1138 especially for users who are new to @ccmode{}.
1139 @item auto-newline mode
1140 This automatically inserts newlines where you'd probably want to type
1141 them yourself, e.g. after typing @samp{@}}s. Its action is suppressed
1142 when electric mode is disabled.
1143 @item hungry-delete mode
1144 This lets you delete a contiguous block of whitespace with a single
1145 key - for example, the newline and indentation just inserted by
1146 auto-newline when you want to back up and write a comment after the
1149 This mode makes basic word movement commands like @kbd{M-f}
1150 (@code{forward-word}) and @kbd{M-b} (@code{backward-word}) treat the
1151 parts of sillycapsed symbols as different words.
1152 E.g. @samp{NSGraphicsContext} is treated as three words @samp{NS},
1153 @samp{Graphics}, and @samp{Context}.
1154 @item syntactic-indentation mode
1155 When this is enabled (which it normally is), indentation commands such
1156 as @kbd{C-j} indent lines of code according to their syntactic
1157 structure. Otherwise, a line is simply indented to the same level as
1158 the previous one and @kbd{@key{TAB}} adjusts the indentation in steps
1159 of `c-basic-offset'.
1162 Full details on how these minor modes work are at @ref{Electric Keys},
1163 @ref{Auto-newlines}, @ref{Hungry WS Deletion}, @ref{Subword Movement},
1164 and @ref{Indentation Engine Basics}.
1166 You can toggle each of these minor modes on and off, and you can
1167 configure @ccmode{} so that it starts up with your favourite
1168 combination of them (@pxref{Sample .emacs File}). By default, when
1169 you initialize a buffer, electric mode and syntactic-indentation mode
1170 are enabled but the other two modes are disabled.
1172 @ccmode{} displays the current state of the first four of these minor
1173 modes on the modeline by appending letters to the major mode's name,
1174 one letter for each enabled minor mode - @samp{l} for electric mode,
1175 @samp{a} for auto-newline mode, @samp{h} for hungry delete mode, and
1176 @samp{w} for subword mode. If all these modes were enabled, you'd see
1177 @samp{C/lahw}@footnote{The @samp{C} would be replaced with the name of
1178 the language in question for the other languages @ccmode{} supports.}.
1180 Here are the commands to toggle these modes:
1183 @item @kbd{C-c C-l} (@code{c-toggle-electric-state})
1185 @findex c-toggle-electric-state
1186 @findex toggle-electric-state (c-)
1187 Toggle electric minor mode. When the command turns the mode off, it
1188 also suppresses auto-newline mode.
1190 @item @kbd{C-c C-a} (@code{c-toggle-auto-newline})
1192 @findex c-toggle-auto-newline
1193 @findex toggle-auto-newline (c-)
1194 Toggle auto-newline minor mode. When the command turns the mode on,
1195 it also enables electric minor mode.
1197 @item @kbd{M-x c-toggle-hungry-state}@footnote{Prior to @ccmode{} 5.31, this command was bound to @kbd{C-c C-d}.}
1198 @findex c-toggle-hungry-state
1199 @findex toggle-hungry-state (c-)
1200 Toggle hungry-delete minor mode.
1202 @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}.}
1203 @findex c-toggle-auto-hungry-state
1204 @findex toggle-auto-hungry-state (c-)
1205 Toggle both auto-newline and hungry delete minor modes.
1207 @item @kbd{C-c C-w} (@code{M-x subword-mode})
1209 @findex subword-mode
1210 Toggle subword mode.
1212 @item @kbd{M-x c-toggle-syntactic-indentation}
1213 @findex c-toggle-syntactic-indentation
1214 @findex toggle-syntactic-indentation (c-)
1215 Toggle syntactic-indentation mode.
1218 Common to all the toggle functions above is that if they are called
1219 programmatically, they take an optional numerical argument. A
1220 positive value will turn on the minor mode (or both of them in the
1221 case of @code{c-toggle-auto-hungry-state}) and a negative value will
1222 turn it (or them) off.
1225 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1226 @node Electric Keys, Auto-newlines, Minor Modes, Commands
1227 @comment node-name, next, previous, up
1228 @section Electric Keys and Keywords
1229 @cindex electric characters
1230 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1232 Most punctuation keys provide @dfn{electric} behavior - as well as
1233 inserting themselves they perform some other action, such as
1234 reindenting the line. This reindentation saves you from having to
1235 reindent a line manually after typing, say, a @samp{@}}. A few
1236 keywords, such as @code{else}, also trigger electric action.
1238 You can inhibit the electric behavior described here by disabling
1239 electric minor mode (@pxref{Minor Modes}).
1241 Common to all these keys is that they only behave electrically when
1242 used in normal code (as contrasted with getting typed in a string
1243 literal or comment). Those which cause re-indentation do so only when
1244 @code{c-syntactic-indentation} has a non-@code{nil} value (which it
1247 These keys and keywords are:
1248 @c ACM, 2004/8/24: c-electric-pound doesn't check c-s-i: this is more
1249 @c like a bug in the code than a bug in this document. It'll get
1250 @c fixed in the code sometime.
1255 @findex c-electric-pound
1256 @findex electric-pound (c-)
1257 @vindex c-electric-pound-behavior
1258 @vindex electric-pound-behavior (c-)
1259 Pound (bound to @code{c-electric-pound}) is electric when typed as the
1260 first non-whitespace character on a line and not within a macro
1261 definition. In this case, the variable @code{c-electric-pound-behavior}
1262 is consulted for the electric behavior. This variable takes a list
1263 value, although the only element currently defined is @code{alignleft},
1264 which tells this command to force the @samp{#} character into column
1265 zero. This is useful for entering preprocessor macro definitions.
1267 Pound is not electric in AWK buffers, where @samp{#} starts a comment,
1268 and is bound to @code{self-insert-command} like any typical printable
1270 @c ACM, 2004/8/24: Change this (and the code) to do AWK comment
1277 @findex c-electric-star
1278 @findex electric-star (c-)
1279 @findex c-electric-slash
1280 @findex electric-slash (c-)
1281 A star (bound to @code{c-electric-star}) or a slash
1282 (@code{c-electric-slash}) causes reindentation when you type it as the
1283 second component of a C style block comment opener (@samp{/*}) or a
1284 C++ line comment opener (@samp{//}) respectively, but only if the
1285 comment opener is the first thing on the line (i.e. there's only
1286 whitespace before it).
1288 Additionally, you can configure @ccmode{} so that typing a slash at
1289 the start of a line within a block comment will terminate the
1290 comment. You don't need to have electric minor mode enabled to get
1291 this behavior. @xref{Clean-ups}.
1293 In AWK mode, @samp{*} and @samp{/} do not delimit comments and are not
1300 @findex c-electric-lt-gt
1301 @findex electric-lt-gt (c-)
1302 A less-than or greater-than sign (bound to @code{c-electric-lt-gt}) is
1303 electric in two circumstances: when it is an angle bracket in a C++
1304 @samp{template} declaration (and similar constructs in other
1305 languages) and when it is the second of two @kbd{<} or @kbd{>}
1306 characters in a C++ style stream operator. In either case, the line
1307 is reindented. Angle brackets in C @samp{#include} directives are not
1314 @findex c-electric-paren
1315 @findex electric-paren (c-)
1316 The normal parenthesis characters @samp{(} and @samp{)} (bound to
1317 @code{c-electric-paren}) reindent the current line. This is useful
1318 for getting the closing parenthesis of an argument list aligned
1321 You can also configure @ccmode{} to insert a space automatically
1322 between a function name and the @samp{(} you've just typed, and to
1323 remove it automatically after typing @samp{)}, should the argument
1324 list be empty. You don't need to have electric minor mode enabled to
1325 get these actions. @xref{Clean-ups}.
1331 @findex c-electric-brace
1332 @findex electric-brace (c-)
1333 Typing a brace (bound to @code{c-electric-brace}) reindents the
1334 current line. Also, one or more newlines might be inserted if
1335 auto-newline minor mode is enabled. @xref{Auto-newlines}.
1336 Additionally, you can configure @ccmode{} to compact excess whitespace
1337 inserted by auto-newline mode in certain circumstances.
1342 @findex c-electric-colon
1343 @findex electric-colon (c-)
1344 Typing a colon (bound to @code{c-electric-colon}) reindents the
1345 current line. Additionally, one or more newlines might be inserted if
1346 auto-newline minor mode is enabled. @xref{Auto-newlines}. If you
1347 type a second colon immediately after such an auto-newline, by default
1348 the whitespace between the two colons is removed, leaving a C++ scope
1349 operator. @xref{Clean-ups}.
1351 If you prefer, you can insert @samp{::} in a single operation,
1352 avoiding all these spurious reindentations, newlines, and clean-ups.
1353 @xref{Other Commands}.
1359 @findex c-electric-semi&comma
1360 @findex electric-semi&comma (c-)
1361 Typing a semicolon or comma (bound to @code{c-electric-semi&comma})
1362 reindents the current line. Also, a newline might be inserted if
1363 auto-newline minor mode is enabled. @xref{Auto-newlines}.
1364 Additionally, you can configure @ccmode{} so that when auto-newline
1365 has inserted whitespace after a @samp{@}}, it will be removed again
1366 when you type a semicolon or comma just after it. @xref{Clean-ups}.
1370 @deffn Command c-electric-continued-statement
1371 @findex electric-continued-statement (c-)
1373 Certain keywords are electric, causing reindentation when they are
1374 preceded only by whitespace on the line. The keywords are those that
1375 continue an earlier statement instead of starting a new one:
1376 @code{else}, @code{while}, @code{catch} (only in C++ and Java) and
1377 @code{finally} (only in Java).
1383 for (i = 0; i < 17; i++)
1385 res += a[i]->offset;
1390 Here, the @code{else} should be indented like the preceding @code{if},
1391 since it continues that statement. @ccmode{} will automatically
1392 reindent it after the @code{else} has been typed in full, since only
1393 then is it possible to decide whether it's a new statement or a
1394 continuation of the preceding @code{if}.
1399 @ccmode{} uses Abbrev mode (@pxref{Abbrevs,,, @emacsman{}, @emacsmantitle{}})
1400 to accomplish this. It's therefore turned on by default in all language
1401 modes except IDL mode, since CORBA IDL doesn't have any statements.
1405 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1406 @node Auto-newlines, Hungry WS Deletion, Electric Keys, Commands
1407 @comment node-name, next, previous, up
1408 @section Auto-newline Insertion
1409 @cindex auto-newline
1410 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1412 When you have @dfn{Auto-newline minor mode} enabled (@pxref{Minor
1413 Modes}), @ccmode{} inserts newlines for you automatically (in certain
1414 syntactic contexts) when you type a left or right brace, a colon, a
1415 semicolon, or a comma. Sometimes a newline appears before the
1416 character you type, sometimes after it, sometimes both.
1418 Auto-newline only triggers when the following conditions hold:
1422 Auto-newline minor mode is enabled, as evidenced by the indicator
1423 @samp{a} after the mode name on the modeline (e.g. @samp{C/a} or
1427 The character was typed at the end of a line, or with only whitespace
1428 after it, and possibly a @samp{\} escaping the newline.
1431 The character is not on its own line already. (This applies only to
1432 insertion of a newline @emph{before} the character.)
1436 @cindex syntactic whitespace
1437 The character was not typed inside of a literal @footnote{A
1438 @dfn{literal} is defined as any comment, string, or preprocessor macro
1439 definition. These constructs are also known as @dfn{syntactic
1440 whitespace} since they are usually ignored when scanning C code.}.
1443 No numeric argument was supplied to the command (i.e. it was typed as
1444 normal, with no @kbd{C-u} prefix).
1447 You can configure the precise circumstances in which newlines get
1448 inserted (see @pxref{Custom Auto-newlines}). Typically, the style
1449 system (@pxref{Styles}) will have set this up for you, so you probably
1450 won't have to bother.
1452 Sometimes @ccmode{} inserts an auto-newline where you don't want one,
1453 such as after a @samp{@}} when you're about to type a @samp{;}.
1454 Hungry deletion can help here (@pxref{Hungry WS Deletion}), or you can
1455 activate an appropriate @dfn{clean-up}, which will remove the excess
1456 whitespace after you've typed the @samp{;}. See @ref{Clean-ups} for a
1457 full description. See also @ref{Electric Keys} for a summary of
1458 clean-ups listed by key.
1461 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1462 @node Hungry WS Deletion, Subword Movement, Auto-newlines, Commands
1463 @comment node-name, next, previous, up
1464 @section Hungry Deletion of Whitespace
1465 @cindex hungry-deletion
1466 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1468 If you want to delete an entire block of whitespace at point, you can
1469 use @dfn{hungry deletion}. This deletes all the contiguous whitespace
1470 either before point or after point in a single operation.
1471 ``Whitespace'' here includes tabs and newlines, but not comments or
1472 preprocessor commands. Hungry deletion can markedly cut down on the
1473 number of times you have to hit deletion keys when, for example,
1474 you've made a mistake on the preceding line and have already pressed
1477 Hungry deletion is a simple feature that some people find extremely
1478 useful. In fact, you might find yourself wanting it in @strong{all}
1481 Loosely speaking, in what follows, @dfn{@key{DEL}} means ``the
1482 backspace key'' and @dfn{@key{DELETE}} means ``the forward delete
1483 key''. This is discussed in more detail below.
1485 There are two different ways you can use hungry deletion:
1488 @item Using @dfn{Hungry Delete Mode} with @kbd{@key{DEL}} and @kbd{C-d}
1489 Here you toggle Hungry Delete minor mode with @kbd{M-x
1490 c-toggle-hungry-state}@footnote{Prior to @ccmode{} 5.31, this command
1491 was bound to @kbd{C-c C-d}. @kbd{C-c C-d} is now the default binding
1492 for @code{c-hungry-delete-forward}.} (@pxref{Minor Modes}.) This
1493 makes @kbd{@key{DEL}} and @kbd{C-d} do backwards and forward hungry
1497 @item @kbd{@key{DEL}} (@code{c-electric-backspace})
1499 @findex c-electric-backspace
1500 @findex electric-backspace (c-)
1501 This command is run by default when you hit the @kbd{DEL} key. When
1502 hungry delete mode is enabled, it deletes any amount of whitespace in
1503 the backwards direction. Otherwise, or when used with a prefix
1504 argument or in a literal (@pxref{Auto-newlines}), the command just
1505 deletes backwards in the usual way. (More precisely, it calls the
1506 function contained in the variable @code{c-backspace-function},
1507 passing it the prefix argument, if any.)
1509 @item @code{c-backspace-function}
1510 @vindex c-backspace-function
1511 @vindex backspace-function (c-)
1512 @findex backward-delete-char-untabify
1513 Hook that gets called by @code{c-electric-backspace} when it doesn't
1514 do an ``electric'' deletion of the preceding whitespace. The default
1515 value is @code{backward-delete-char-untabify}
1516 (@pxref{Deletion,,,@lispref{}, @lispreftitle{}}, the function which
1517 deletes a single character.
1519 @item @kbd{C-d} (@code{c-electric-delete-forward})
1521 @findex c-electric-delete-forward
1522 @findex electric-delete-forward (c-)
1523 This function, which is bound to @kbd{C-d} by default, works just like
1524 @code{c-electric-backspace} but in the forward direction. When it
1525 doesn't do an ``electric'' deletion of the following whitespace, it
1526 just does @code{delete-char}, more or less. (Strictly speaking, it
1527 calls the function in @code{c-delete-function} with the prefix
1530 @item @code{c-delete-function}
1531 @vindex c-delete-function
1532 @vindex delete-function (c-)
1534 Hook that gets called by @code{c-electric-delete-forward} when it
1535 doesn't do an ``electric'' deletion of the following whitespace. The
1536 default value is @code{delete-char}.
1539 @item Using Distinct Bindings
1540 The other (newer and recommended) way to use hungry deletion is to
1541 perform @code{c-hungry-delete-backwards} and
1542 @code{c-hungry-delete-forward} directly through their key sequences
1543 rather than using the minor mode toggling.
1546 @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}.}
1547 @kindex C-c C-<backspace>
1548 @kindex C-c <backspace>
1551 @findex c-hungry-delete-backwards
1552 @findex hungry-delete-backwards (c-)
1553 Delete any amount of whitespace in the backwards direction (regardless
1554 whether hungry-delete mode is enabled or not). This command is bound
1555 to both @kbd{C-c C-@key{DEL}} and @kbd{C-c @key{DEL}}, since the more
1556 natural one, @kbd{C-c C-@key{DEL}}, is sometimes difficult to type at
1557 a character terminal.
1559 @item @kbd{C-c C-d}, @kbd{C-c C-@key{DELETE}}, or @kbd{C-c @key{DELETE}} (@code{c-hungry-delete-forward})
1561 @kindex C-c C-<DELETE>
1562 @kindex C-c <DELETE>
1563 @findex c-hungry-delete-forward
1564 @findex hungry-delete-forward (c-)
1565 Delete any amount of whitespace in the forward direction (regardless
1566 whether hungry-delete mode is enabled or not). This command is bound
1567 to both @kbd{C-c C-@key{DELETE}} and @kbd{C-c @key{DELETE}} for the
1568 same reason as for @key{DEL} above.
1575 When we talk about @kbd{@key{DEL}}, and @kbd{@key{DELETE}} above, we
1576 actually do so without connecting them to the physical keys commonly
1577 known as @key{Backspace} and @key{Delete}. The default bindings to
1578 those two keys depends on the flavor of (X)Emacs you are using.
1580 @findex c-electric-delete
1581 @findex electric-delete (c-)
1582 @findex c-hungry-delete
1583 @findex hungry-delete (c-)
1584 @vindex delete-key-deletes-forward
1585 In XEmacs 20.3 and beyond, the @key{Backspace} key is bound to
1586 @code{c-electric-backspace} and the @key{Delete} key is bound to
1587 @code{c-electric-delete}. You control the direction it deletes in by
1588 setting the variable @code{delete-key-deletes-forward}, a standard
1590 @c This variable is encapsulated by XEmacs's (defsubst delete-forward-p ...).
1591 When this variable is non-@code{nil}, @code{c-electric-delete} will do
1592 forward deletion with @code{c-electric-delete-forward}, otherwise it
1593 does backward deletion with @code{c-electric-backspace}. Similarly,
1594 @kbd{C-c @key{Delete}} and @kbd{C-c C-@key{Delete}} are bound to
1595 @code{c-hungry-delete} which is controlled in the same way by
1596 @code{delete-key-deletes-forward}.
1598 @findex normal-erase-is-backspace-mode
1600 Emacs 21 and later automatically binds @key{Backspace} and
1601 @key{Delete} to @kbd{DEL} and @kbd{C-d} according to your environment,
1602 and @ccmode{} extends those bindings to @kbd{C-c C-@key{Backspace}}
1603 etc. If you need to change the bindings through
1604 @code{normal-erase-is-backspace-mode} then @ccmode{} will also adapt
1605 its extended bindings accordingly.
1607 In earlier (X)Emacs versions, @ccmode{} doesn't bind either
1608 @key{Backspace} or @key{Delete} directly. Only the key codes
1609 @kbd{DEL} and @kbd{C-d} are bound, and it's up to the default bindings
1610 to map the physical keys to them. You might need to modify this
1611 yourself if the defaults are unsuitable.
1613 Getting your @key{Backspace} and @key{Delete} keys properly set up can
1614 sometimes be tricky. The information in @ref{DEL Does Not
1615 Delete,,,emacs, GNU Emacs Manual}, might be helpful if you're having
1616 trouble with this in GNU Emacs.
1619 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1620 @node Subword Movement, Other Commands, Hungry WS Deletion, Commands
1621 @comment node-name, next, previous, up
1622 @section Subword Movement and Editing
1623 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1625 @cindex nomenclature
1627 In spite of the GNU Coding Standards, it is popular to name a symbol
1628 by mixing uppercase and lowercase letters, e.g. @samp{GtkWidget},
1629 @samp{EmacsFrameClass}, or @samp{NSGraphicsContext}. Here we call
1630 these mixed case symbols @dfn{nomenclatures}. Also, each capitalized
1631 (or completely uppercase) part of a nomenclature is called a
1632 @dfn{subword}. Here are some examples:
1634 @multitable {@samp{NSGraphicsContext}} {@samp{NS}, @samp{Graphics}, and @samp{Context}}
1635 @c This could be converted to @headitem when we require Texinfo 4.7
1637 @item @b{Nomenclature}
1643 @item ---------------------------------------------------------
1645 @item @samp{GtkWindow}
1646 @tab @samp{Gtk} and @samp{Window}
1647 @item @samp{EmacsFrameClass}
1648 @tab @samp{Emacs}, @samp{Frame}, and @samp{Class}
1649 @item @samp{NSGraphicsContext}
1650 @tab @samp{NS}, @samp{Graphics}, and @samp{Context}
1653 The subword minor mode replaces the basic word oriented movement and
1654 editing commands with variants that recognize subwords in a
1655 nomenclature and treat them as separate words:
1657 @findex c-forward-subword
1658 @findex forward-subword (c-)
1659 @findex c-backward-subword
1660 @findex backward-subword (c-)
1661 @findex c-mark-subword
1662 @findex mark-subword (c-)
1663 @findex c-kill-subword
1664 @findex kill-subword (c-)
1665 @findex c-backward-kill-subword
1666 @findex backward-kill-subword (c-)
1667 @findex c-transpose-subwords
1668 @findex transpose-subwords (c-)
1669 @findex c-capitalize-subword
1670 @findex capitalize-subword (c-)
1671 @findex c-upcase-subword
1672 @findex upcase-subword (c-)
1673 @findex c-downcase-subword
1674 @findex downcase-subword (c-)
1675 @multitable @columnfractions .20 .40 .40
1676 @c This could be converted to @headitem when we require Texinfo 4.7
1678 @item @b{Key} @tab @b{Word oriented command} @tab @b{Subword oriented command}
1681 @item Key @tab Word oriented command @tab Subword oriented command
1682 @item ----------------------------------------------------------------------------
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 () (subword-mode 1)))
1709 As a bonus, you can also use @code{subword-mode} in non-@ccmode{}
1710 buffers by typing @kbd{M-x 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
1891 hardware. @xref{Font Lock,,,@emacsman{}, @emacsmantitle{}}.
1894 @cindex user defined types
1895 @cindex types, user defined
1897 Since user defined types are hard to recognize you can provide
1898 additional regexps to match those you use:
1900 @defopt c-font-lock-extra-types
1901 @defoptx c++-font-lock-extra-types
1902 @defoptx objc-font-lock-extra-types
1903 @defoptx java-font-lock-extra-types
1904 @defoptx idl-font-lock-extra-types
1905 @defoptx pike-font-lock-extra-types
1906 For each language there's a variable @code{*-font-lock-extra-types},
1907 where @samp{*} stands for the language in question. It contains a list
1908 of regexps that matches identifiers that should be recognized as types,
1909 e.g. @samp{\\sw+_t} to recognize all identifiers ending with @samp{_t}
1910 as is customary in C code. Each regexp should not match more than a
1913 The default values contain regexps for many types in standard runtime
1914 libraries that are otherwise difficult to recognize, and patterns for
1915 standard type naming conventions like the @samp{_t} suffix in C and C++.
1916 Java, Objective-C and Pike have as a convention to start class names
1917 with capitals, so there are patterns for that in those languages.
1919 Despite the names of these variables, they are not only used for
1920 fontification but in other places as well where @ccmode{} needs to
1925 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1926 @node Faces, Doc Comments, Font Locking Preliminaries, Font Locking
1927 @comment node-name, next, previous, up
1930 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1932 @ccmode{} attempts to use the standard faces for programming languages
1933 in accordance with their intended purposes as far as possible. No extra
1934 faces are currently provided, with the exception of a replacement face
1935 @code{c-invalid-face} for emacsen that don't provide
1936 @code{font-lock-warning-face}.
1940 @vindex font-lock-comment-face
1941 Normal comments are fontified in @code{font-lock-comment-face}.
1944 @vindex font-lock-doc-face
1945 @vindex font-lock-doc-string-face
1946 @vindex font-lock-comment-face
1947 Comments that are recognized as documentation (@pxref{Doc Comments})
1948 get @code{font-lock-doc-face} (Emacs) or
1949 @code{font-lock-doc-string-face} (XEmacs) if those faces exist. If
1950 they don't then @code{font-lock-comment-face} is used.
1953 @vindex font-lock-string-face
1954 String and character literals are fontified in
1955 @code{font-lock-string-face}.
1958 @vindex font-lock-keyword-face
1959 Keywords are fontified with @code{font-lock-keyword-face}.
1962 @vindex font-lock-function-name-face
1963 @code{font-lock-function-name-face} is used for function names in
1964 declarations and definitions, and classes in those contexts. It's also
1965 used for preprocessor defines with arguments.
1968 @vindex font-lock-variable-name-face
1969 Variables in declarations and definitions, and other identifiers in such
1970 variable contexts, get @code{font-lock-variable-name-face}. It's also
1971 used for preprocessor defines without arguments.
1974 @vindex font-lock-constant-face
1975 @vindex font-lock-reference-face
1976 Builtin constants are fontified in @code{font-lock-constant-face} if it
1977 exists, @code{font-lock-reference-face} otherwise. As opposed to the
1978 preceding two faces, this is used on the names in expressions, and it's
1979 not used in declarations, even if there happen to be a @samp{const} in
1983 @vindex font-lock-type-face
1984 @code{font-lock-type-face} is put on types (both predefined and user
1985 defined) and classes in type contexts.
1988 @vindex font-lock-constant-face
1989 @vindex font-lock-reference-face
1990 Label identifiers get @code{font-lock-constant-face} if it exists,
1991 @code{font-lock-reference-face} otherwise.
1994 Name qualifiers and identifiers for scope constructs are fontified like
1998 Special markup inside documentation comments are also fontified like
2002 @vindex font-lock-preprocessor-face
2003 @vindex font-lock-builtin-face
2004 @vindex font-lock-reference-face
2005 Preprocessor directives get @code{font-lock-preprocessor-face} if it
2006 exists (i.e. XEmacs). In Emacs they get @code{font-lock-builtin-face}
2007 or @code{font-lock-reference-face}, for lack of a closer equivalent.
2010 @vindex font-lock-warning-face
2011 @vindex c-invalid-face
2012 @vindex invalid-face (c-)
2013 Some kinds of syntactic errors are fontified with
2014 @code{font-lock-warning-face} in Emacs. In older XEmacs versions
2015 there's no corresponding standard face, so there a special
2016 @code{c-invalid-face} is used, which is defined to stand out sharply by
2019 Note that it's not used for @samp{#error} or @samp{#warning} directives,
2020 since those aren't syntactic errors in themselves.
2024 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2025 @node Doc Comments, AWK Mode Font Locking, Faces, Font Locking
2026 @comment node-name, next, previous, up
2027 @section Documentation Comments
2028 @cindex documentation comments
2029 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2031 There are various tools to supply documentation in the source as
2032 specially structured comments, e.g. the standard Javadoc tool in Java.
2033 @ccmode{} provides an extensible mechanism to fontify such comments and
2034 the special markup inside them.
2036 @defopt c-doc-comment-style
2037 @vindex doc-comment-style (c-)
2038 This is a style variable that specifies which documentation comment
2039 style to recognize, e.g. @code{javadoc} for Javadoc comments.
2041 The value may also be a list of styles, in which case all of them are
2042 recognized simultaneously (presumably with markup cues that don't
2045 The value may also be an association list to specify different comment
2046 styles for different languages. The symbol for the major mode is then
2047 looked up in the alist, and the value of that element is interpreted as
2048 above if found. If it isn't found then the symbol `other' is looked up
2049 and its value is used instead.
2051 The default value for @code{c-doc-comment-style} is
2052 @w{@code{((java-mode . javadoc) (pike-mode . autodoc) (c-mode . gtkdoc))}}.
2054 Note that @ccmode{} uses this variable to set other variables that
2055 handle fontification etc. That's done at mode initialization or when
2056 you switch to a style which sets this variable. Thus, if you change it
2057 in some other way, e.g. interactively in a CC Mode buffer, you will need
2058 to do @kbd{M-x java-mode} (or whatever mode you're currently using) to
2061 @findex c-setup-doc-comment-style
2062 @findex setup-doc-comment-style (c-)
2063 Note also that when @ccmode{} starts up, the other variables are
2064 modified before the mode hooks are run. If you change this variable in
2065 a mode hook, you'll have to call @code{c-setup-doc-comment-style}
2066 afterwards to redo that work.
2069 @ccmode{} currently provides handing of the following doc comment
2074 @cindex Javadoc markup
2075 Javadoc comments, the standard tool in Java.
2078 @cindex Pike autodoc markup
2079 For Pike autodoc markup, the standard in Pike.
2082 @cindex GtkDoc markup
2083 For GtkDoc markup, widely used in the Gnome community.
2086 The above is by no means complete. If you'd like to see support for
2087 other doc comment styles, please let us know (@pxref{Mailing Lists and
2090 You can also write your own doc comment fontification support to use
2091 with @code{c-doc-comment-style}: Supply a variable or function
2092 @code{*-font-lock-keywords} where @samp{*} is the name you want to use
2093 in @code{c-doc-comment-style}. If it's a variable, it's prepended to
2094 @code{font-lock-keywords}. If it's a function, it's called at mode
2095 initialization and the result is prepended. For an example, see
2096 @code{javadoc-font-lock-keywords} in @file{cc-fonts.el}.
2098 If you add support for another doc comment style, please consider
2099 contributing it - send a note to @email{bug-cc-mode@@gnu.org}.
2102 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2103 @node AWK Mode Font Locking, , Doc Comments, Font Locking
2104 @comment node-name, next, previous, up
2105 @section AWK Mode Font Locking
2106 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2108 The general appearance of font-locking in AWK mode is much like in any
2109 other programming mode. @xref{Faces For Font Lock,,,elisp, GNU Emacs
2110 Lisp Reference Manual}.
2112 The following faces are, however, used in a non-standard fashion in
2116 @item @code{font-lock-variable-name-face}
2117 This face was intended for variable declarations. Since variables are
2118 not declared in AWK, this face is used instead for AWK system
2119 variables (such as @code{NF}) and ``Special File Names'' (such as
2120 @code{"/dev/stderr"}).
2122 @item @code{font-lock-builtin-face} (Emacs)/@code{font-lock-preprocessor-face} (XEmacs)
2123 This face is normally used for preprocessor directives in @ccmode{}.
2124 There are no such things in AWK, so this face is used instead for
2125 standard functions (such as @code{match}).
2127 @item @code{font-lock-string-face}
2128 As well as being used for strings, including localizable strings,
2129 (delimited by @samp{"} and @samp{_"}), this face is also used for AWK
2130 regular expressions (delimited by @samp{/}).
2132 @item @code{font-lock-warning-face} (Emacs)/@code{c-invalid-face} (XEmacs)
2133 This face highlights the following syntactically invalid AWK
2138 An unterminated string or regular expression. Here the opening
2139 delimiter (@samp{"} or @samp{/} or @samp{_"}) is displayed in
2140 @code{font-lock-warning-face}. This is most noticeable when typing in a
2141 new string/regular expression into a buffer, when the warning-face
2142 serves as a continual reminder to terminate the construct.
2144 AWK mode fontifies unterminated strings/regular expressions
2145 differently from other modes: Only the text up to the end of the line
2146 is fontified as a string (escaped newlines being handled correctly),
2147 rather than the text up to the next string quote.
2150 A space between the function name and opening parenthesis when calling
2151 a user function. The last character of the function name and the
2152 opening parenthesis are highlighted. This font-locking rule will
2153 spuriously highlight a valid concatenation expression where an
2154 identifier precedes a parenthesised expression. Unfortunately.
2157 Whitespace following the @samp{\} in what otherwise looks like an
2158 escaped newline. The @samp{\} is highlighted.
2163 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2164 @node Config Basics, Custom Filling and Breaking, Font Locking, Top
2165 @comment node-name, next, previous, up
2166 @chapter Configuration Basics
2167 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2169 @cindex Emacs Initialization File
2170 @cindex Configuration
2171 You configure @ccmode{} by setting Lisp variables and calling (and
2172 perhaps writing) Lisp functions@footnote{DON'T PANIC!!! This isn't
2173 difficult.}, which is usually done by adding code to an Emacs
2174 initialization file. This file might be @file{site-start.el} or
2175 @file{.emacs} or @file{init.el} or @file{default.el} or perhaps some
2176 other file. @xref{Init File,,,@emacsman{}, @emacsmantitle{}}. For
2177 the sake of conciseness, we just call this file ``your @file{.emacs}''
2178 throughout the rest of the manual.
2180 Several of these variables (currently 16), are known collectively as
2181 @dfn{style variables}. @ccmode{} provides a special mechanism, known
2182 as @dfn{styles} to make it easier to set these variables as a group,
2183 to ``inherit'' settings from one style into another, and so on. Style
2184 variables remain ordinary Lisp variables, whose values can be read and
2185 changed independently of the style system. @xref{Style Variables}.
2187 There are several ways you can write the code, depending on the
2188 precise effect you want---they are described further down on this page.
2189 If you are new to @ccmode{}, we suggest you begin with the simplest
2190 method, ``Top-level commands or the customization interface''.
2192 If you make conflicting settings in several of these ways, the way
2193 that takes precedence is the one that appears latest in this list:
2198 @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.}
2199 @itemx Top-level command or ``customization interface''
2201 @itemx File Local Variable setting
2205 Here is a summary of the different ways of writing your configuration
2209 @item Top-level commands or the ``customization interface''
2210 Most simply, you can write @code{setq} and similar commands at the top
2211 level of your @file{.emacs} file. When you load a @ccmode{} buffer,
2212 it initializes its configuration from these global values (at least,
2213 for those settings you have given values to), so it makes sense to
2214 have these @code{setq} commands run @emph{before} @ccmode{} is first
2215 initialized---in particular, before any call to @code{desktop-read}
2216 (@pxref{Saving Emacs Sessions,,, emacs, GNU Emacs Manual}). For
2217 example, you might set c-basic-offset thus:
2220 (setq c-basic-offset 4)
2223 You can use the more user friendly Customization interface instead,
2224 but this manual does not cover in detail how that works. To do this,
2225 start by typing @kbd{M-x customize-group @key{RET} c @key{RET}}.
2226 @xref{Easy Customization,,,@emacsman{}, @emacsmantitle{}}.
2227 @c The following note really belongs in the Emacs manual.
2228 Emacs normally writes the customizations at the end of your
2229 @file{.emacs} file. If you use @code{desktop-read}, you should edit
2230 your @file{.emacs} to place the call to @code{desktop-read} @emph{after}
2233 The first initialization of @ccmode{} puts a snapshot of the
2234 configuration settings into the special style @code{user}.
2235 @xref{Built-in Styles}.
2237 For basic use of Emacs, either of these ways of configuring is
2238 adequate. However, the settings are then the same in all @ccmode{}
2239 buffers and it can be clumsy to communicate them between programmers.
2240 For more flexibility, you'll want to use one (or both) of @ccmode{}'s
2241 more sophisticated facilities, hooks and styles.
2244 An Emacs @dfn{hook} is a place to put Lisp functions that you want
2245 Emacs to execute later in specific circumstances.
2246 @xref{Hooks,,,@lispref{}, @lispreftitle{}}. @ccmode{} supplies a main
2247 hook and a language-specific hook for each language it supports - any
2248 functions you put onto these hooks get executed as the last part of a
2249 buffer's initialization. Typically you put most of your customization
2250 within the main hook, and use the language-specific hooks to vary the
2251 customization settings between language modes. For example, if you
2252 wanted different (non-standard) values of @code{c-basic-offset} in C
2253 Mode and Java Mode buffers, you could do it like this:
2257 (defun my-c-mode-hook ()
2258 (setq c-basic-offset 3))
2259 (add-hook 'c-mode-hook 'my-c-mode-hook)
2261 (defun my-java-mode-hook ()
2262 (setq c-basic-offset 6))
2263 (add-hook 'java-mode-hook 'my-java-mode-hook)
2267 See @ref{CC Hooks} for more details on the use of @ccmode{} hooks.
2270 A @ccmode{} @dfn{style} is a coherent collection of customizations
2271 with a name. At any time, exactly one style is active in each
2272 @ccmode{} buffer, either the one you have selected or a default.
2273 @ccmode{} is delivered with several existing styles. Additionally,
2274 you can create your own styles, possibly based on these existing
2275 styles. If you worked in a programming team called the ``Free
2276 Group'', which had its own coding standards, you might well have this
2277 in your @file{.emacs} file:
2280 (setq c-default-style '((java-mode . "java")
2282 (other . "free-group-style")))
2285 See @ref{Styles} for fuller details on using @ccmode{} styles and how
2288 @item File Local Variable setting
2289 A @dfn{file local variable setting} is a setting which applies to an
2290 individual source file. You put this in a @dfn{local variables list},
2291 a special block at the end of the source file (@pxref{Specifying File
2292 Variables,,, @emacsman{}}).
2295 A @dfn{file style} is a rarely used variant of the ``style'' mechanism
2296 described above, which applies to an individual source file.
2297 @xref{File Styles}. You use this by setting certain special variables
2298 in a local variables list (@pxref{Specifying File Variables,,,
2301 @item Hooks with Styles
2302 For ultimate flexibility, you can use hooks and styles together. For
2303 example, if your team were developing a product which required a
2304 Linux driver, you'd probably want to use the ``linux'' style for the
2305 driver, and your own team's style for the rest of the code. You
2306 could achieve this with code like this in your @file{.emacs}:
2310 (defun my-c-mode-hook ()
2312 (if (and (buffer-file-name)
2313 (string-match "/usr/src/linux" (buffer-file-name)))
2315 "free-group-style")))
2316 (add-hook 'c-mode-hook 'my-c-mode-hook)
2320 In a programming team, a hook is a also a good place for each member
2321 to put his own personal preferences. For example, you might be the
2322 only person in your team who likes Auto-newline minor mode. You could
2323 have it enabled by default by placing the following in your
2328 (defun my-turn-on-auto-newline ()
2329 (c-toggle-auto-newline 1))
2330 (add-hook 'c-mode-common-hook 'my-turn-on-auto-newline)
2341 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2342 @node CC Hooks, Style Variables, Config Basics, Config Basics
2343 @comment node-name, next, previous, up
2346 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2347 @c The node name is "CC Hooks" rather than "Hooks" because of a bug in
2348 @c some older versions of Info, e.g. the info.el in GNU Emacs 21.3.
2349 @c If you go to "Config Basics" and hit <CR> on the xref to "CC
2350 @c Hooks" the function Info-follow-reference searches for "*Note: CC
2351 @c Hooks" from the beginning of the page. If this node were instead
2352 @c named "Hooks", that search would spuriously find "*Note:
2353 @c Hooks(elisp)" and go to the wrong node.
2355 @ccmode{} provides several hooks that you can use to customize the
2356 mode for your coding style. The main hook is
2357 @code{c-mode-common-hook}; typically, you'll put the bulk of your
2358 customizations here. In addition, each language mode has its own
2359 hook, allowing you to fine tune your settings individually for the
2360 different @ccmode{} languages, and there is a package initialization
2361 hook. Finally, there is @code{c-special-indent-hook}, which enables
2362 you to solve anomalous indentation problems. It is described in
2363 @ref{Other Indentation}, not here. All these hooks adhere to the
2364 standard Emacs conventions.
2366 When you open a buffer, @ccmode{} first initializes it with the
2367 currently active style (@pxref{Styles}). Then it calls
2368 @code{c-mode-common-hook}, and finally it calls the language-specific
2369 hook. Thus, any style settings done in these hooks will override
2370 those set by @code{c-default-style}.
2372 @defvar c-initialization-hook
2373 @vindex initialization-hook (c-)
2374 Hook run only once per Emacs session, when @ccmode{} is initialized.
2375 This is a good place to change key bindings (or add new ones) in any
2376 of the @ccmode{} key maps. @xref{Sample .emacs File}.
2379 @defvar c-mode-common-hook
2380 @vindex mode-common-hook (c-)
2381 Common hook across all languages. It's run immediately before the
2382 language specific hook.
2386 @defvarx c++-mode-hook
2387 @defvarx objc-mode-hook
2388 @defvarx java-mode-hook
2389 @defvarx idl-mode-hook
2390 @defvarx pike-mode-hook
2391 @defvarx awk-mode-hook
2392 The language specific mode hooks. The appropriate one is run as the
2393 last thing when you enter that language mode.
2396 Although these hooks are variables defined in @ccmode{}, you can give
2397 them values before @ccmode{}'s code is loaded---indeed, this is the
2398 only way to use @code{c-initialization-hook}. Their values aren't
2399 overwritten when @ccmode{} gets loaded.
2401 Here's a simplified example of what you can add to your @file{.emacs}
2402 file to do things whenever any @ccmode{} language is edited. See the
2403 Emacs manuals for more information on customizing Emacs via hooks.
2404 @xref{Sample .emacs File}, for a more complete sample @file{.emacs}
2408 (defun my-c-mode-common-hook ()
2409 ;; my customizations for all of c-mode and related modes
2410 (no-case-fold-search)
2412 (add-hook 'c-mode-common-hook 'my-c-mode-common-hook)
2415 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2416 @node Style Variables, Styles, CC Hooks, Config Basics
2417 @comment node-name, next, previous, up
2418 @section Style Variables
2420 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2422 @cindex style variables
2423 The variables that @ccmode{}'s style system control are called
2424 @dfn{style variables}. Note that style variables are ordinary Lisp
2425 variables, which the style system initializes; you can change their
2426 values at any time (e.g. in a hook function). The style system can
2427 also set other variables, to some extent. @xref{Styles}.
2429 @dfn{Style variables} are handled specially in several ways:
2433 Style variables are by default buffer-local variables. However, they
2434 can instead be made global by setting
2435 @code{c-style-variables-are-local-p} to @code{nil} before @ccmode{} is
2439 @vindex c-old-style-variable-behavior
2440 @vindex old-style-variable-behavior (c-)
2441 The default global binding of any style variable (with two exceptions
2442 - see below) is the special symbol @code{set-from-style}. When the
2443 style system initializes a buffer-local copy of a style variable for a
2444 @ccmode{} buffer, if its global binding is still that symbol then it
2445 will be set from the current style. Otherwise it will retain its
2446 global default@footnote{This is a big change from versions of
2447 @ccmode{} earlier than 5.26, where such settings would get overridden
2448 by the style system unless special precautions were taken. That was
2449 changed since it was counterintuitive and confusing, especially to
2450 novice users. If your configuration depends on the old overriding
2451 behavior, you can set the variable
2452 @code{c-old-style-variable-behavior} to non-@code{nil}.}. This
2453 ``otherwise'' happens, for example, when you've set the variable with
2454 @code{setq} at the top level of your @file{.emacs} (@pxref{Config
2458 The style variable @code{c-offsets-alist} (@pxref{c-offsets-alist}) is
2459 an association list with an element for each syntactic symbol. It's
2460 handled a little differently from the other style variables. It's
2461 default global binding is the empty list @code{nil}, rather than
2462 @code{set-from-style}. Before the style system is initialized, you
2463 can add individual elements to @code{c-offsets-alist} by calling
2464 @code{c-set-offset}(@pxref{c-offsets-alist}) just like you would set
2465 other style variables with @code{setq}. Those elements will then
2466 prevail when the style system later initializes a buffer-local copy of
2467 @code{c-offsets-alist}.
2470 The style variable @code{c-special-indent-hook} is also handled in a
2471 special way. Styles can only add functions to this hook, not remove
2472 them, so any global settings you put on it are always
2473 preserved@footnote{This did not change in version 5.26.}. The value
2474 you give this variable in a style definition can be either a function
2475 or a list of functions.
2478 The global bindings of the style variables get captured in the special
2479 @code{user} style when the style system is first initialized.
2480 @xref{Built-in Styles}, for details.
2483 The style variables are:@*
2484 @code{c-indent-comment-alist},
2485 @code{c-indent-comments-syntactically-p} (@pxref{Indentation
2487 @code{c-doc-comment-style} (@pxref{Doc Comments});@*
2488 @code{c-block-comment-prefix}, @code{c-comment-prefix-regexp}
2489 (@pxref{Custom Filling and Breaking});@*
2490 @code{c-hanging-braces-alist} (@pxref{Hanging Braces});@*
2491 @code{c-hanging-colons-alist} (@pxref{Hanging Colons});@*
2492 @code{c-hanging-semi&comma-criteria} (@pxref{Hanging Semicolons and
2494 @code{c-cleanup-list} (@pxref{Clean-ups});@*
2495 @code{c-basic-offset} (@pxref{Customizing Indentation});@*
2496 @code{c-offsets-alist} (@pxref{c-offsets-alist});@*
2497 @code{c-comment-only-line-offset} (@pxref{Comment Line-Up});@*
2498 @code{c-special-indent-hook}, @code{c-label-minimum-indentation}
2499 (@pxref{Other Indentation});@*
2500 @code{c-backslash-column}, @code{c-backslash-max-column}
2501 (@pxref{Custom Macros}).
2503 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2504 @node Styles, , Style Variables, Config Basics
2505 @comment node-name, next, previous, up
2508 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2510 By @dfn{style} we mean the layout of the code---things like how many
2511 columns to indent a block of code, whether an opening brace gets
2512 indented to the level of the code it encloses, or of the construct
2513 that introduces it, or ``hangs'' at the end of a line.
2515 Most people only need to edit code formatted in just a few well-defined
2516 and consistent styles. For example, their organization might impose a
2517 ``blessed'' style that all its programmers must conform to. Similarly,
2518 people who work on GNU software will have to use the GNU coding style.
2519 Some shops are more lenient, allowing a variety of coding styles, and as
2520 programmers come and go, there could be a number of styles in use. For
2521 this reason, @ccmode{} makes it convenient for you to set up logical
2522 groupings of customizations called @dfn{styles}, associate a single name
2523 for any particular style, and pretty easily start editing new or
2524 existing code using these styles.
2526 As an alternative to writing a style definition yourself, you can have
2527 @ccmode{} @dfn{guess} (at least part of) your style by looking at an
2528 already formatted piece of your code, @ref{Guessing the Style}.
2532 * Choosing a Style::
2534 * Guessing the Style::
2538 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2539 @node Built-in Styles, Choosing a Style, Styles, Styles
2540 @comment node-name, next, previous, up
2541 @subsection Built-in Styles
2542 @cindex styles, built-in
2543 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2545 If you're lucky, one of @ccmode{}'s built-in styles might be just
2546 what you're looking for. These are:
2551 Coding style blessed by the Free Software Foundation
2552 for C code in GNU programs.
2556 The classic Kernighan and Ritchie style for C code.
2560 Also known as ``Allman style'' after Eric Allman.
2563 @cindex Whitesmith style
2564 Popularized by the examples that came with Whitesmiths C, an early
2565 commercial C compiler.
2568 @cindex Stroustrup style
2569 The classic Stroustrup style for C++ code.
2572 @cindex Ellemtel style
2573 Popular C++ coding standards as defined by ``Programming in C++, Rules
2574 and Recommendations,'' Erik Nyquist and Mats Henricson,
2575 Ellemtel@footnote{This document is available at
2576 @uref{http://www.doc.ic.ac.uk/lab/cplus/c++.rules/} among other
2578 @c N.B. This URL was still valid at 2005/8/28 (ACM).
2582 C coding standard for Linux (the kernel).
2585 @cindex Python style
2586 C coding standard for Python extension modules@footnote{Python is a
2587 high level scripting language with a C/C++ foreign function interface.
2588 For more information, see @uref{http://www.python.org/}.}.
2592 The style for editing Java code. Note that the default
2593 value for @code{c-default-style} installs this style when you enter
2598 The style for editing AWK code. Note that the default value for
2599 @code{c-default-style} installs this style when you enter
2604 This is a special style created by you. It consists of the factory
2605 defaults for all the style variables as modified by the customizations
2606 you do either with the Customization interface or by writing
2607 @code{setq}s and @code{c-set-offset}s at the top level of your
2608 @file{.emacs} file (@pxref{Config Basics}). The style system creates
2609 this style as part of its initialization and doesn't modify it
2614 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2615 @node Choosing a Style, Adding Styles, Built-in Styles, Styles
2616 @comment node-name, next, previous, up
2617 @subsection Choosing a Style
2618 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2620 When you create a new buffer, its style will be set from
2621 @code{c-default-style}. The factory default is the style @code{gnu},
2622 except in Java and AWK modes where it's @code{java} and @code{awk}.
2624 Remember that if you set a style variable with the Customization
2625 interface or at the top level of your @file{.emacs} file before the
2626 style system is initialized (@pxref{Config Basics}), this setting will
2627 override the one that the style system would have given the variable.
2629 To set a buffer's style interactively, use the command @kbd{C-c .}
2630 (@pxref{Other Commands}). To set it from a file's local variable
2631 list, @ref{File Styles}.
2633 @defopt c-default-style
2634 @vindex default-style (c-)
2635 This variable specifies which style to install by default in new
2636 buffers. It takes either a style name string, or an association list
2637 of major mode symbols to style names:
2641 When @code{c-default-style} is a string, it must be an existing style
2642 name. This style is then used for all modes.
2645 When @code{c-default-style} is an association list, the mode language
2646 is looked up to find a style name string.
2649 If @code{c-default-style} is an association list where the mode
2650 language mode isn't found then the special symbol @samp{other} is
2651 looked up. If it's found then the associated style is used.
2654 If @samp{other} is not found then the @samp{gnu} style is used.
2657 In all cases, the style described in @code{c-default-style} is installed
2658 @emph{before} the language hooks are run, so you can always override
2659 this setting by including an explicit call to @code{c-set-style} in your
2660 language mode hook, or in @code{c-mode-common-hook}.
2662 The standard value of @code{c-default-style} is @w{@code{((java-mode
2663 . "java") (awk-mode . "awk") (other . "gnu"))}}.
2666 @defvar c-indentation-style
2667 @vindex indentation-style (c-)
2668 This variable always contains the buffer's current style name, as a
2672 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2673 @node Adding Styles, Guessing the Style, Choosing a Style, Styles
2674 @comment node-name, next, previous, up
2675 @subsection Adding and Amending Styles
2676 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2678 If none of the built-in styles is appropriate, you'll probably want to
2679 create a new @dfn{style definition}, possibly based on an existing
2680 style. To do this, put the new style's settings into a list with the
2681 following format - the list can then be passed as an argument to the
2682 function @code{c-add-style}. You can see an example of a style
2683 definition in @ref{Sample .emacs File}.
2685 @cindex style definition
2686 @c @defvr {List} style definition
2688 @item Structure of a Style Definition List
2689 ([@var{base-style}] [(@var{variable} . @var{value}) @dots{}])
2691 Optional @var{base-style}, if present, must be a string which is the
2692 name of the @dfn{base style} from which this style inherits. At most
2693 one @var{base-style} is allowed in a style definition. If
2694 @var{base-style} is not specified, the style inherits from the table
2695 of factory default values@footnote{This table is stored internally in
2696 the variable c-fallback-style.} instead. All styles eventually
2697 inherit from this internal table. Style loops generate errors. The
2698 list of pre-existing styles can be seen in @ref{Built-in Styles}.
2700 The dotted pairs (@var{variable} . @var{value}) each consist of a
2701 variable and the value it is to be set to when the style is later
2702 activated.@footnote{Note that if the variable has been given a value
2703 by the Customization interface or a @code{setq} at the top level of
2704 your @file{.emacs}, this value will override the one the style system
2705 tries to give it. @xref{Config Basics}.} The variable can be either a
2706 @ccmode{} style variable or an arbitrary Emacs variable. In the
2707 latter case, it is @emph{not} made buffer-local by the @ccmode{} style
2711 Two variables are treated specially in the dotted pair list:
2714 @item c-offsets-alist
2715 The value is in turn a list of dotted pairs of the form
2718 (@r{@var{syntactic-symbol}} . @r{@var{offset}})
2721 as described in @ref{c-offsets-alist}. These are passed to
2722 @code{c-set-offset} so there is no need to set every syntactic symbol
2723 in your style, only those that are different from the inherited style.
2725 @item c-special-indent-hook
2726 The value is added to @code{c-special-indent-hook} using
2727 @code{add-hook}, so any functions already on it are kept. If the value
2728 is a list, each element of the list is added with @code{add-hook}.
2732 Styles are kept in the @code{c-style-alist} variable, but you
2733 should never modify this variable directly. Instead, @ccmode{}
2734 provides the function @code{c-add-style} for this purpose.
2736 @defun c-add-style stylename description &optional set-p
2737 @findex add-style (c-)
2738 Add or update a style called @var{stylename}, a string.
2739 @var{description} is the new style definition in the form described
2740 above. If @var{stylename} already exists in @code{c-style-alist} then
2741 it is replaced by @var{description}. (Note, this replacement is
2742 total. The old style is @emph{not} merged into the new one.)
2743 Otherwise, a new style is added.
2745 If the optional @var{set-p} is non-@code{nil} then the new style is
2746 applied to the current buffer as well. The use of this facility is
2747 deprecated and it might be removed from @ccmode{} in a future release.
2748 You should use @code{c-set-style} instead.
2750 The sample @file{.emacs} file provides a concrete example of how a new
2751 style can be added and automatically set. @xref{Sample .emacs File}.
2754 @defvar c-style-alist
2755 @vindex style-alist (c-)
2756 This is the variable that holds the definitions for the styles. It
2757 should not be changed directly; use @code{c-add-style} instead.
2760 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2761 @node Guessing the Style, File Styles, Adding Styles, Styles
2762 @comment node-name, next, previous, up
2763 @subsection Guessing the Style
2764 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2766 Instead of specifying a style, you can get @ccmode{} to @dfn{guess}
2767 your style by examining an already formatted code buffer. @ccmode{}
2768 then determines the ''most frequent'' offset (@pxref{c-offsets-alist})
2769 for each of the syntactic symbols (@pxref{Indentation Engine Basics})
2770 encountered in the buffer, and the ''most frequent'' value of
2771 c-basic-offset (@pxref{Customizing Indentation}), then merges the
2772 current style with these ''guesses'' to form a new style. This
2773 combined style is known as the @dfn{guessed style}.
2775 To do this, call @code{c-guess} (or one of the other 5 guessing
2776 commands) on your sample buffer. The analysis of your code may take
2779 You can then set the guessed style in any @ccmode{} buffer with
2780 @code{c-guess-install}. You can display the style with
2781 @code{c-guess-view}, and preserve it by copying it into your
2782 @file{.emacs} for future use, preferably after editing it.
2785 @item @kbd{M-x c-guess-no-install}
2786 @itemx @kbd{M-x c-guess-buffer-no-install}
2787 @itemx @kbd{M-x c-guess-region-no-install}
2788 @findex c-guess-no-install
2789 @findex c-guess-buffer-no-install
2790 @findex c-guess-region-no-install
2791 @findex guess-no-install (c-)
2792 @findex guess-buffer-no-install (c-)
2793 @findex guess-region-no-install (c-)
2794 These commands analyze a part of the current buffer and guess the
2797 The part of the buffer examined is either the region
2798 (@code{c-guess-region-no-install}), the entire buffer
2799 (@code{c-guess-buffer-no-install}), or the first
2800 @code{c-guess-region-max} bytes (@code{c-guess-no-install}).
2802 Each of these commands can be given an optional prefix argument. This
2803 instructs @ccmode{} to combine the new guesses with the current
2804 guesses before forming the guessed style.
2808 @item @kbd{M-x c-guess}
2809 @itemx @kbd{M-x c-guess-buffer}
2810 @itemx @kbd{M-x c-guess-region}
2812 @findex c-guess-buffer
2813 @findex c-guess-region
2815 @findex guess-buffer (c-)
2816 @findex guess-region (c-)
2817 These commands analyze a part of the current buffer, guess the style
2818 from it, then install the guessed style on the buffer. The guessed
2819 style is given a name based on the buffer's absolute file name, and
2820 you can then set this style on any @ccmode{} buffer with @kbd{C-c .}.
2822 The part of the buffer examined is either the region
2823 (@code{c-guess-region}), the entire buffer (@code{c-guess-buffer}), or
2824 the first @code{c-guess-region-max} bytes (@code{c-guess}).
2826 Each of these commands can be given an optional prefix argument. This
2827 instructs @ccmode{} to combine the new guesses with the current
2828 guesses before forming the guessed style.
2831 @defopt c-guess-region-max
2832 @vindex guess-region-max (c-)
2833 This variable, default 50000, is the size in bytes of the buffer
2834 portion examined by c-guess and c-guess-no-install. If set to
2835 @code{nil}, the entire buffer is examined.
2838 @defopt c-guess-offset-threshold
2839 @vindex guess-offset-threshold (c-)
2840 This variable, default 10, is the maximum offset, either outwards or
2841 inwards, which will be taken into account by the analysis process.
2842 Any offset bigger than this will be ignored. For no limit, set this
2843 variable to a large number.
2847 @item @kbd{M-x c-guess-install}
2848 @findex c-guess-install
2849 @findex guess-install (c-)
2851 Set the current buffer's style to the guessed style. This prompts you
2852 to enter an optional new style name to give to the guessed style. By
2853 default, this name is based on the buffer's absolute file name. You
2854 can then use this style like any other.
2856 @item @kbd{M-x c-guess-view}
2857 @findex c-guess-view
2858 @findex guess-view (c-)
2859 Display the most recently guessed style in a temporary buffer. This
2860 display is in the form of a @code{c-add-style} form (@pxref{Adding
2861 Styles}) which can be easily copied to your @file{.emacs}. You will
2862 probably want to edit it first.
2864 The display of the guessed style contains these elements:
2867 @item Placeholder Name
2868 You should replace this with a style name of your own.
2870 The style current when the guessing began, from which the guessed
2871 style inherits (@pxref{Config Basics}) the settings which weren't
2873 @item Guessed Offsets
2874 These are the core result of the guessing process. Each of them is
2875 marked by a comment.
2876 @item Inherited Offsets
2877 These are syntactic offsets which have been taken over from the parent
2878 style. To avoid possible future conflicts, you should remove either
2879 these offsets or the parent style name.
2883 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2884 @node File Styles, , Guessing the Style, Styles
2885 @comment node-name, next, previous, up
2886 @subsection File Styles
2887 @cindex styles, file local
2888 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2890 @cindex file local variables
2892 The Emacs manual describes how you can customize certain variables on a
2893 per-file basis by including a @dfn{file local variable} block at the end
2894 of the file (@pxref{File Variables,, Local Variables in Files, @emacsman{},
2897 So far, you've only seen a functional interface for setting styles in
2898 @ccmode{}, and this can't be used here. @ccmode{} fills the gap by
2899 providing two variables for use in a file's local variable list.
2900 Don't use them anywhere else! These allow you to customize the style
2901 on a per-file basis:
2903 @defvar c-file-style
2904 @vindex file-style (c-)
2905 Set this variable to a style name string in the Local Variables list.
2906 From now on, when you visit the file, @ccmode{} will automatically set
2907 the file's style to this one using @code{c-set-style}.
2910 @defvar c-file-offsets
2911 @vindex file-offsets (c-)
2912 Set this variable (in the Local Variables list) to an association list
2913 of the same format as @code{c-offsets-alist}. From now on, when you
2914 visit the file, @ccmode{} will automatically institute these offsets
2915 using @code{c-set-offset}.
2918 Note that file style settings (i.e. @code{c-file-style}) are applied
2919 before file offset settings
2920 (i.e. @code{c-file-offsets})@footnote{Also, if either of these are set
2921 in a file's local variable section, all the style variable values are
2922 made local to that buffer, even if
2923 @code{c-style-variables-are-local-p} is @code{nil}. Since this
2924 variable is virtually always non-@code{nil} anyhow, you're unlikely to
2925 notice this effect.}.
2927 If you set any variable by the file local variables mechanism, that
2928 setting takes priority over all other settings, even those in your
2929 mode hooks (@pxref{CC Hooks}). Any individual setting of a variable
2930 will override one made through @code{c-file-style} or
2931 @code{c-file-offsets}.
2932 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2933 @node Custom Filling and Breaking, Custom Auto-newlines, Config Basics, Top
2934 @comment node-name, next, previous, up
2935 @chapter Customizing Filling and Line Breaking
2936 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2938 Since there's a lot of normal text in comments and string literals,
2939 @ccmode{} provides features to edit these like in text mode. It does
2940 this by hooking in on the different line breaking functions and tuning
2941 relevant variables as necessary.
2943 @vindex c-comment-prefix-regexp
2944 @vindex comment-prefix-regexp (c-)
2945 @cindex comment line prefix
2946 @vindex comment-start
2948 @vindex comment-start-skip
2949 @vindex paragraph-start
2950 @vindex paragraph-separate
2951 @vindex paragraph-ignore-fill-prefix
2952 @vindex adaptive-fill-mode
2953 @vindex adaptive-fill-regexp
2954 @vindex adaptive-fill-first-line-regexp
2955 To make Emacs recognize comments and treat text in them as normal
2956 paragraphs, @ccmode{} makes several standard
2957 variables@footnote{@code{comment-start}, @code{comment-end},
2958 @code{comment-start-skip}, @code{paragraph-start},
2959 @code{paragraph-separate}, @code{paragraph-ignore-fill-prefix},
2960 @code{adaptive-fill-mode}, @code{adaptive-fill-regexp}, and
2961 @code{adaptive-fill-first-line-regexp}.} buffer-local and modifies them
2962 according to the language syntax and the comment line prefix.
2964 @defopt c-comment-prefix-regexp
2965 @vindex comment-prefix-regexp (c-)
2966 This style variable contains the regexp used to recognize the
2967 @dfn{comment line prefix}, which is the line decoration that starts
2968 every line in a comment. The variable is either the comment line
2969 prefix itself, or (more usually) an association list with different
2970 values for different languages. The symbol for the major mode is
2971 looked up in the alist to get the regexp for the language, and if it
2972 isn't found then the special symbol @samp{other} is looked up instead.
2974 When a comment line gets divided by @kbd{M-j} or the like, @ccmode{}
2975 inserts the comment line prefix from a neighboring line at the start
2976 of the new line. The default value of c-comment-prefix-regexp is
2977 @samp{//+\\|\\**}, which matches C++ style line comments like
2984 with two or more slashes in front of them, and the second and
2985 subsequent lines of C style block comments like
2996 with zero or more stars at the beginning of every line. If you change
2997 this variable, please make sure it still matches the comment starter
2998 (i.e. @code{//}) of line comments @emph{and} the line prefix inside
3001 @findex c-setup-paragraph-variables
3002 @findex setup-paragraph-variables (c-)
3003 Also note that since @ccmode{} uses the value of
3004 @code{c-comment-prefix-regexp} to set up several other variables at
3005 mode initialization, there won't be any effect if you just change it
3006 inside a @ccmode{} buffer. You need to call the command
3007 @code{c-setup-paragraph-variables} too, to update those other
3008 variables. That's also the case if you modify
3009 @code{c-comment-prefix-regexp} in a mode hook, since @ccmode{} will
3010 already have set up these variables before calling the hook.
3013 In comments, @ccmode{} uses @code{c-comment-prefix-regexp} to adapt
3014 the line prefix from the other lines in the comment.
3016 @vindex adaptive-fill-mode
3017 @cindex Adaptive Fill mode
3018 @ccmode{} uses adaptive fill mode (@pxref{Adaptive Fill,,, emacs, GNU
3019 Emacs Manual}) to make Emacs correctly keep the line prefix when
3020 filling paragraphs. That also makes Emacs preserve the text
3021 indentation @emph{inside} the comment line prefix. E.g. in the
3022 following comment, both paragraphs will be filled with the left
3023 margins of the texts kept intact:
3027 /* Make a balanced b-tree of the nodes in the incoming
3028 * stream. But, to quote the famous words of Donald E.
3031 * Beware of bugs in the above code; I have only
3032 * proved it correct, not tried it.
3037 @findex c-setup-filladapt
3038 @findex setup-filladapt (c-)
3039 @findex filladapt-mode
3040 @vindex filladapt-mode
3041 @cindex Filladapt mode
3042 It's also possible to use other adaptive filling packages, notably Kyle
3043 E. Jones' Filladapt package@footnote{It's available from
3044 @uref{http://www.wonderworks.com/}. As of version 2.12, it does however
3045 lack a feature that makes it work suboptimally when
3046 @code{c-comment-prefix-regexp} matches the empty string (which it does
3047 by default). A patch for that is available from
3048 @uref{http://cc-mode.sourceforge.net/,, the CC Mode web site}.},
3049 @c 2005/11/22: The above is still believed to be the case.
3050 which handles things like bulleted lists nicely. There's a convenience
3051 function @code{c-setup-filladapt} that tunes the relevant variables in
3052 Filladapt for use in @ccmode{}. Call it from a mode hook, e.g. with
3053 something like this in your @file{.emacs}:
3056 (defun my-c-mode-common-hook ()
3059 (add-hook 'c-mode-common-hook 'my-c-mode-common-hook)
3062 @defopt c-block-comment-prefix
3063 @vindex block-comment-prefix (c-)
3064 @vindex c-comment-continuation-stars
3065 @vindex comment-continuation-stars (c-)
3066 Normally the comment line prefix inserted for a new line inside a
3067 comment is deduced from other lines in it. However there's one
3068 situation when there's no hint about what the prefix should look like,
3069 namely when a block comment is broken for the first time. This style
3070 variable@footnote{In versions before 5.26, this variable was called
3071 @code{c-comment-continuation-stars}. As a compatibility measure,
3072 @ccmode{} still uses the value on that variable if it's set.} is used
3073 then as the comment prefix. It defaults to @samp{*
3074 }@footnote{Actually, this default setting of
3075 @code{c-block-comment-prefix} typically gets overridden by the default
3076 style @code{gnu}, which sets it to blank. You can see the line
3077 splitting effect described here by setting a different style,
3078 e.g. @code{k&r} @xref{Choosing a Style}.}, which makes a comment
3081 /* Got O(n^2) here, which is a Bad Thing. */
3089 /* Got O(n^2) here, which
3090 * is a Bad Thing. */
3094 Note that it won't work to adjust the indentation by putting leading
3095 spaces in @code{c-block-comment-prefix}, since @ccmode{} still uses the
3096 normal indentation engine to indent the line. Thus, the right way to
3097 fix the indentation is by customizing the @code{c} syntactic symbol. It
3098 defaults to @code{c-lineup-C-comments}, which handles the indentation of
3099 most common comment styles, see @ref{Line-Up Functions}.
3102 @defopt c-ignore-auto-fill
3103 @vindex ignore-auto-fill (c-)
3104 When auto fill mode is enabled, @ccmode{} can selectively ignore it
3105 depending on the context the line break would occur in, e.g. to never
3106 break a line automatically inside a string literal. This variable
3107 takes a list of symbols for the different contexts where auto-filling
3112 Inside a string or character literal.
3114 Inside a C style block comment.
3116 Inside a C++ style line comment.
3118 Inside a preprocessor directive.
3120 Anywhere else, i.e. in normal code.
3123 By default, @code{c-ignore-auto-fill} is set to @code{(string cpp
3124 code)}, which means that when auto-fill mode is activated,
3125 auto-filling only occurs in comments. In literals, it's often
3126 desirable to have explicit control over newlines. In preprocessor
3127 directives, the necessary @samp{\} escape character before the newline
3128 is not automatically inserted, so an automatic line break would
3129 produce invalid code. In normal code, line breaks are normally
3130 dictated by some logical structure in the code rather than the last
3131 whitespace character, so automatic line breaks there will produce poor
3132 results in the current implementation.
3135 @vindex comment-multi-line
3136 If inside a comment and @code{comment-multi-line} (@pxref{Auto Fill,,,
3137 @emacsman{}, @emacsmantitle{}} is non-@code{nil}, the indentation and
3138 line prefix are preserved. If inside a comment and
3139 @code{comment-multi-line} is @code{nil}, a new comment of the same
3140 type is started on the next line and indented as appropriate for
3143 Note that @ccmode{} sets @code{comment-multi-line} to @code{t} at
3144 startup. The reason is that @kbd{M-j} could otherwise produce sequences
3145 of single line block comments for texts that should logically be treated
3146 as one comment, and the rest of the paragraph handling code
3147 (e.g. @kbd{M-q} and @kbd{M-a}) can't cope with that, which would lead to
3148 inconsistent behavior.
3150 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3151 @node Custom Auto-newlines, Clean-ups, Custom Filling and Breaking, Top
3152 @comment node-name, next, previous, up
3153 @chapter Customizing Auto-newlines
3154 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3156 @ccmode{} determines whether to insert auto-newlines in two basically
3157 different ways, depending on the character just typed:
3160 @item Braces and Colons
3161 @ccmode{} first determines the syntactic context of the brace or colon
3162 (@pxref{Syntactic Symbols}), then looks for a corresponding element in
3163 an alist. This element specifies where to put newlines - this is any
3164 combination of before and after the brace or colon. If no alist
3165 element is found, newlines are inserted both before and after a brace,
3166 but none are inserted around a colon. See @ref{Hanging Braces} and
3167 @ref{Hanging Colons}.
3169 @item Semicolons and Commas
3170 The variable @code{c-hanging-semi&comma-criteria} contains a list of
3171 functions which determine whether to insert a newline after a newly
3172 typed semicolon or comma. @xref{Hanging Semicolons and Commas}.
3175 The names of these configuration variables contain @samp{hanging}
3176 because they let you @dfn{hang} the pertinent characters. A character
3177 which introduces a C construct is said to @dfn{hang on the right} when
3178 it appears at the end of a line after other code, being separated by a
3179 line break from the construct it introduces, like the opening brace in:
3191 A character @dfn{hangs on the left} when it appears at the start of
3192 the line after the construct it closes off, like the above closing
3195 The next chapter, ``Clean-ups'', describes how to configure @ccmode{}
3196 to remove these automatically added newlines in certain specific
3197 circumstances. @xref{Clean-ups}.
3202 * Hanging Semicolons and Commas::
3206 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3207 @node Hanging Braces, Hanging Colons, Custom Auto-newlines, Custom Auto-newlines
3208 @comment node-name, next, previous, up
3209 @section Hanging Braces
3210 @cindex hanging braces
3211 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3213 To specify which kinds of braces you want auto-newlines put around,
3214 you set the style variable @code{c-hanging-braces-alist}. Its
3215 structure and semantics are described in this section. Details of how
3216 to set it up, and its relationship to CC Mode's style system are given
3217 in @ref{Style Variables}.
3219 Say you wanted an auto-newline after (but not before) the following
3227 First you need to find the @dfn{syntactic context} of the brace---type
3228 a @key{RET} before the brace to get it on a line of its
3229 own@footnote{Also insert a @samp{\} at the end of the previous line if
3230 you're in AWK Mode.}, then type @kbd{C-c C-s}. That will tell you
3234 ((substatement-open 1061))
3238 So here you need to put the entry @code{(substatement-open . (after))}
3239 into @code{c-hanging-braces-alist}.
3241 If you don't want any auto-newlines for a particular syntactic symbol,
3242 put this into @code{c-hanging-braces-alist}:
3248 If some brace syntactic symbol is not in @code{c-hanging-brace-alist},
3249 its entry is taken by default as @code{(before after)}---insert a
3250 newline both before and after the brace. In place of a
3251 ``before/after'' list you can specify a function in this alist---this
3252 is useful when the auto newlines depend on the code around the brace.
3254 @defopt c-hanging-braces-alist
3255 @vindex hanging-braces-alist (c-)
3257 This variable is an association list which maps syntactic symbols to
3258 lists of places to insert a newline. @xref{Association
3259 Lists,,,@lispref{}, @lispreftitle{}}. The key of each element is the
3260 syntactic symbol, the associated value is either @code{nil}, a list,
3264 @item The Key - the syntactic symbol
3265 The syntactic symbols that are useful as keys in this list are
3266 @code{brace-list-intro}, @code{statement-cont},
3267 @code{inexpr-class-open}, @code{inexpr-class-close}, and all the
3268 @code{*-open} and @code{*-close} symbols. @xref{Syntactic Symbols},
3269 for a more detailed description of these syntactic symbols, except for
3270 @code{inexpr-class-open} and @code{inexpr-class-close}, which aren't
3271 actual syntactic symbols. Elements with any other value as a key get
3274 The braces of anonymous inner classes in Java are given the special
3275 symbols @code{inexpr-class-open} and @code{inexpr-class-close}, so that
3276 they can be distinguished from the braces of normal classes@footnote{The
3277 braces of anonymous classes produce a combination of
3278 @code{inexpr-class}, and @code{class-open} or @code{class-close} in
3279 normal indentation analysis.}.
3281 Note that the aggregate constructs in Pike mode, @samp{(@{}, @samp{@})},
3282 @samp{([}, @samp{])}, and @samp{(<}, @samp{>)}, do not count as brace
3283 lists in this regard, even though they do for normal indentation
3284 purposes. It's currently not possible to set automatic newlines on
3287 @item The associated value - the ``ACTION'' list or function
3288 The value associated with each syntactic symbol in this association
3289 list is called an @var{action}, which can be either a list or a
3290 function which returns a list. @xref{Custom Braces}, for how to use
3291 a function as a brace hanging @var{action}.
3293 The list @var{action} (or the list returned by @var{action} when it's
3294 a function) contains some combination of the symbols @code{before} and
3295 @code{after}, directing @ccmode{} where to put newlines in
3296 relationship to the brace being inserted. Thus, if the list contains
3297 only the symbol @code{after}, then the brace hangs on the right side
3301 // here, open braces always `hang'
3302 void spam( int i ) @{
3309 When the list contains both @code{after} and @code{before}, the braces
3310 will appear on a line by themselves, as shown by the close braces in
3311 the above example. The list can also be empty, in which case newlines
3312 are added neither before nor after the brace.
3315 If a syntactic symbol is missing entirely from
3316 @code{c-hanging-braces-alist}, it's treated in the same way as an
3317 @var{action} with a list containing @code{before} and @code{after}, so
3318 that braces by default end up on their own line.
3320 For example, the default value of @code{c-hanging-braces-alist} is:
3326 (substatement-open after)
3327 (block-close . c-snug-do-while)
3328 (extern-lang-open after)
3329 (namespace-open after)
3331 (composition-open after)
3332 (inexpr-class-open after)
3333 (inexpr-class-close before))
3336 @noindent which says that @code{brace-list-open},
3337 @code{brace-entry-open} and @code{statement-cont}@footnote{Brace lists
3338 inside statements, such as initializers for static array variables
3339 inside functions in C, are recognized as @code{statement-cont}. All
3340 normal substatement blocks are recognized with other symbols.} braces
3341 should both hang on the right side and allow subsequent text to follow
3342 on the same line as the brace. Also, @code{substatement-open},
3343 @code{extern-lang-open}, and @code{inexpr-class-open} braces should hang
3344 on the right side, but subsequent text should follow on the next line.
3345 The opposite holds for @code{inexpr-class-close} braces; they won't
3346 hang, but the following text continues on the same line. Here, in the
3347 @code{block-close} entry, you also see an example of using a function as
3348 an @var{action}. In all other cases, braces are put on a line by
3356 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3357 @node Custom Braces, , Hanging Braces, Hanging Braces
3358 @comment node-name, next, previous, up
3359 @subsection Custom Brace Hanging
3360 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3362 @vindex c-hanging-braces-alist
3363 @vindex hanging-braces-alist (c-)
3364 @cindex action functions
3365 Syntactic symbols aren't the only place where you can customize
3366 @ccmode{} with the lisp equivalent of callback functions. Remember
3367 that @var{action}s are usually a list containing some combination of
3368 the symbols @code{before} and @code{after} (@pxref{Hanging Braces}).
3369 For more flexibility, you can instead specify brace ``hanginess'' by
3370 giving a syntactic symbol an @dfn{action function} in
3371 @code{c-hanging-braces-alist}; this function determines the
3372 ``hanginess'' of a brace, usually by looking at the code near it.
3374 @cindex customization, brace hanging
3375 An action function is called with two arguments: the syntactic symbol
3376 for the brace (e.g. @code{substatement-open}), and the buffer position
3377 where the brace has been inserted. Point is undefined on entry to an
3378 action function, but the function must preserve it (e.g. by using
3379 @code{save-excursion}). The return value should be a list containing
3380 some combination of @code{before} and @code{after}, including neither
3381 of them (i.e. @code{nil}).
3383 @defvar c-syntactic-context
3384 @vindex syntactic-context (c-)
3385 During the call to the indentation or brace hanging @var{action}
3386 function, this variable is bound to the full syntactic analysis list.
3387 This might be, for example, @samp{((block-close 73))}. Don't ever
3388 give @code{c-syntactic-context} a value yourself---this would disrupt
3389 the proper functioning of @ccmode{}.
3391 This variable is also bound in three other circumstances:
3392 (i)@w{ }when calling a c-hanging-semi&comma-criteria function
3393 (@pxref{Hanging Semicolons and Commas}); (ii)@w{ }when calling a
3394 line-up function (@pxref{Custom Line-Up}); (iii)@w{ }when calling a
3395 c-special-indent-hook function (@pxref{Other Indentation}).
3398 As an example, @ccmode{} itself uses this feature to dynamically
3399 determine the hanginess of braces which close ``do-while''
3403 void do_list( int count, char** atleast_one_string )
3407 handle_string( atleast_one_string[i] );
3409 @} while( i < count );
3413 @ccmode{} assigns the @code{block-close} syntactic symbol to the
3414 brace that closes the @code{do} construct, and normally we'd like the
3415 line that follows a @code{block-close} brace to begin on a separate
3416 line. However, with ``do-while'' constructs, we want the
3417 @code{while} clause to follow the closing brace. To do this, we
3418 associate the @code{block-close} symbol with the @var{action} function
3419 @code{c-snug-do-while}:
3422 (defun c-snug-do-while (syntax pos)
3423 "Dynamically calculate brace hanginess for do-while statements."
3426 (if (and (eq syntax 'block-close)
3427 (setq langelem (assq 'block-close c-syntactic-context))
3428 (progn (goto-char (cdr langelem))
3429 (if (= (following-char) ?@{)
3431 (looking-at "\\<do\\>[^_]")))
3436 @findex c-snug-do-while
3437 @findex snug-do-while (c-)
3438 This function simply looks to see if the brace closes a ``do-while''
3439 clause and if so, returns the list @samp{(before)} indicating
3440 that a newline should be inserted before the brace, but not after it.
3441 In all other cases, it returns the list @samp{(before after)} so
3442 that the brace appears on a line by itself.
3444 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3445 @node Hanging Colons, Hanging Semicolons and Commas, Hanging Braces, Custom Auto-newlines
3446 @comment node-name, next, previous, up
3447 @section Hanging Colons
3448 @cindex hanging colons
3449 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3451 @cindex customization, colon hanging
3452 @vindex c-hanging-colons-alist
3453 @vindex hanging-colons-alist (c-)
3455 Using a mechanism similar to brace hanging (@pxref{Hanging Braces}),
3456 colons can also be made to hang using the style variable
3457 @code{c-hanging-colons-alist} - When a colon is typed, @ccmode
3458 determines its syntactic context, looks this up in the alist
3459 @code{c-changing-colons-alist} and inserts up to two newlines
3460 accordingly. Here, however, If @ccmode fails to find an entry for a
3461 syntactic symbol in the alist, no newlines are inserted around the
3464 @defopt c-hanging-colons-alist
3465 @vindex hanging-colons-alist (c-)
3468 @item The Key - the syntactic symbol
3469 The syntactic symbols appropriate as keys in this association list
3470 are: @code{case-label}, @code{label}, @code{access-label},
3471 @code{member-init-intro}, and @code{inher-intro}. @xref{Syntactic
3472 Symbols}. Elements with any other value as a key get ignored.
3474 @item The associate value - the ``ACTION'' list
3475 The @var{action} here is simply a list containing a combination of the
3476 symbols @code{before} and @code{after}. Unlike in
3477 @code{c-hanging-braces-alist}, functions as @var{actions} are not
3478 supported - there doesn't seem to be any need for them.
3482 In C++, double-colons are used as a scope operator but because these
3483 colons always appear right next to each other, newlines before and after
3484 them are controlled by a different mechanism, called @dfn{clean-ups} in
3485 @ccmode{}. @xref{Clean-ups}, for details.
3487 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3488 @node Hanging Semicolons and Commas, , Hanging Colons, Custom Auto-newlines
3489 @comment node-name, next, previous, up
3490 @section Hanging Semicolons and Commas
3491 @cindex hanging semicolons
3492 @cindex hanging commas
3493 @cindex customization, semicolon newlines
3494 @cindex customization, comma newlines
3495 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3497 @defopt c-hanging-semi&comma-criteria
3498 @vindex hanging-semi&comma-criteria (c-)
3499 This style variable takes a list of functions; these get called when
3500 you type a semicolon or comma. The functions are called in order
3501 without arguments. When these functions are entered, point is just
3502 after the newly inserted @samp{;} or @samp{,} and they must preserve
3503 point (e.g., by using @code{save-excursion}). During the call, the
3504 variable @code{c-syntactic-context} is bound to the syntactic context
3505 of the current line@footnote{This was first introduced in @ccmode{}
3506 5.31.} @pxref{Custom Braces}. These functions don't insert newlines
3507 themselves, rather they direct @ccmode{} whether or not to do so.
3508 They should return one of the following values:
3512 A newline is to be inserted after the @samp{;} or @samp{,}, and no
3513 more functions from the list are to be called.
3515 No more functions from the list are to be called, and no newline is to
3518 No determination has been made, and the next function in the list is
3522 Note that auto-newlines are never inserted @emph{before} a semicolon
3523 or comma. If every function in the list is called without a
3524 determination being made, then no newline is added.
3526 In AWK mode, this variable is set by default to @code{nil}. In the
3527 other modes, the default value is a list containing a single function,
3528 @code{c-semi&comma-inside-parenlist}. This inserts newlines after all
3529 semicolons, apart from those separating @code{for}-clause statements.
3532 @defun c-semi&comma-no-newlines-before-nonblanks
3533 @findex semi&comma-no-newlines-before-nonblanks (c-)
3534 This is an example of a criteria function, provided by @ccmode{}. It
3535 prevents newlines from being inserted after semicolons when there is a
3536 non-blank following line. Otherwise, it makes no determination. To
3537 use, add this function to the front of the
3538 @code{c-hanging-semi&comma-criteria} list.
3541 (defun c-semi&comma-no-newlines-before-nonblanks ()
3543 (if (and (eq last-command-char ?\;)
3544 (zerop (forward-line 1))
3545 (not (looking-at "^[ \t]*$")))
3551 @defun c-semi&comma-inside-parenlist
3552 @findex semi&comma-inside-parenlist (c-)
3553 @defunx c-semi&comma-no-newlines-for-oneline-inliners
3554 @findex semi&comma-no-newlines-for-oneline-inliners (c-)
3555 The function @code{c-semi&comma-inside-parenlist} is what prevents
3556 newlines from being inserted inside the parenthesis list of @code{for}
3557 statements. In addition to
3558 @code{c-semi&comma-no-newlines-before-nonblanks} described above,
3559 @ccmode{} also comes with the criteria function
3560 @code{c-semi&comma-no-newlines-for-oneline-inliners}, which suppresses
3561 newlines after semicolons inside one-line inline method definitions
3562 (e.g. in C++ or Java).
3566 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3567 @node Clean-ups, Indentation Engine Basics, Custom Auto-newlines, Top
3568 @comment node-name, next, previous, up
3571 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3573 @dfn{Clean-ups} are mechanisms which remove (or exceptionally, add)
3574 whitespace in specific circumstances and are complementary to colon
3575 and brace hanging. You enable a clean-up by adding its symbol into
3576 @code{c-cleanup-list}, e.g. like this:
3579 (add-to-list 'c-cleanup-list 'space-before-funcall)
3582 On the surface, it would seem that clean-ups overlap the functionality
3583 provided by the @code{c-hanging-*-alist} variables. Clean-ups,
3584 however, are used to adjust code ``after-the-fact'', i.e. to adjust
3585 the whitespace in constructs later than when they were typed.
3587 Most of the clean-ups remove automatically inserted newlines, and are
3588 only active when auto-newline minor mode is turned on. Others will
3589 work all the time. Note that clean-ups are only performed when there
3590 is nothing but whitespace appearing between the individual components
3591 of the construct, and (apart from @code{comment-close-slash}) when the
3592 construct does not occur within a literal (@pxref{Auto-newlines}).
3594 @defopt c-cleanup-list
3595 @vindex cleanup-list (c-)
3598 You configure @ccmode{}'s clean-ups by setting the style variable
3599 @code{c-cleanup-list}, which is a list of clean-up symbols. By
3600 default, @ccmode{} cleans up only the @code{scope-operator} construct,
3601 which is necessary for proper C++ support.
3604 These are the clean-ups that are only active when electric and
3605 auto-newline minor modes are enabled:
3607 @c TBD: Would like to use some sort of @deffoo here; @table indents a
3608 @c bit too much in dvi output.
3610 @item brace-else-brace
3611 Clean up @samp{@} else @{} constructs by placing the entire construct on
3612 a single line. Clean up occurs when the open brace after the
3613 @samp{else} is typed. So for example, this:
3628 appears like this after the last open brace is typed:
3640 @item brace-elseif-brace
3641 Similar to the @code{brace-else-brace} clean-up, but this cleans up
3642 @samp{@} else if (...) @{} constructs. For example:
3657 appears like this after the last open parenthesis is typed:
3670 and like this after the last open brace is typed:
3678 @} else if( i==3 ) @{
3682 @item brace-catch-brace
3683 Analogous to @code{brace-elseif-brace}, but cleans up @samp{@} catch
3684 (...) @{} in C++ and Java mode.
3686 @item empty-defun-braces
3687 Clean up braces following a top-level function or class definition that
3688 contains no body. Clean up occurs when the closing brace is typed.
3700 is transformed into this when the close brace is typed:
3709 @item defun-close-semi
3710 Clean up the terminating semicolon on top-level function or class
3711 definitions when they follow a close brace. Clean up occurs when the
3712 semicolon is typed. So for example, the following:
3725 is transformed into this when the semicolon is typed:
3736 @item list-close-comma
3737 Clean up commas following braces in array and aggregate initializers.
3738 Clean up occurs when the comma is typed. The space before the comma
3739 is zapped just like the space before the semicolon in
3740 @code{defun-close-semi}.
3742 @item scope-operator
3743 Clean up double colons which might designate a C++ scope operator split
3744 across multiple lines@footnote{Certain C++ constructs introduce
3745 ambiguous situations, so @code{scope-operator} clean-ups might not
3746 always be correct. This usually only occurs when scoped identifiers
3747 appear in switch label tags.}. Clean up occurs when the second colon is
3748 typed. You will always want @code{scope-operator} in the
3749 @code{c-cleanup-list} when you are editing C++ code.
3751 @item one-liner-defun
3752 Clean up a single line of code enclosed by defun braces by removing
3753 the whitespace before and after the code. The clean-up happens when
3754 the closing brace is typed. If the variable
3755 @code{c-max-one-liner-length} is set, the cleanup is only done if the
3756 resulting line would be no longer than the value of that variable.
3758 For example, consider this AWK code:
3763 FS = "\t" # use <TAB> as a field separator
3769 It gets compacted to the following when the closing brace is typed:
3773 BEGIN @{FS = "\t"@} # use <TAB> as a field separator
3777 @defopt c-max-one-liner-length
3778 @vindex max-one-liner-length (c-)
3779 The maximum length of the resulting line for which the clean-up
3780 @code{one-liner-defun} will be triggered. This length is that of the entire
3781 line, including any leading whitespace and any trailing comment. Its
3782 default value is 80. If the value is zero or @code{nil}, no limit
3787 The following clean-ups are always active when they occur on
3788 @code{c-cleanup-list}, regardless of whether Electric minor mode or
3789 Auto-newline minor mode are enabled:
3792 @item space-before-funcall
3793 Insert a space between the function name and the opening parenthesis
3794 of a function call. This produces function calls in the style
3795 mandated by the GNU coding standards, e.g. @samp{signal@w{ }(SIGINT,
3796 SIG_IGN)} and @samp{abort@w{ }()}. Clean up occurs when the opening
3797 parenthesis is typed. This clean-up should never be active in AWK
3798 Mode, since such a space is syntactically invalid for user defined
3801 @item compact-empty-funcall
3802 Clean up any space between the function name and the opening parenthesis
3803 of a function call that has no arguments. This is typically used
3804 together with @code{space-before-funcall} if you prefer the GNU function
3805 call style for functions with arguments but think it looks ugly when
3806 it's only an empty parenthesis pair. I.e. you will get @samp{signal
3807 (SIGINT, SIG_IGN)}, but @samp{abort()}. Clean up occurs when the
3808 closing parenthesis is typed.
3810 @item comment-close-slash
3811 When inside a block comment, terminate the comment when you type a slash
3812 at the beginning of a line (i.e. immediately after the comment prefix).
3813 This clean-up removes whitespace preceding the slash and if needed,
3814 inserts a star to complete the token @samp{*/}. Type @kbd{C-q /} in this
3815 situation if you just want a literal @samp{/} inserted.
3819 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3820 @node Indentation Engine Basics, Customizing Indentation, Clean-ups, Top
3821 @comment node-name, next, previous, up
3822 @chapter Indentation Engine Basics
3823 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3825 This chapter will briefly cover how @ccmode{} indents lines of code.
3826 It is helpful to understand the indentation model being used so that
3827 you will know how to customize @ccmode{} for your personal coding
3828 style. All the details are in @ref{Customizing Indentation}.
3830 @ccmode{} has an indentation engine that provides a flexible and
3831 general mechanism for customizing indentation. When @ccmode{} indents
3832 a line of code, it separates its calculations into two steps:
3836 @cindex syntactic symbol
3837 @cindex anchor position
3838 It analyzes the line to determine its @dfn{syntactic symbol(s)} (the
3839 kind of language construct it's looking at) and its @dfn{anchor
3840 position} (the position earlier in the file that @ccmode{} will indent
3841 the line relative to). The anchor position might be the location of
3842 an opening brace in the previous line, for example. @xref{Syntactic
3846 @cindex indentation offset specifications
3847 It looks up the syntactic symbol(s) in the configuration to get the
3848 corresponding @dfn{offset(s)}. The symbol @code{+}, which means
3849 ``indent this line one more level'' is a typical offset. @ccmode{}
3850 then applies these offset(s) to the anchor position, giving the
3851 indentation for the line. The different sorts of offsets are
3852 described in @ref{c-offsets-alist}.
3855 In exceptional circumstances, the syntax directed indentation
3856 described here may be a nuisance rather than a help. You can disable
3857 it by setting @code{c-syntactic-indentation} to @code{nil}. (To set
3858 the variable interactively, @ref{Minor Modes}).
3860 @defopt c-syntactic-indentation
3861 @vindex syntactic-indentation (c-)
3862 When this is non-@code{nil} (which it is by default), the indentation
3863 of code is done according to its syntactic structure. When it's
3864 @code{nil}, every line is just indented to the same level as the
3865 previous one, and @kbd{TAB} (@code{c-indent-command}) adjusts the
3866 indentation in steps of @code{c-basic-offset}. The current style
3867 (@pxref{Config Basics}) then has no effect on indentation, nor do any
3868 of the variables associated with indentation, not even
3869 @code{c-special-indent-hook}.
3873 * Syntactic Analysis::
3874 * Syntactic Symbols::
3875 * Indentation Calculation::
3879 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3880 @node Syntactic Analysis, Syntactic Symbols, Indentation Engine Basics, Indentation Engine Basics
3881 @comment node-name, next, previous, up
3882 @section Syntactic Analysis
3883 @cindex syntactic analysis
3884 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3886 @cindex syntactic element
3887 @cindex syntactic context
3888 The first thing @ccmode{} does when indenting a line of code, is to
3889 analyze the line, determining the @dfn{syntactic context} of the
3890 (first) construct on that line. It's a list of @dfn{syntactic
3891 elements}, where each syntactic element in turn is a list@footnote{In
3892 @ccmode 5.28 and earlier, a syntactic element was a dotted pair; the
3893 cons was the syntactic symbol and the cdr was the anchor position.
3894 For compatibility's sake, the parameter passed to a line-up function
3895 still has this dotted pair form (@pxref{Custom Line-Up}).} Here is a
3896 brief and typical example:
3899 ((defun-block-intro 1959))
3902 @cindex syntactic symbol
3904 The first thing inside each syntactic element is always a
3905 @dfn{syntactic symbol}. It describes the kind of construct that was
3906 recognized, e.g. @code{statement}, @code{substatement},
3907 @code{class-open}, @code{class-close}, etc. @xref{Syntactic Symbols},
3908 for a complete list of currently recognized syntactic symbols and
3909 their semantics. The remaining entries are various data associated
3910 with the recognized construct - there might be zero or more.
3912 @cindex anchor position
3913 Conceptually, a line of code is always indented relative to some
3914 position higher up in the buffer (typically the indentation of the
3915 previous line). That position is the @dfn{anchor position} in the
3916 syntactic element. If there is an entry after the syntactic symbol in
3917 the syntactic element list then it's either nil or that anchor position.
3919 Here is an example. Suppose we had the following code as the only thing
3920 in a C++ buffer @footnote{The line numbers in this and future examples
3921 don't actually appear in the buffer, of course!}:
3924 1: void swap( int& a, int& b )
3933 We can use @kbd{C-c C-s} (@code{c-show-syntactic-information}) to
3934 report what the syntactic analysis is for the current line:
3937 @item @kbd{C-c C-s} (@code{c-show-syntactic-information})
3939 @findex c-show-syntactic-information
3940 @findex show-syntactic-information (c-)
3941 This command calculates the syntactic analysis of the current line and
3942 displays it in the minibuffer. The command also highlights the anchor
3946 Running this command on line 4 of this example, we'd see in the echo
3947 area@footnote{With a universal argument (i.e. @kbd{C-u C-c C-s}) the
3948 analysis is inserted into the buffer as a comment on the current
3956 and the @samp{i} of @code{int} on line 3 would be highlighted. This
3957 tells us that the line is a statement and it is indented relative to
3958 buffer position 35, the highlighted position. If you were to move
3959 point to line 3 and hit @kbd{C-c C-s}, you would see:
3962 ((defun-block-intro 29))
3966 This indicates that the @samp{int} line is the first statement in a top
3967 level function block, and is indented relative to buffer position 29,
3968 which is the brace just after the function header.
3970 Here's another example:
3973 1: int add( int val, int incr, int doit )
3977 5: return( val + incr );
3984 Hitting @kbd{C-c C-s} on line 4 gives us:
3987 ((substatement-open 46))
3990 @cindex substatement
3991 @cindex substatement block
3993 which tells us that this is a brace that @emph{opens} a substatement
3994 block. @footnote{A @dfn{substatement} is the line after a
3995 conditional statement, such as @code{if}, @code{else}, @code{while},
3996 @code{do}, @code{switch}, etc. A @dfn{substatement
3997 block} is a brace block following one of these conditional statements.}
3999 @cindex comment-only line
4000 Syntactic contexts can contain more than one element, and syntactic
4001 elements need not have anchor positions. The most common example of
4002 this is a @dfn{comment-only line}:
4005 1: void draw_list( List<Drawables>& drawables )
4007 3: // call the virtual draw() method on each element in list
4008 4: for( int i=0; i < drawables.count(), ++i )
4010 6: drawables[i].draw();
4016 Hitting @kbd{C-c C-s} on line 3 of this example gives:
4019 ((comment-intro) (defun-block-intro 46))
4023 and you can see that the syntactic context contains two syntactic
4024 elements. Notice that the first element, @samp{(comment-intro)}, has no
4028 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4029 @node Syntactic Symbols, Indentation Calculation, Syntactic Analysis, Indentation Engine Basics
4030 @comment node-name, next, previous, up
4031 @section Syntactic Symbols
4032 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4034 @cindex syntactic symbols, brief list
4035 @vindex c-offsets-alist
4036 @vindex offsets-alist (c-)
4037 This section is a complete list of the syntactic symbols which appear
4038 in the @code{c-offsets-alist} style variable, along with brief
4039 descriptions. The previous section (@pxref{Syntactic Analysis})
4040 states what syntactic symbols are and how the indentation engine uses
4043 More detailed descriptions of these symbols, together with snippets of
4044 source code to which they apply, appear in the examples in the
4045 subsections below. Note that, in the interests of brevity, the anchor
4046 position associated with most syntactic symbols is @emph{not}
4047 specified. In cases of doubt, type @kbd{C-c C-s} on a pertinent
4048 line---this highlights the anchor position.
4050 @ssindex -open symbols
4051 @ssindex -close symbols
4052 @ssindex -block-intro symbols
4053 The syntactic symbols which indicate brace constructs follow a general
4054 naming convention. When a line begins with an open or close brace,
4055 its syntactic symbol will contain the suffix @code{-open} or
4056 @code{-close} respectively. The first line within the brace block
4057 construct will contain the suffix @code{-block-intro}.
4059 @ssindex -intro symbols
4060 @ssindex -cont symbols
4061 In constructs which can span several lines, a distinction is usually
4062 made between the first line that introduces the construct and the
4063 lines that continue it. The syntactic symbols that indicate these
4064 lines will contain the suffixes @code{-intro} or @code{-cont}
4067 The best way to understand how all this works is by looking at some
4068 examples. Remember that you can see the syntax of any source code
4069 line by using @kbd{C-c C-s}.
4073 Inside a multiline string. @ref{Literal Symbols}.
4075 Inside a multiline C style block comment. @ref{Literal Symbols}.
4077 Brace that opens a top-level function definition. @ref{Function
4080 Brace that closes a top-level function definition. @ref{Function
4082 @item defun-block-intro
4083 The first line in a top-level defun. @ref{Function Symbols}.
4085 Brace that opens a class definition. @ref{Class Symbols}.
4087 Brace that closes a class definition. @ref{Class Symbols}.
4089 Brace that opens an in-class inline method. @ref{Class Symbols}.
4091 Brace that closes an in-class inline method. @ref{Class Symbols}.
4092 @item func-decl-cont
4093 The region between a function definition's argument list and the
4094 function opening brace (excluding K&R argument declarations). In C,
4095 you cannot put anything but whitespace and comments in this region,
4096 however in C++ and Java, @code{throws} declarations and other things
4097 can appear here. @ref{Literal Symbols}. @c @emph{FIXME!!! Can it not
4098 @c go somewhere better?}
4099 @item knr-argdecl-intro
4100 First line of a K&R C argument declaration. @ref{K&R Symbols}.
4102 Subsequent lines in a K&R C argument declaration. @ref{K&R Symbols}.
4104 The first line in a ``topmost'' definition. @ref{Function Symbols}.
4105 @item topmost-intro-cont
4106 Topmost definition continuation lines. This is only used in the parts
4107 that aren't covered by other symbols such as @code{func-decl-cont} and
4108 @code{knr-argdecl}. @ref{Function Symbols}.
4109 @item annotation-top-cont
4110 Topmost definition continuation lines where all previous items are
4111 annotations. @ref{Java Symbols}.
4112 @item member-init-intro
4113 First line in a member initialization list. @ref{Class Symbols}.
4114 @item member-init-cont
4115 Subsequent member initialization list lines. @ref{Class Symbols}.
4117 First line of a multiple inheritance list. @ref{Class Symbols}.
4119 Subsequent multiple inheritance lines. @ref{Class Symbols}.
4121 Statement block open brace. @ref{Literal Symbols}.
4123 Statement block close brace. @ref{Conditional Construct Symbols}.
4124 @item brace-list-open
4125 Open brace of an enum or static array list. @ref{Brace List Symbols}.
4126 @item brace-list-close
4127 Close brace of an enum or static array list. @ref{Brace List Symbols}.
4128 @item brace-list-intro
4129 First line in an enum or static array list. @ref{Brace List Symbols}.
4130 @item brace-list-entry
4131 Subsequent lines in an enum or static array list. @ref{Brace List
4133 @item brace-entry-open
4134 Subsequent lines in an enum or static array list where the line begins
4135 with an open brace. @ref{Brace List Symbols}.
4137 A statement. @ref{Function Symbols}.
4138 @item statement-cont
4139 A continuation of a statement. @ref{Function Symbols}.
4140 @item annotation-var-cont
4141 A continuation of a statement where all previous items are
4142 annotations. @ref{Java Symbols}.
4143 @item statement-block-intro
4144 The first line in a new statement block. @ref{Conditional Construct
4146 @item statement-case-intro
4147 The first line in a case block. @ref{Switch Statement Symbols}.
4148 @item statement-case-open
4149 The first line in a case block that starts with a brace. @ref{Switch
4152 The first line after a conditional or loop construct.
4153 @ref{Conditional Construct Symbols}.
4154 @item substatement-open
4155 The brace that opens a substatement block. @ref{Conditional Construct
4157 @item substatement-label
4158 The first line after a conditional or loop construct if it's a label.
4159 @ref{Conditional Construct Symbols}.
4161 A label in a @code{switch} block. @ref{Switch Statement Symbols}.
4163 C++ access control label. @ref{Class Symbols}.
4165 Any other label. @ref{Literal Symbols}.
4166 @item do-while-closure
4167 The @code{while} line that ends a @code{do}-@code{while} construct.
4168 @ref{Conditional Construct Symbols}.
4170 The @code{else} line of an @code{if}-@code{else} construct.
4171 @ref{Conditional Construct Symbols}.
4173 The @code{catch} or @code{finally} (in Java) line of a
4174 @code{try}-@code{catch} construct. @ref{Conditional Construct
4177 A line containing only a comment introduction. @ref{Literal Symbols}.
4179 The first line in an argument list. @ref{Paren List Symbols}.
4181 Subsequent argument list lines when no arguments follow on the same
4182 line as the arglist opening paren. @ref{Paren List Symbols}.
4183 @item arglist-cont-nonempty
4184 Subsequent argument list lines when at least one argument follows on
4185 the same line as the arglist opening paren. @ref{Paren List Symbols}.
4187 The solo close paren of an argument list. @ref{Paren List Symbols}.
4189 Lines continuing a stream operator (C++ only). @ref{Literal
4190 Symbols}. @c @emph{FIXME!!! Can this not be moved somewhere better?}
4192 The line is nested inside a class definition. @ref{Class Symbols}.
4194 The start of a preprocessor macro definition. @ref{Literal Symbols}.
4195 @item cpp-define-intro
4196 The first line inside a multiline preprocessor macro if
4197 @code{c-syntactic-indentation-in-macros} is set. @ref{Multiline Macro
4199 @item cpp-macro-cont
4200 All lines inside multiline preprocessor macros if
4201 @code{c-syntactic-indentation-in-macros} is @code{nil}.
4202 @ref{Multiline Macro Symbols}.
4204 A C++ friend declaration. @ref{Class Symbols}.
4205 @item objc-method-intro
4206 The first line of an Objective-C method definition. @ref{Objective-C
4208 @item objc-method-args-cont
4209 Lines continuing an Objective-C method definition. @ref{Objective-C
4211 @item objc-method-call-cont
4212 Lines continuing an Objective-C method call. @ref{Objective-C Method
4214 @item extern-lang-open
4215 Brace that opens an @code{extern} block (e.g. @code{extern "C"
4216 @{...@}}). @ref{External Scope Symbols}.
4217 @item extern-lang-close
4218 Brace that closes an @code{extern} block. @ref{External Scope
4221 Analogous to @code{inclass} syntactic symbol, but used inside
4222 @code{extern} blocks. @ref{External Scope Symbols}.
4223 @item namespace-open
4224 @itemx namespace-close
4226 These are analogous to the three @code{extern-lang} symbols above, but
4227 are returned for C++ namespace blocks. @ref{External Scope Symbols}.
4231 Analogous to the above, but for CORBA IDL @code{module} blocks.
4232 @ref{External Scope Symbols}.
4233 @item composition-open
4234 @itemx composition-close
4235 @itemx incomposition
4236 Analogous to the above, but for CORBA CIDL @code{composition} blocks.
4237 @ref{External Scope Symbols}.
4238 @item template-args-cont
4239 C++ template argument list continuations. @ref{Class Symbols}.
4241 Analogous to @code{inclass} syntactic symbol, but used inside lambda
4242 (i.e. anonymous) functions. Only used in Pike mode. @ref{Statement
4244 @item lambda-intro-cont
4245 Lines continuing the header of a lambda function, i.e. between the
4246 @code{lambda} keyword and the function body. Only used in Pike mode.
4247 @ref{Statement Block Symbols}.
4248 @item inexpr-statement
4249 A statement block inside an expression. The gcc C and C++ extension
4250 for this is recognized. It's also used for the special functions that
4251 take a statement block as an argument in Pike. @ref{Statement Block
4254 A class definition inside an expression. This is used for anonymous
4255 classes in Java. It's also used for anonymous array initializers in
4256 Java. @ref{Java Symbols}.
4260 * Function Symbols::
4262 * Conditional Construct Symbols::
4263 * Switch Statement Symbols::
4264 * Brace List Symbols::
4265 * External Scope Symbols::
4266 * Paren List Symbols::
4268 * Multiline Macro Symbols::
4269 * Objective-C Method Symbols::
4271 * Statement Block Symbols::
4275 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4276 @node Function Symbols, Class Symbols, Syntactic Symbols, Syntactic Symbols
4277 @comment node-name, next, previous, up
4278 @subsection Function Symbols
4279 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4281 This example shows a typical function declaration.
4285 2: swap( int& a, int& b )
4295 @ssindex topmost-intro
4296 @ssindex topmost-intro-cont
4298 @ssindex defun-close
4299 @ssindex defun-block-intro
4300 Line 1 shows a @code{topmost-intro} since it is the first line that
4301 introduces a top-level construct. Line 2 is a continuation of the
4302 top-level construct introduction so it has the syntax
4303 @code{topmost-intro-cont}. Line 3 shows a @code{defun-open} since it is
4304 the brace that opens a top-level function definition. Line 9 is the
4306 @code{defun-close} since it contains the brace that closes the top-level
4307 function definition. Line 4 is a @code{defun-block-intro}, i.e. it is
4308 the first line of a brace-block, enclosed in a
4309 top-level function definition.
4312 @ssindex statement-cont
4313 Lines 5, 6, and 7 are all given @code{statement} syntax since there
4314 isn't much special about them. Note however that line 8 is given
4315 @code{statement-cont} syntax since it continues the statement begun
4316 on the previous line.
4318 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4319 @node Class Symbols, Conditional Construct Symbols, Function Symbols, Syntactic Symbols
4320 @comment node-name, next, previous, up
4321 @subsection Class related Symbols
4322 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4324 Here's an example which illustrates some C++ class syntactic symbols:
4329 3: public Amplifiable
4333 7: : eString( new BassString( 0.105 )),
4334 8: aString( new BassString( 0.085 )),
4335 9: dString( new BassString( 0.065 )),
4336 10: gString( new BassString( 0.045 ))
4338 12: eString.tune( 'E' );
4339 13: aString.tune( 'A' );
4340 14: dString.tune( 'D' );
4341 15: gString.tune( 'G' );
4343 17: friend class Luthier;
4348 @ssindex class-close
4349 As in the previous example, line 1 has the @code{topmost-intro} syntax.
4350 Here however, the brace that opens a C++ class definition on line 4 is
4351 assigned the @code{class-open} syntax. Note that in C++, classes,
4352 structs, and unions are essentially equivalent syntactically (and are
4353 very similar semantically), so replacing the @code{class} keyword in the
4354 example above with @code{struct} or @code{union} would still result in a
4355 syntax of @code{class-open} for line 4 @footnote{This is the case even
4356 for C and Objective-C. For consistency, structs in all supported
4357 languages are syntactically equivalent to classes. Note however that
4358 the keyword @code{class} is meaningless in C and Objective-C.}.
4359 Similarly, line 18 is assigned @code{class-close} syntax.
4361 @ssindex inher-intro
4363 Line 2 introduces the inheritance list for the class so it is assigned
4364 the @code{inher-intro} syntax, and line 3, which continues the
4365 inheritance list is given @code{inher-cont} syntax.
4367 @ssindex access-label
4369 Hitting @kbd{C-c C-s} on line 5 shows the following analysis:
4372 ((inclass 58) (access-label 58))
4376 The primary syntactic symbol for this line is @code{access-label} as
4377 this is a label keyword that specifies access protection in C++. However,
4378 because this line is also a top-level construct inside a class
4379 definition, the analysis actually shows two syntactic symbols. The
4380 other syntactic symbol assigned to this line is @code{inclass}.
4381 Similarly, line 6 is given both @code{inclass} and @code{topmost-intro}
4385 ((inclass 58) (topmost-intro 60))
4388 @ssindex member-init-intro
4389 @ssindex member-init-cont
4390 Line 7 introduces a C++ member initialization list and as such is given
4391 @code{member-init-intro} syntax. Note that in this case it is
4392 @emph{not} assigned @code{inclass} since this is not considered a
4393 top-level construct. Lines 8 through 10 are all assigned
4394 @code{member-init-cont} since they continue the member initialization
4395 list started on line 7.
4397 @cindex in-class inline methods
4398 @ssindex inline-open
4399 @ssindex inline-close
4400 Line 11's analysis is a bit more complicated:
4403 ((inclass 58) (inline-open))
4406 This line is assigned a syntax of both @code{inline-open} and
4407 @code{inclass} because it opens an @dfn{in-class} C++ inline method
4408 definition. This is distinct from, but related to, the C++ notion of an
4409 inline function in that its definition occurs inside an enclosing class
4410 definition, which in C++ implies that the function should be inlined.
4411 However, if the definition of the @code{Bass} constructor appeared
4412 outside the class definition, the construct would be given the
4413 @code{defun-open} syntax, even if the keyword @code{inline} appeared
4414 before the method name, as in:
4419 3: public Amplifiable
4427 11: : eString( new BassString( 0.105 )),
4428 12: aString( new BassString( 0.085 )),
4429 13: dString( new BassString( 0.065 )),
4430 14: gString( new BassString( 0.045 ))
4432 16: eString.tune( 'E' );
4433 17: aString.tune( 'A' );
4434 18: dString.tune( 'D' );
4435 19: gString.tune( 'G' );
4440 Returning to the previous example, line 16 is given @code{inline-close}
4441 syntax, while line 12 is given @code{defun-block-open} syntax, and lines
4442 13 through 15 are all given @code{statement} syntax. Line 17 is
4443 interesting in that its syntactic analysis list contains three
4447 ((inclass 58) (topmost-intro 380) (friend))
4450 The @code{friend} and @code{inline-open} syntactic symbols are
4451 modifiers that do not have anchor positions.
4453 @ssindex template-args-cont
4454 Template definitions introduce yet another syntactic symbol:
4457 1: ThingManager <int,
4458 2: Framework::Callback *,
4459 3: Mutex> framework_callbacks;
4462 Here, line 1 is analyzed as a @code{topmost-intro}, but lines 2 and 3
4463 are both analyzed as @code{template-args-cont} lines.
4465 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4466 @node Conditional Construct Symbols, Switch Statement Symbols, Class Symbols, Syntactic Symbols
4467 @comment node-name, next, previous, up
4468 @subsection Conditional Construct Symbols
4469 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4471 Here is a (totally contrived) example which illustrates how syntax is
4472 assigned to various conditional constructs:
4475 1: void spam( int index )
4477 3: for( int i=0; i<index; i++ )
4480 6: do_something_special();
4483 9: do_something( i );
4486 12: another_thing( i-- );
4492 Only the lines that illustrate new syntactic symbols will be discussed.
4494 @ssindex substatement-open
4495 @ssindex statement-block-intro
4496 @ssindex block-close
4497 Line 4 has a brace which opens a conditional's substatement block. It
4498 is thus assigned @code{substatement-open} syntax, and since line 5 is
4499 the first line in the substatement block, it is assigned
4500 @code{statement-block-intro} syntax. Line 10 contains the brace
4501 that closes the inner substatement block, and is therefore given the
4502 syntax @code{block-close}@footnote{@code{block-open} is used only for
4503 ``free-standing'' blocks, and is somewhat rare (@pxref{Literal
4504 Symbols} for an example.)}. Line 13 is treated the same way.
4506 @ssindex substatement
4507 Lines 6 and 9 are also substatements of conditionals, but since they
4508 don't start blocks they are given @code{substatement} syntax
4509 instead of @code{substatement-open}.
4511 @ssindex substatement-label
4512 Line 8 contains a label, which is normally given @code{label} syntax.
4513 This one is however a bit special since it's between a conditional and
4514 its substatement. It's analyzed as @code{substatement-label} to let you
4515 handle this rather odd case differently from normal labels.
4517 @ssindex else-clause
4518 @ssindex catch-clause
4519 Line 7 start with an @code{else} that matches the @code{if} statement on
4520 line 5. It is therefore given the @code{else-clause} syntax and is
4521 anchored on the matching @code{if}. The @code{try}-@code{catch}
4522 constructs in C++ and Java are treated this way too, except that
4523 @code{catch} and (in Java) @code{finally}, are marked with
4524 @code{catch-clause}.
4526 @ssindex do-while-closure
4527 The @code{while} construct on line 14 that closes a @code{do}
4528 conditional is given the special syntax @code{do-while-closure} if it
4529 appears on a line by itself. Note that if the @code{while} appeared on
4530 the same line as the preceding close brace, that line would still have
4531 @code{block-close} syntax.
4533 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4534 @node Switch Statement Symbols, Brace List Symbols, Conditional Construct Symbols, Syntactic Symbols
4535 @comment node-name, next, previous, up
4536 @subsection Switch Statement Symbols
4537 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4539 Switch statements have their own set of syntactic symbols. Here's an
4543 1: void spam( enum Ingredient i )
4550 8: drink_some_water();
4562 @ssindex statement-case-intro
4563 @ssindex statement-case-open
4564 Here, lines 4, 7, and 10 are all assigned @code{case-label} syntax,
4565 while lines 5 and 8 are assigned @code{statement-case-intro}. Line 11
4566 is treated slightly differently since it contains a brace that opens a
4567 block --- it is given @code{statement-case-open} syntax.
4569 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4570 @node Brace List Symbols, External Scope Symbols, Switch Statement Symbols, Syntactic Symbols
4571 @comment node-name, next, previous, up
4572 @subsection Brace List Symbols
4573 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4576 There are a set of syntactic symbols that are used to recognize
4577 constructs inside of brace lists. A brace list is defined as an
4578 @code{enum} or aggregate initializer list, such as might statically
4579 initialize an array of structs. The three special aggregate constructs
4580 in Pike, @code{(@{ @})}, @code{([ ])} and @code{(< >)}, are treated as
4581 brace lists too. An example:
4584 1: static char* ingredients[] =
4592 @ssindex brace-list-open
4593 @ssindex brace-list-intro
4594 @ssindex brace-list-close
4595 @ssindex brace-list-entry
4596 Following convention, line 2 in this example is assigned
4597 @code{brace-list-open} syntax, and line 3 is assigned
4598 @code{brace-list-intro} syntax. Likewise, line 6 is assigned
4599 @code{brace-list-close} syntax. Lines 4 and 5 however, are assigned
4600 @code{brace-list-entry} syntax, as would all subsequent lines in this
4603 @ssindex brace-entry-open
4604 Your static initializer might be initializing nested structures, for
4608 1: struct intpairs[] =
4621 Here, you've already seen the analysis of lines 1, 2, 3, and 11. On
4622 line 4, things get interesting; this line is assigned
4623 @code{brace-entry-open} syntactic symbol because it's a bracelist entry
4624 line that starts with an open brace. Lines 5 and 6 (and line 9) are
4625 pretty standard, and line 7 is a @code{brace-list-close} as you'd
4626 expect. Once again, line 8 is assigned as @code{brace-entry-open} as is
4629 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4630 @node External Scope Symbols, Paren List Symbols, Brace List Symbols, Syntactic Symbols
4631 @comment node-name, next, previous, up
4632 @subsection External Scope Symbols
4633 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4635 External language definition blocks also have their own syntactic
4636 symbols. In this example:
4641 3: int thing_one( int );
4642 4: int thing_two( double );
4646 @ssindex extern-lang-open
4647 @ssindex extern-lang-close
4648 @ssindex inextern-lang
4651 line 2 is given the @code{extern-lang-open} syntax, while line 5 is given
4652 the @code{extern-lang-close} syntax. The analysis for line 3 yields:
4655 ((inextern-lang) (topmost-intro 14))
4659 where @code{inextern-lang} is a modifier similar in purpose to
4662 There are various other top level blocks like @code{extern}, and they
4663 are all treated in the same way except that the symbols are named after
4664 the keyword that introduces the block. E.g. C++ namespace blocks get
4665 the three symbols @code{namespace-open}, @code{namespace-close} and
4666 @code{innamespace}. The currently recognized top level blocks are:
4669 @item @code{extern-lang-open}, @code{extern-lang-close}, @code{inextern-lang}
4670 @code{extern} blocks in C and C++.@footnote{These should logically be
4671 named @code{extern-open}, @code{extern-close} and @code{inextern}, but
4672 that isn't the case for historical reasons.}
4674 @item @code{namespace-open}, @code{namespace-close}, @code{innamespace}
4675 @ssindex namespace-open
4676 @ssindex namespace-close
4677 @ssindex innamespace
4678 @code{namespace} blocks in C++.
4680 @item @code{module-open}, @code{module-close}, @code{inmodule}
4681 @ssindex module-open
4682 @ssindex module-close
4684 @code{module} blocks in CORBA IDL.
4686 @item @code{composition-open}, @code{composition-close}, @code{incomposition}
4687 @ssindex composition-open
4688 @ssindex composition-close
4689 @ssindex incomposition
4690 @code{composition} blocks in CORBA CIDL.
4693 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4694 @node Paren List Symbols, Literal Symbols, External Scope Symbols, Syntactic Symbols
4695 @comment node-name, next, previous, up
4696 @subsection Parenthesis (Argument) List Symbols
4697 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4699 A number of syntactic symbols are associated with parenthesis lists,
4700 a.k.a argument lists, as found in function declarations and function
4701 calls. This example illustrates these:
4704 1: void a_function( int line1,
4707 4: void a_longer_function(
4712 9: void call_them( int line1, int line2 )
4719 16: a_longer_function( line1,
4724 @ssindex arglist-intro
4725 @ssindex arglist-close
4726 Lines 5 and 12 are assigned @code{arglist-intro} syntax since they are
4727 the first line following the open parenthesis, and lines 7 and 14 are
4728 assigned @code{arglist-close} syntax since they contain the parenthesis
4729 that closes the argument list.
4731 @ssindex arglist-cont-nonempty
4732 @ssindex arglist-cont
4733 Lines that continue argument lists can be assigned one of two syntactic
4734 symbols. For example, Lines 2 and 17
4735 are assigned @code{arglist-cont-nonempty} syntax. What this means
4736 is that they continue an argument list, but that the line containing the
4737 parenthesis that opens the list is @emph{not empty} following the open
4738 parenthesis. Contrast this against lines 6 and 13 which are assigned
4739 @code{arglist-cont} syntax. This is because the parenthesis that opens
4740 their argument lists is the last character on that line.
4742 Syntactic elements with @code{arglist-intro},
4743 @code{arglist-cont-nonempty}, and @code{arglist-close} contain two
4744 buffer positions: the anchor position (the beginning of the
4745 declaration or statement) and the position of the open parenthesis.
4746 The latter position can be used in a line-up function (@pxref{Line-Up
4749 Note that there is no @code{arglist-open} syntax. This is because any
4750 parenthesis that opens an argument list, appearing on a separate line,
4751 is assigned the @code{statement-cont} syntax instead.
4753 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4754 @node Literal Symbols, Multiline Macro Symbols, Paren List Symbols, Syntactic Symbols
4755 @comment node-name, next, previous, up
4756 @subsection Comment String Label and Macro Symbols
4757 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4759 A few miscellaneous syntactic symbols that haven't been previously
4760 covered are illustrated by this C++ example:
4763 1: void Bass::play( int volume )
4766 4: /* this line starts a multiline
4767 5: * comment. This line should get `c' syntax */
4769 7: char* a_multiline_string = "This line starts a multiline \
4770 8: string. This line should get `string' syntax.";
4778 16: cout << "I played "
4784 The lines to note in this example include:
4788 @ssindex func-decl-cont
4789 Line 2 is assigned the @code{func-decl-cont} syntax.
4792 @ssindex comment-intro
4793 Line 4 is assigned both @code{defun-block-intro} @emph{and}
4794 @code{comment-intro} syntax. A syntactic element with
4795 @code{comment-intro} has no anchor point --- It is always accompanied
4796 by another syntactic element which does have one.
4800 Line 5 is assigned @code{c} syntax.
4803 @cindex syntactic whitespace
4804 Line 6 which, even though it contains nothing but whitespace, is
4805 assigned @code{defun-block-intro}. Note that the appearance of the
4806 comment on lines 4 and 5 do not cause line 6 to be assigned
4807 @code{statement} syntax because comments are considered to be
4808 @dfn{syntactic whitespace}, which are ignored when analyzing
4813 Line 8 is assigned @code{string} syntax.
4817 Line 10 is assigned @code{label} syntax.
4821 Line 11 is assigned @code{block-open} as well as @code{statement}
4822 syntax. A @code{block-open} syntactic element doesn't have an anchor
4823 position, since it always appears with another syntactic element which
4828 Lines 12 and 14 are assigned @code{cpp-macro} syntax in addition to the
4829 normal syntactic symbols (@code{statement-block-intro} and
4830 @code{statement}, respectively). Normally @code{cpp-macro} is
4831 configured to cancel out the normal syntactic context to make all
4832 preprocessor directives stick to the first column, but that's easily
4833 changed if you want preprocessor directives to be indented like the rest
4834 of the code. Like @code{comment-intro}, a syntactic element with
4835 @code{cpp-macro} doesn't contain an anchor position.
4839 Line 17 is assigned @code{stream-op} syntax.
4842 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4843 @node Multiline Macro Symbols, Objective-C Method Symbols, Literal Symbols, Syntactic Symbols
4844 @comment node-name, next, previous, up
4845 @subsection Multiline Macro Symbols
4846 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4848 @cindex multiline macros
4849 @cindex syntactic whitespace
4850 @ssindex cpp-define-intro
4851 @ssindex cpp-macro-cont
4852 Multiline preprocessor macro definitions are normally handled just like
4853 other code, i.e. the lines inside them are indented according to the
4854 syntactic analysis of the preceding lines inside the macro. The first
4855 line inside a macro definition (i.e. the line after the starting line of
4856 the cpp directive itself) gets @code{cpp-define-intro}. In this example:
4859 1: #define LIST_LOOP(cons, listp) \
4860 2: for (cons = listp; !NILP (cons); cons = XCDR (cons)) \
4861 3: if (!CONSP (cons)) \
4862 4: signal_error ("Invalid list format", listp); \
4867 line 1 is given the syntactic symbol @code{cpp-macro}. The first line
4868 of a cpp directive is always given that symbol. Line 2 is given
4869 @code{cpp-define-intro}, so that you can give the macro body as a whole
4870 some extra indentation. Lines 3 through 5 are then analyzed as normal
4871 code, i.e. @code{substatement} on lines 3 and 4, and @code{else-clause}
4874 The syntactic analysis inside macros can be turned off with
4875 @code{c-syntactic-indentation-in-macros} (@pxref{Custom Macros}). In
4876 that case, lines 2 through 5 would all be given @code{cpp-macro-cont}
4877 with an anchor position pointing to the @code{#} which starts the cpp
4878 directive@footnote{This is how @ccmode{} 5.28 and earlier analyzed
4881 @xref{Custom Macros}, for more info about the treatment of macros.
4883 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4884 @node Objective-C Method Symbols, Java Symbols, Multiline Macro Symbols, Syntactic Symbols
4885 @comment node-name, next, previous, up
4886 @subsection Objective-C Method Symbols
4887 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4889 In Objective-C buffers, there are three additional syntactic symbols
4890 assigned to various message calling constructs. Here's an example
4894 1: - (void)setDelegate:anObject
4897 4: [delegate masterWillRebind:self
4898 5: toDelegate:anObject
4899 6: withExtraStuff:stuff];
4903 @ssindex objc-method-intro
4904 @ssindex objc-method-args-cont
4905 @ssindex objc-method-call-cont
4906 Here, line 1 is assigned @code{objc-method-intro} syntax, and line 2 is
4907 assigned @code{objc-method-args-cont} syntax. Lines 5 and 6 are both
4908 assigned @code{objc-method-call-cont} syntax.
4910 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4911 @node Java Symbols, Statement Block Symbols, Objective-C Method Symbols, Syntactic Symbols
4912 @comment node-name, next, previous, up
4913 @subsection Java Symbols
4914 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4916 Java has a concept of anonymous classes which can look something like
4921 2: public void watch(Observable o) @{
4923 4: Observer obs = new Observer() @{
4924 5: public void update(Observable o, Object arg) @{
4925 6: history.addElement(arg);
4928 9: o.addObserver(obs);
4932 @ssindex inexpr-class
4933 The brace following the @code{new} operator opens the anonymous class.
4934 Lines 5 and 8 are assigned the @code{inexpr-class} syntax, besides the
4935 @code{inclass} symbol used in normal classes. Thus, the class will be
4936 indented just like a normal class, with the added indentation given to
4937 @code{inexpr-class}. An @code{inexpr-class} syntactic element doesn't
4938 have an anchor position.
4940 @ssindex annotation-top-cont
4941 @ssindex annotation-var-cont
4942 Line 2 is assigned the @code{annotation-top-cont} syntax, due to it being a
4943 continuation of a topmost introduction with an annotation symbol preceding
4944 the current line. Similarly, line 4 is assigned the @code{annotation-var-cont}
4945 syntax due to it being a continuation of a variable declaration where preceding
4946 the declaration is an annotation.
4948 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4949 @node Statement Block Symbols, K&R Symbols, Java Symbols, Syntactic Symbols
4950 @comment node-name, next, previous, up
4951 @subsection Statement Block Symbols
4952 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4954 There are a few occasions where a statement block might be used inside
4955 an expression. One is in C or C++ code using the gcc extension for
4960 2: int y = foo (); int z;
4961 3: if (y > 0) z = y; else z = - y;
4966 @ssindex inexpr-statement
4967 Lines 2 and 5 get the @code{inexpr-statement} syntax, besides the
4968 symbols they'd get in a normal block. Therefore, the indentation put on
4969 @code{inexpr-statement} is added to the normal statement block
4970 indentation. An @code{inexpr-statement} syntactic element doesn't
4971 contain an anchor position.
4973 In Pike code, there are a few other situations where blocks occur inside
4974 statements, as illustrated here:
4979 3: string s = map (backtrace()[-2][3..],
4983 7: return sprintf ("%t", arg);
4984 8: @}) * ", " + "\n";
4986 10: write (s + "\n");
4992 @ssindex lambda-intro-cont
4993 Lines 4 through 8 contain a lambda function, which @ccmode{} recognizes
4994 by the @code{lambda} keyword. If the function argument list is put
4995 on a line of its own, as in line 5, it gets the @code{lambda-intro-cont}
4996 syntax. The function body is handled as an inline method body, with the
4997 addition of the @code{inlambda} syntactic symbol. This means that line
4998 6 gets @code{inlambda} and @code{inline-open}, and line 8 gets
4999 @code{inline-close}@footnote{You might wonder why it doesn't get
5000 @code{inlambda} too. It's because the closing brace is relative to the
5001 opening brace, which stands on its own line in this example. If the
5002 opening brace was hanging on the previous line, then the closing brace
5003 would get the @code{inlambda} syntax too to be indented correctly.}.
5005 @ssindex inexpr-statement
5006 On line 9, @code{catch} is a special function taking a statement block
5007 as its argument. The block is handled as an in-expression statement
5008 with the @code{inexpr-statement} syntax, just like the gcc extended C
5009 example above. The other similar special function, @code{gauge}, is
5010 handled like this too.
5012 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5013 @node K&R Symbols, , Statement Block Symbols, Syntactic Symbols
5014 @comment node-name, next, previous, up
5015 @subsection K&R Symbols
5016 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5018 @ssindex knr-argdecl-intro
5019 @ssindex knr-argdecl
5020 Two other syntactic symbols can appear in old style, non-prototyped C
5021 code @footnote{a.k.a. K&R C, or Kernighan & Ritchie C}:
5024 1: int add_three_integers(a, b, c)
5029 6: return a + b + c;
5033 Here, line 2 is the first line in an argument declaration list and so is
5034 given the @code{knr-argdecl-intro} syntactic symbol. Subsequent lines
5035 (i.e. lines 3 and 4 in this example), are given @code{knr-argdecl}
5039 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5040 @node Indentation Calculation, , Syntactic Symbols, Indentation Engine Basics
5041 @comment node-name, next, previous, up
5042 @section Indentation Calculation
5044 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5046 Indentation for a line is calculated from the syntactic context
5047 (@pxref{Syntactic Analysis}).
5049 First, a buffer position is found whose column will be the base for the
5050 indentation calculation. It's the anchor position in the first
5051 syntactic element that provides one that is used. If no syntactic
5052 element has an anchor position then column zero is used.
5054 Second, the syntactic symbols in each syntactic element are looked up
5055 in the @code{c-offsets-alist} style variable
5056 (@pxref{c-offsets-alist}), which is an association list of syntactic
5057 symbols and the offsets to apply for those symbols. These offsets are
5058 added together with the base column to produce the new indentation
5061 Let's use our two code examples above to see how this works. Here is
5062 our first example again:
5065 1: void swap( int& a, int& b )
5073 Let's say point is on line 3 and we hit the @key{TAB} key to reindent
5074 the line. The syntactic context for that line is:
5077 ((defun-block-intro 29))
5081 Since buffer position 29 is the first and only anchor position in the
5082 list, @ccmode{} goes there and asks for the current column. This brace
5083 is in column zero, so @ccmode{} uses @samp{0} as the base column.
5085 Next, @ccmode{} looks up @code{defun-block-intro} in the
5086 @code{c-offsets-alist} style variable. Let's say it finds the value
5087 @samp{4}; it adds this to the base column @samp{0}, yielding a running
5088 total indentation of 4 spaces.
5090 Since there is only one syntactic element on the list for this line,
5091 indentation calculation is complete, and the total indentation for the
5094 Here's another example:
5097 1: int add( int val, int incr, int doit )
5101 5: return( val + incr );
5107 If we were to hit @kbd{TAB} on line 4 in the above example, the same
5108 basic process is performed, despite the differences in the syntactic
5109 context. The context for this line is:
5112 ((substatement-open 46))
5115 Here, @ccmode{} goes to buffer position 46, which is the @samp{i} in
5116 @code{if} on line 3. This character is in the fourth column on that
5117 line so the base column is @samp{4}. Then @ccmode{} looks up the
5118 @code{substatement-open} symbol in @code{c-offsets-alist}. Let's say it
5119 finds the value @samp{4}. It's added with the base column and yields an
5120 indentation for the line of 8 spaces.
5124 Actually, it's a bit more complicated than that since the entries on
5125 @code{c-offsets-alist} can be much more than plain offsets.
5126 @xref{c-offsets-alist}, for the full story.
5128 Anyway, the mode usually just does The Right Thing without you having to
5129 think about it in this much detail. But when customizing indentation,
5130 it's helpful to understand the general indentation model being used.
5132 As you configure @ccmode{}, you might want to set the variable
5133 @code{c-echo-syntactic-information-p} to non-@code{nil} so that the
5134 syntactic context and calculated offset always is echoed in the
5135 minibuffer when you hit @kbd{TAB}.
5138 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5139 @node Customizing Indentation, Custom Macros, Indentation Engine Basics, Top
5140 @comment node-name, next, previous, up
5141 @chapter Customizing Indentation
5142 @cindex customization, indentation
5144 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5146 The principal variable for customizing indentation is the style
5147 variable @code{c-offsets-alist}, which gives an @dfn{offset} (an
5148 indentation rule) for each syntactic symbol. Its structure and
5149 semantics are completely described in @ref{c-offsets-alist}. The
5150 various ways you can set the variable, including the use of the
5151 @ccmode{} style system, are described in @ref{Config Basics} and its
5152 sections, in particular @ref{Style Variables}.
5154 The simplest and most used kind of ``offset'' setting in
5155 @code{c-offsets-alist} is in terms of multiples of
5156 @code{c-basic-offset}:
5158 @defopt c-basic-offset
5159 @vindex basic-offset (c-)
5160 This style variable holds the basic offset between indentation levels.
5161 It's factory default is 4, but all the built-in styles set it
5162 themselves, to some value between 2 (for @code{gnu} style) and 8 (for
5163 @code{bsd}, @code{linux}, and @code{python} styles).
5166 The most flexible ``offset'' setting you can make in
5167 @code{c-offsets-alist} is a line-up function (or even a list of them),
5168 either one supplied by @ccmode{} (@pxref{Line-Up Functions}) or one
5169 you write yourself (@pxref{Custom Line-Up}).
5171 Finally, in @ref{Other Indentation} you'll find the tool of last
5172 resort: a hook which is called after a line has been indented. You
5173 can install functions here to make ad-hoc adjustments to any line's
5178 * Interactive Customization::
5179 * Line-Up Functions::
5181 * Other Indentation::
5185 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5186 @node c-offsets-alist, Interactive Customization, Customizing Indentation, Customizing Indentation
5187 @comment node-name, next, previous, up
5188 @section c-offsets-alist
5189 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5191 This section explains the structure and semantics of the style
5192 variable @code{c-offset-alist}, the principal variable for configuring
5193 indentation. Details of how to set it up, and its relationship to
5194 @ccmode{}'s style system are given in @ref{Style Variables}.
5196 @defopt c-offsets-alist
5197 @vindex offsets-alist (c-)
5198 This is an alist which associates an offset with each syntactic
5199 symbol. This @dfn{offset} is a rule specifying how to indent a line
5200 whose syntactic context matches the symbol. @xref{Syntactic
5203 Note that the buffer-local binding of this alist in a @ccmode{} buffer
5204 contains an entry for @emph{every} syntactic symbol. Its global
5205 binding and its settings within style specifications usually contain
5206 only a few entries. @xref{Style Variables}.
5208 The offset specification associated with any particular syntactic
5209 symbol can be an integer, a variable name, a vector, a function or
5210 lambda expression, a list, or one of the following special symbols:
5211 @code{+}, @code{-}, @code{++}, @code{--}, @code{*}, or @code{/}. The
5212 meanings of these values are described in detail below.
5214 Here is an example fragment of a @code{c-offsets-alist}, showing some
5215 of these kinds of offsets:
5221 (topmost-intro-cont . c-lineup-topmost-intro-cont)
5222 (statement-block-intro . (add c-lineup-whitesmith-in-block
5223 c-indent-multi-line-block))
5229 @deffn Command c-set-offset (@kbd{C-c C-o})
5230 @findex set-offset (c-)
5232 This command changes the entry for a syntactic symbol in the current
5233 binding of @code{c-offsets-alist}, or it inserts a new entry if there
5234 isn't already one for that syntactic symbol.
5236 You can use @code{c-set-offsets} interactively within a @ccmode{}
5237 buffer to make experimental changes to your indentation settings.
5238 @kbd{C-c C-o} prompts you for the syntactic symbol to change
5239 (defaulting to that of the current line) and the new offset
5240 (defaulting to the current offset).
5242 @code{c-set-offsets} takes two arguments when used programmatically:
5243 @var{symbol}, the syntactic element symbol to change and @var{offset},
5244 the new offset for that syntactic element. You can call the command
5245 in your @file{.emacs} to change the global binding of
5246 @code{c-offsets-alist} (@pxref{Style Variables}); you can use it in a
5247 hook function to make changes from the current style. @ccmode{}
5248 itself uses this function when initializing styles.
5251 @cindex offset specification
5252 The ``offset specifications'' in @code{c-offsets-alist} can be any of
5257 The integer specifies a relative offset. All relative
5258 offsets@footnote{The syntactic context @code{@w{((defun-block-intro
5259 2724) (comment-intro))}} would likely have two relative offsets.} will
5260 be added together and used to calculate the indentation relative to an
5261 anchor position earlier in the buffer. @xref{Indentation
5262 Calculation}, for details. Most of the time, it's probably better to
5263 use one of the special symbols like @code{+} than an integer (apart
5266 @item One of the symbols @code{+}, @code{-}, @code{++}, @code{--}, @code{*}, or @code{/}
5267 These special symbols describe a relative offset in multiples of
5268 @code{c-basic-offset}:
5270 By defining a style's indentation in terms of @code{c-basic-offset},
5271 you can change the amount of whitespace given to an indentation level
5272 while maintaining the same basic shape of your code. Here are the
5273 values that the special symbols correspond to:
5277 @code{c-basic-offset} times 1
5279 @code{c-basic-offset} times -1
5281 @code{c-basic-offset} times 2
5283 @code{c-basic-offset} times -2
5285 @code{c-basic-offset} times 0.5
5287 @code{c-basic-offset} times -0.5
5291 The first element of the vector, an integer, sets the absolute
5292 indentation column. This will override any previously calculated
5293 indentation, but won't override relative indentation calculated from
5294 syntactic elements later on in the syntactic context of the line being
5295 indented. @xref{Indentation Calculation}. Any elements in the vector
5296 beyond the first will be ignored.
5298 @item A function or lambda expression
5299 The function will be called and its return value will in turn be
5300 evaluated as an offset specification. Functions are useful when more
5301 context than just the syntactic symbol is needed to get the desired
5302 indentation. @xref{Line-Up Functions}, and @ref{Custom Line-Up}, for
5305 @item A symbol with a variable binding
5306 If the symbol also has a function binding, the function takes
5307 precedence over the variable. Otherwise the value of the variable is
5308 used. It must be an integer (which is used as relative offset) or a
5309 vector (an absolute offset).
5312 The offset can also be a list containing several offset
5313 specifications; these are evaluated recursively and combined. A list
5314 is typically only useful when some of the offsets are line-up
5315 functions. A common strategy is calling a sequence of functions in
5316 turn until one of them recognizes that it is appropriate for the
5317 source line and returns a non-@code{nil} value.
5319 @code{nil} values are always ignored when the offsets are combined.
5320 The first element of the list specifies the method of combining the
5321 non-@code{nil} offsets from the remaining elements:
5325 Use the first offset that doesn't evaluate to @code{nil}. Subsequent
5326 elements of the list don't get evaluated.
5328 Use the minimum of all the offsets. All must be either relative or
5329 absolute - they can't be mixed.
5331 Use the maximum of all the offsets. All must be either relative or
5332 absolute - they can't be mixed.
5334 Add all the evaluated offsets together. Exactly one of them may be
5335 absolute, in which case the result is absolute. Any relative offsets
5336 that preceded the absolute one in the list will be ignored in that case.
5339 As a compatibility measure, if the first element is none of the above
5340 then it too will be taken as an offset specification and the whole list
5341 will be combined according to the method @code{first}.
5344 @vindex c-strict-syntax-p
5345 @vindex strict-syntax-p (c-)
5346 If an offset specification evaluates to @code{nil}, then a relative
5347 offset of 0 (zero) is used@footnote{There is however a variable
5348 @code{c-strict-syntax-p} that when set to non-@code{nil} will cause an
5349 error to be signaled in that case. It's now considered obsolete since
5350 it doesn't work well with some of the alignment functions that return
5351 @code{nil} instead of zero. You should therefore leave
5352 @code{c-strict-syntax-p} set to @code{nil}.}.
5354 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5355 @node Interactive Customization, Line-Up Functions, c-offsets-alist, Customizing Indentation
5356 @comment node-name, next, previous, up
5357 @section Interactive Customization
5358 @cindex customization, interactive
5359 @cindex interactive customization
5360 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5362 As an example of how to customize indentation, let's change the
5363 style of this example@footnote{In this and subsequent examples, the
5364 original code is formatted using the @samp{gnu} style unless otherwise
5365 indicated. @xref{Styles}.}:
5369 1: int add( int val, int incr, int doit )
5373 5: return( val + incr );
5385 1: int add( int val, int incr, int doit )
5389 5: return( val + incr );
5396 In other words, we want to change the indentation of braces that open a
5397 block following a condition so that the braces line up under the
5398 conditional, instead of being indented. Notice that the construct we
5399 want to change starts on line 4. To change the indentation of a line,
5400 we need to see which syntactic symbols affect the offset calculations
5401 for that line. Hitting @kbd{C-c C-s} on line 4 yields:
5404 ((substatement-open 44))
5408 so we know that to change the offset of the open brace, we need to
5409 change the indentation for the @code{substatement-open} syntactic
5412 To do this interactively, just hit @kbd{C-c C-o}. This prompts
5413 you for the syntactic symbol to change, providing a reasonable default.
5414 In this case, the default is @code{substatement-open}, which is just the
5415 syntactic symbol we want to change!
5417 After you hit return, @ccmode{} will then prompt you for the new
5418 offset value, with the old value as the default. The default in this
5419 case is @samp{+}, but we want no extra indentation so enter
5420 @samp{0} and @kbd{RET}. This will associate the offset 0 with the
5421 syntactic symbol @code{substatement-open}.
5423 To check your changes quickly, just hit @kbd{C-c C-q}
5424 (@code{c-indent-defun}) to reindent the entire function. The example
5425 should now look like:
5429 1: int add( int val, int incr, int doit )
5433 5: return( val + incr );
5440 Notice how just changing the open brace offset on line 4 is all we
5441 needed to do. Since the other affected lines are indented relative to
5442 line 4, they are automatically indented the way you'd expect. For more
5443 complicated examples, this might not always work. The general approach
5444 to take is to always start adjusting offsets for lines higher up in the
5445 file, then reindent and see if any following lines need further
5448 @c Move this bit to "Styles" (2005/10/7)
5449 @deffn Command c-set-offset symbol offset
5450 @findex set-offset (c-)
5452 This is the command bound to @kbd{C-c C-o}. It provides a convenient
5453 way to set offsets on @code{c-offsets-alist} both interactively (see
5454 the example above) and from your mode hook.
5456 It takes two arguments when used programmatically: @var{symbol} is the
5457 syntactic element symbol to change and @var{offset} is the new offset
5458 for that syntactic element.
5460 @c End of MOVE THIS BIT.
5462 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5463 @node Line-Up Functions, Custom Line-Up, Interactive Customization, Customizing Indentation
5464 @comment node-name, next, previous, up
5465 @section Line-Up Functions
5466 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5468 @cindex line-up function
5469 @cindex indentation function
5470 Often there are cases when a simple offset setting on a syntactic
5471 symbol isn't enough to get the desired indentation---for example, you
5472 might want to line up a closing parenthesis with the matching opening
5473 one rather than indenting relative to its ``anchor point''. @ccmode{}
5474 provides this flexibility with @dfn{line-up functions}.
5476 The way you associate a line-up function with a syntactic symbol is
5477 described in @ref{c-offsets-alist}. @ccmode{} comes with many
5478 predefined line-up functions for common situations. If none of these
5479 does what you want, you can write your own. @xref{Custom Line-Up}.
5480 Sometimes, it is easier to tweak the standard indentation by adding a
5481 function to @code{c-special-indent-hook} (@pxref{Other Indentation}).
5483 The line-up functions haven't been adapted for AWK buffers or tested
5484 with them. Some of them might work serendipitously. There shouldn't be
5485 any problems writing custom line-up functions for AWK mode.
5487 The calling convention for line-up functions is described fully in
5488 @ref{Custom Line-Up}. Roughly speaking, the return value is either an
5489 offset itself (such as @code{+} or @code{[0]}) or it's @code{nil},
5490 meaning ``this function is inappropriate in this case - try a
5491 different one''. @xref{c-offsets-alist}.
5493 The subsections below describe all the standard line-up functions,
5494 categorized by the sort of token the lining-up centers around. For
5495 each of these functions there is a ``works with'' list that indicates
5496 which syntactic symbols the function is intended to be used with.
5499 @emph{Works with:@ }
5508 @macro sssTBasicOffset
5509 <--> @i{c-basic-offset}@c
5512 @macro sssTsssTBasicOffset
5513 <--><--> @i{c-basic-offset}@c
5520 @c The TeX backend seems to insert extra spaces around the argument. :P
5529 * Brace/Paren Line-Up::
5531 * Operator Line-Up::
5536 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5537 @node Brace/Paren Line-Up, List Line-Up, Line-Up Functions, Line-Up Functions
5538 @comment node-name, next, previous, up
5539 @subsection Brace and Parenthesis Line-Up Functions
5540 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5542 The line-up functions here calculate the indentation for braces,
5543 parentheses and statements within brace blocks.
5545 @defun c-lineup-close-paren
5546 @findex lineup-close-paren (c-)
5547 Line up the closing paren under its corresponding open paren if the
5548 open paren is followed by code. If the open paren ends its line, no
5549 indentation is added. E.g:
5555 ) @hereFn{c-lineup-close-paren}
5566 ) @hereFn{c-lineup-close-paren}
5570 As a special case, if a brace block is opened at the same line as the
5571 open parenthesis of the argument list, the indentation is
5572 @code{c-basic-offset} instead of the open paren column. See
5573 @code{c-lineup-arglist} for further discussion of this ``DWIM'' measure.
5575 @workswith All @code{*-close} symbols.
5578 @comment ------------------------------------------------------------
5580 @anchor{c-lineup-arglist-close-under-paren}
5581 @defun c-lineup-arglist-close-under-paren
5582 @findex lineup-arglist-close-under-paren (c-)
5583 Set your @code{arglist-close} syntactic symbol to this line-up function
5584 so that parentheses that close argument lists will line up under the
5585 parenthesis that opened the argument list. It can also be used with
5586 @code{arglist-cont} and @code{arglist-cont-nonempty} to line up all
5587 lines inside a parenthesis under the open paren.
5589 As a special case, if a brace block is opened at the same line as the
5590 open parenthesis of the argument list, the indentation is
5591 @code{c-basic-offset} only. See @code{c-lineup-arglist} for further
5592 discussion of this ``DWIM'' measure.
5594 @workswith Almost all symbols, but are typically most useful on
5595 @code{arglist-close}, @code{brace-list-close}, @code{arglist-cont} and
5596 @code{arglist-cont-nonempty}.
5599 @comment ------------------------------------------------------------
5601 @defun c-indent-one-line-block
5602 @findex indent-one-line-block (c-)
5603 Indent a one line block @code{c-basic-offset} extra. E.g:
5608 @{m+=n; n=0;@} @hereFn{c-indent-one-line-block}
5619 @{ @hereFn{c-indent-one-line-block}
5625 The block may be surrounded by any kind of parenthesis characters.
5626 @code{nil} is returned if the line doesn't start with a one line block,
5627 which makes the function usable in list expressions.
5629 @workswith Almost all syntactic symbols, but most useful on the
5630 @code{-open} symbols.
5633 @comment ------------------------------------------------------------
5635 @defun c-indent-multi-line-block
5636 @findex indent-multi-line-block (c-)
5637 Indent a multiline block @code{c-basic-offset} extra. E.g:
5643 @{17@}, @hereFn{c-indent-multi-line-block}
5654 @{ @hereFn{c-indent-multi-line-block}
5661 The block may be surrounded by any kind of parenthesis characters.
5662 @code{nil} is returned if the line doesn't start with a multiline
5663 block, which makes the function usable in list expressions.
5665 @workswith Almost all syntactic symbols, but most useful on the
5666 @code{-open} symbols.
5669 @comment ------------------------------------------------------------
5671 @defun c-lineup-runin-statements
5672 @findex lineup-runin-statements (c-)
5673 Line up statements for coding standards which place the first statement
5674 in a block on the same line as the block opening brace@footnote{Run-in
5675 style doesn't really work too well. You might need to write your own
5676 custom line-up functions to better support this style.}. E.g:
5682 return 0; @hereFn{c-lineup-runin-statements}
5687 If there is no statement after the opening brace to align with,
5688 @code{nil} is returned. This makes the function usable in list
5691 @workswith The @code{statement} syntactic symbol.
5694 @comment ------------------------------------------------------------
5696 @defun c-lineup-inexpr-block
5697 @findex lineup-inexpr-block (c-)
5698 This can be used with the in-expression block symbols to indent the
5699 whole block to the column where the construct is started. E.g. for Java
5700 anonymous classes, this lines up the class under the @samp{new} keyword,
5701 and in Pike it lines up the lambda function body under the @samp{lambda}
5702 keyword. Returns @code{nil} if the block isn't part of such a
5705 @workswith @code{inlambda}, @code{inexpr-statement},
5706 @code{inexpr-class}.
5709 @comment ------------------------------------------------------------
5711 @defun c-lineup-after-whitesmith-blocks
5712 @findex lineup-after-whitesmith-blocks (c-)
5713 Compensate for Whitesmith style indentation of blocks. Due to the way
5714 @ccmode{} calculates anchor positions for normal lines inside blocks,
5715 this function is necessary for those lines to get correct Whitesmith
5716 style indentation. Consider the following examples:
5723 x; @hereFn{c-lineup-after-whitesmith-blocks}
5734 x; @hereFn{c-lineup-after-whitesmith-blocks}
5738 The fact that the line with @code{x} is preceded by a Whitesmith style
5739 indented block in the latter case and not the first should not affect
5740 its indentation. But since CC Mode in cases like this uses the
5741 indentation of the preceding statement as anchor position, the @code{x}
5742 would in the second case be indented too much if the offset for
5743 @code{statement} was set simply to zero.
5745 This lineup function corrects for this situation by detecting if the
5746 anchor position is at an open paren character. In that case, it instead
5747 indents relative to the surrounding block just like
5748 @code{c-lineup-whitesmith-in-block}.
5750 @workswith @code{brace-list-entry}, @code{brace-entry-open},
5751 @code{statement}, @code{arglist-cont}.
5754 @comment ------------------------------------------------------------
5756 @defun c-lineup-whitesmith-in-block
5757 @findex lineup-whitesmith-in-block (c-)
5758 Line up lines inside a block in Whitesmith style. It's done in a way
5759 that works both when the opening brace hangs and when it doesn't. E.g:
5765 foo; @hereFn{c-lineup-whitesmith-in-block}
5776 foo; @hereFn{c-lineup-whitesmith-in-block}
5782 In the first case the indentation is kept unchanged, in the second
5783 @code{c-basic-offset} is added.
5785 @workswith @code{defun-close}, @code{defun-block-intro},
5786 @code{inline-close}, @code{block-close}, @code{brace-list-close},
5787 @code{brace-list-intro}, @code{statement-block-intro},
5788 @code{arglist-intro}, @code{arglist-cont-nonempty},
5789 @code{arglist-close}, and all @code{in*} symbols, e.g. @code{inclass}
5790 and @code{inextern-lang}.
5793 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5794 @node List Line-Up, Operator Line-Up, Brace/Paren Line-Up, Line-Up Functions
5795 @comment node-name, next, previous, up
5796 @subsection List Line-Up Functions
5797 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5799 The line-up functions here calculate the indentation for lines which
5800 form lists of items, usually separated by commas.
5802 The function @ref{c-lineup-arglist-close-under-paren}, which is mainly
5803 for indenting a close parenthesis, is also useful for the lines
5804 contained within parentheses.
5806 @defun c-lineup-arglist
5807 @findex lineup-arglist (c-)
5808 Line up the current argument line under the first argument.
5810 As a special case, if an argument on the same line as the open
5811 parenthesis starts with a brace block opener, the indentation is
5812 @code{c-basic-offset} only. This is intended as a ``DWIM'' measure in
5813 cases like macros that contain statement blocks, e.g:
5817 A_VERY_LONG_MACRO_NAME (@{
5818 some (code, with + long, lines * in[it]);
5824 This is motivated partly because it's more in line with how code
5825 blocks are handled, and partly since it approximates the behavior of
5826 earlier CC Mode versions, which due to inaccurate analysis tended to
5827 indent such cases this way.
5829 @workswith @code{arglist-cont-nonempty}, @code{arglist-close}.
5832 @comment ------------------------------------------------------------
5834 @defun c-lineup-arglist-intro-after-paren
5835 @findex lineup-arglist-intro-after-paren (c-)
5836 Line up a line to just after the open paren of the surrounding paren or
5839 @workswith @code{defun-block-intro}, @code{brace-list-intro},
5840 @code{statement-block-intro}, @code{statement-case-intro},
5841 @code{arglist-intro}.
5844 @comment ------------------------------------------------------------
5846 @defun c-lineup-multi-inher
5847 @findex lineup-multi-inher (c-)
5848 Line up the classes in C++ multiple inheritance clauses and member
5849 initializers under each other. E.g:
5853 Foo::Foo (int a, int b):
5855 Bar (b) @hereFn{c-lineup-multi-inher}
5866 public Bar @hereFn{c-lineup-multi-inher}
5875 Foo::Foo (int a, int b)
5877 , Bar (b) @hereFn{c-lineup-multi-inher}
5881 @workswith @code{inher-cont}, @code{member-init-cont}.
5884 @comment ------------------------------------------------------------
5886 @defun c-lineup-java-inher
5887 @findex lineup-java-inher (c-)
5888 Line up Java implements and extends declarations. If class names
5889 follow on the same line as the @samp{implements}/@samp{extends}
5890 keyword, they are lined up under each other. Otherwise, they are
5891 indented by adding @code{c-basic-offset} to the column of the keyword.
5898 Bar @hereFn{c-lineup-java-inher}
5910 Bar @hereFn{c-lineup-java-inher}
5914 @workswith @code{inher-cont}.
5917 @comment ------------------------------------------------------------
5919 @defun c-lineup-java-throws
5920 @findex lineup-java-throws (c-)
5921 Line up Java throws declarations. If exception names follow on the
5922 same line as the throws keyword, they are lined up under each other.
5923 Otherwise, they are indented by adding @code{c-basic-offset} to the
5924 column of the @samp{throws} keyword. The @samp{throws} keyword itself
5925 is also indented by @code{c-basic-offset} from the function declaration
5926 start if it doesn't hang. E.g:
5931 throws @hereFn{c-lineup-java-throws}
5932 Bar @hereFn{c-lineup-java-throws}
5933 @sssTsssTBasicOffset{}
5942 int foo() throws Cyphr,
5943 Bar, @hereFn{c-lineup-java-throws}
5944 Vlod @hereFn{c-lineup-java-throws}
5948 @workswith @code{func-decl-cont}.
5951 @comment ------------------------------------------------------------
5953 @defun c-lineup-template-args
5954 @findex lineup-template-args (c-)
5955 Line up the arguments of a template argument list under each other, but
5956 only in the case where the first argument is on the same line as the
5959 To allow this function to be used in a list expression, @code{nil} is
5960 returned if there's no template argument on the first line.
5962 @workswith @code{template-args-cont}.
5965 @comment ------------------------------------------------------------
5967 @defun c-lineup-ObjC-method-call
5968 @findex lineup-ObjC-method-call (c-)
5969 For Objective-C code, line up selector args as Emacs Lisp mode does
5970 with function args: go to the position right after the message receiver,
5971 and if you are at the end of the line, indent the current line
5972 c-basic-offset columns from the opening bracket; otherwise you are
5973 looking at the first character of the first method call argument, so
5974 lineup the current line with it.
5976 @workswith @code{objc-method-call-cont}.
5979 @comment ------------------------------------------------------------
5981 @defun c-lineup-ObjC-method-args
5982 @findex lineup-ObjC-method-args (c-)
5983 For Objective-C code, line up the colons that separate args. The colon
5984 on the current line is aligned with the one on the first line.
5986 @workswith @code{objc-method-args-cont}.
5989 @comment ------------------------------------------------------------
5991 @defun c-lineup-ObjC-method-args-2
5992 @findex lineup-ObjC-method-args-2 (c-)
5993 Similar to @code{c-lineup-ObjC-method-args} but lines up the colon on
5994 the current line with the colon on the previous line.
5996 @workswith @code{objc-method-args-cont}.
5999 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6000 @node Operator Line-Up, Comment Line-Up, List Line-Up, Line-Up Functions
6001 @comment node-name, next, previous, up
6002 @subsection Operator Line-Up Functions
6003 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6005 The line-up functions here calculate the indentation for lines which
6006 start with an operator, by lining it up with something on the previous
6009 @defun c-lineup-argcont
6010 @findex lineup-argcont (c-)
6011 Line up a continued argument. E.g:
6015 foo (xyz, aaa + bbb + ccc
6016 + ddd + eee + fff); @hereFn{c-lineup-argcont}
6020 Only continuation lines like this are touched, @code{nil} is returned on
6021 lines which are the start of an argument.
6023 Within a gcc @code{asm} block, @code{:} is recognized as an argument
6024 separator, but of course only between operand specifications, not in the
6025 expressions for the operands.
6027 @workswith @code{arglist-cont}, @code{arglist-cont-nonempty}.
6030 @comment ------------------------------------------------------------
6032 @defun c-lineup-arglist-operators
6033 @findex lineup-arglist-operators (c-)
6034 Line up lines starting with an infix operator under the open paren.
6035 Return @code{nil} on lines that don't start with an operator, to leave
6036 those cases to other line-up functions. Example:
6041 || at_limit (x, @hereFn{c-lineup-arglist-operators}
6042 list) @hereFn{c-lineup-arglist-operators@r{ returns nil}}
6047 Since this function doesn't do anything for lines without an infix
6048 operator you typically want to use it together with some other lineup
6049 settings, e.g. as follows (the @code{arglist-close} setting is just a
6050 suggestion to get a consistent style):
6053 (c-set-offset 'arglist-cont
6054 '(c-lineup-arglist-operators 0))
6055 (c-set-offset 'arglist-cont-nonempty
6056 '(c-lineup-arglist-operators c-lineup-arglist))
6057 (c-set-offset 'arglist-close
6058 '(c-lineup-arglist-close-under-paren))
6061 @workswith @code{arglist-cont}, @code{arglist-cont-nonempty}.
6064 @comment ------------------------------------------------------------
6066 @defun c-lineup-assignments
6067 @findex lineup-assignments (c-)
6068 Line up the current line after the assignment operator on the first line
6069 in the statement. If there isn't any, return nil to allow stacking with
6070 other line-up functions. If the current line contains an assignment
6071 operator too, try to align it with the first one.
6073 @workswith @code{topmost-intro-cont}, @code{statement-cont},
6074 @code{arglist-cont}, @code{arglist-cont-nonempty}.
6078 @comment ------------------------------------------------------------
6080 @defun c-lineup-math
6081 @findex lineup-math (c-)
6082 Like @code{c-lineup-assignments} but indent with @code{c-basic-offset}
6083 if no assignment operator was found on the first line. I.e. this
6084 function is the same as specifying a list @code{(c-lineup-assignments
6085 +)}. It's provided for compatibility with old configurations.
6087 @workswith @code{topmost-intro-cont}, @code{statement-cont},
6088 @code{arglist-cont}, @code{arglist-cont-nonempty}.
6091 @comment ------------------------------------------------------------
6093 @defun c-lineup-cascaded-calls
6094 @findex lineup-cascaded-calls (c-)
6095 Line up ``cascaded calls'' under each other. If the line begins with
6096 @code{->} or @code{.} and the preceding line ends with one or more
6097 function calls preceded by the same token, then the arrow is lined up
6098 with the first of those tokens. E.g:
6102 r = proc->add(17)->add(18)
6103 ->add(19) + @hereFn{c-lineup-cascaded-calls}
6104 offset; @hereFn{c-lineup-cascaded-calls@r{ (inactive)}}
6108 In any other situation @code{nil} is returned to allow use in list
6111 @workswith @code{topmost-intro-cont}, @code{statement-cont},
6112 @code{arglist-cont}, @code{arglist-cont-nonempty}.
6115 @comment ------------------------------------------------------------
6117 @defun c-lineup-streamop
6118 @findex lineup-streamop (c-)
6119 Line up C++ stream operators (i.e. @samp{<<} and @samp{>>}).
6121 @workswith @code{stream-op}.
6124 @comment ------------------------------------------------------------
6126 @defun c-lineup-string-cont
6127 @findex lineup-string-cont (c-)
6128 Line up a continued string under the one it continues. A continued
6129 string in this sense is where a string literal follows directly after
6134 result = prefix + "A message "
6135 "string."; @hereFn{c-lineup-string-cont}
6139 @code{nil} is returned in other situations, to allow stacking with other
6142 @workswith @code{topmost-intro-cont}, @code{statement-cont},
6143 @code{arglist-cont}, @code{arglist-cont-nonempty}.
6147 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6148 @node Comment Line-Up, Misc Line-Up, Operator Line-Up, Line-Up Functions
6149 @comment node-name, next, previous, up
6150 @subsection Comment Line-Up Functions
6151 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6153 The lineup functions here calculate the indentation for several types
6154 of comment structure.
6156 @defun c-lineup-C-comments
6157 @findex lineup-C-comments (c-)
6158 Line up C block comment continuation lines. Various heuristics are used
6159 to handle most of the common comment styles. Some examples:
6172 text ** text ** text
6179 /**************************************************
6181 *************************************************/
6185 @vindex comment-start-skip
6188 /**************************************************
6189 Free form text comments:
6190 In comments with a long delimiter line at the
6191 start, the indentation is kept unchanged for lines
6192 that start with an empty comment line prefix. The
6193 delimiter line is whatever matches the
6194 @code{comment-start-skip} regexp.
6195 **************************************************/
6199 The style variable @code{c-comment-prefix-regexp} is used to recognize
6200 the comment line prefix, e.g. the @samp{*} that usually starts every
6201 line inside a comment.
6203 @workswith The @code{c} syntactic symbol.
6206 @comment ------------------------------------------------------------
6208 @defun c-lineup-comment
6209 @findex lineup-comment (c-)
6210 Line up a comment-only line according to the style variable
6211 @code{c-comment-only-line-offset}. If the comment is lined up with a
6212 comment starter on the previous line, that alignment is preserved.
6214 @defopt c-comment-only-line-offset
6215 @vindex comment-only-line-offset (c-)
6216 This style variable specifies the extra offset for the line. It can
6217 contain an integer or a cons cell of the form
6220 (@r{@var{non-anchored-offset}} . @r{@var{anchored-offset}})
6224 where @var{non-anchored-offset} is the amount of offset given to
6225 non-column-zero anchored lines, and @var{anchored-offset} is the amount
6226 of offset to give column-zero anchored lines. Just an integer as value
6227 is equivalent to @code{(@r{@var{value}} . -1000)}.
6230 @workswith @code{comment-intro}.
6233 @comment ------------------------------------------------------------
6235 @defun c-lineup-knr-region-comment
6236 @findex lineup-knr-region-comment (c-)
6237 Line up a comment in the ``K&R region'' with the declaration. That is
6238 the region between the function or class header and the beginning of the
6244 /* Called at startup. */ @hereFn{c-lineup-knr-region-comment}
6251 Return @code{nil} if called in any other situation, to be useful in list
6254 @workswith @code{comment-intro}.
6257 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6258 @node Misc Line-Up, , Comment Line-Up, Line-Up Functions
6259 @comment node-name, next, previous, up
6260 @subsection Miscellaneous Line-Up Functions
6261 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6263 The line-up functions here are the odds and ends which didn't fit into
6264 any earlier category.
6266 @defun c-lineup-dont-change
6267 @findex lineup-dont-change (c-)
6268 This lineup function makes the line stay at whatever indentation it
6269 already has; think of it as an identity function for lineups.
6271 @workswith Any syntactic symbol.
6274 @comment ------------------------------------------------------------
6276 @defun c-lineup-cpp-define
6277 @findex lineup-cpp-define (c-)
6278 Line up macro continuation lines according to the indentation of the
6279 construct preceding the macro. E.g:
6283 const char msg[] = @hereFn{@r{The beginning of the preceding construct.}}
6287 do @{ \ @hereFn{c-lineup-cpp-define}
6299 if (!running) @hereFn{@r{The beginning of the preceding construct.}}
6300 error(\"Not running!\");
6303 do @{ \ @hereFn{c-lineup-cpp-define}
6309 If @code{c-syntactic-indentation-in-macros} is non-@code{nil}, the
6310 function returns the relative indentation to the macro start line to
6311 allow accumulation with other offsets. E.g. in the following cases,
6312 @code{cpp-define-intro} is combined with the
6313 @code{statement-block-intro} that comes from the @samp{do @{} that hangs
6314 on the @samp{#define} line:
6321 #define X(A, B) do @{ \
6322 printf (A, B); \ @hereFn{c-lineup-cpp-define}
6324 @} while (0) @hereFn{c-lineup-cpp-define}
6335 error(\"Not running!\");
6337 #define X(A, B) do @{ \
6338 printf (A, B); \ @hereFn{c-lineup-cpp-define}
6340 @} while (0) @hereFn{c-lineup-cpp-define}
6344 The relative indentation returned by @code{c-lineup-cpp-define} is zero
6345 and two, respectively, on the two lines in each of these examples. They
6346 are then added to the two column indentation that
6347 @code{statement-block-intro} gives in both cases here.
6349 If the relative indentation is zero, then @code{nil} is returned
6350 instead. That is useful in a list expression to specify the default
6351 indentation on the top level.
6353 If @code{c-syntactic-indentation-in-macros} is @code{nil} then this
6354 function keeps the current indentation, except for empty lines (ignoring
6355 the ending backslash) where it takes the indentation from the closest
6356 preceding nonempty line in the macro. If there's no such line in the
6357 macro then the indentation is taken from the construct preceding it, as
6360 @workswith @code{cpp-define-intro}.
6363 @comment ------------------------------------------------------------
6365 @defun c-lineup-gcc-asm-reg
6366 @findex lineup-gcc-asm-reg (c-)
6367 Line up a gcc asm register under one on a previous line.
6380 The @samp{x} line is aligned to the text after the @samp{:} on the
6381 @samp{w} line, and similarly @samp{z} under @samp{y}.
6383 This is done only in an @samp{asm} or @samp{__asm__} block, and only to
6384 those lines mentioned. Anywhere else @code{nil} is returned. The usual
6385 arrangement is to have this routine as an extra feature at the start of
6386 arglist lineups, e.g.
6389 (c-lineup-gcc-asm-reg c-lineup-arglist)
6392 @workswith @code{arglist-cont}, @code{arglist-cont-nonempty}.
6395 @comment ------------------------------------------------------------
6397 @defun c-lineup-topmost-intro-cont
6398 @findex lineup-topmost-intro-cont (c-)
6399 Line up declaration continuation lines zero or one indentation
6400 step@footnote{This function is mainly provided to mimic the behavior of
6401 CC Mode 5.28 and earlier where this case wasn't handled consistently so
6402 that those lines could be analyzed as either topmost-intro-cont or
6403 statement-cont. It's used for @code{topmost-intro-cont} by default, but
6404 you might consider using @code{+} instead.}. For lines preceding a
6405 definition, zero is used. For other lines, @code{c-basic-offset} is
6406 added to the indentation. E.g:
6411 neg (int i) @hereFn{c-lineup-topmost-intro-cont}
6424 larch @hereFn{c-lineup-topmost-intro-cont}
6428 the_larch, @hereFn{c-lineup-topmost-intro-cont}
6429 another_larch; @hereFn{c-lineup-topmost-intro-cont}
6440 the_larch, @hereFn{c-lineup-topmost-intro-cont}
6441 another_larch; @hereFn{c-lineup-topmost-intro-cont}
6445 @workswith @code{topmost-intro-cont}.
6448 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6449 @node Custom Line-Up, Other Indentation, Line-Up Functions, Customizing Indentation
6450 @comment node-name, next, previous, up
6451 @section Custom Line-Up Functions
6452 @cindex customization, indentation functions
6453 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6455 The most flexible way to customize indentation is by writing custom
6456 line-up functions, and associating them with specific syntactic
6457 symbols (@pxref{c-offsets-alist}). Depending on the effect you want,
6458 it might be better to write a @code{c-special-indent-hook} function
6459 rather than a line-up function (@pxref{Other Indentation}).
6461 @ccmode{} comes with an extensive set of predefined line-up functions,
6462 not all of which are used by the default styles. So there's a good
6463 chance the function you want already exists. @xref{Line-Up
6464 Functions}, for a list of them. If you write your own line-up
6465 function, it's probably a good idea to start working from one of these
6466 predefined functions, which can be found in the file
6467 @file{cc-align.el}. If you have written a line-up function that you
6468 think is generally useful, you're very welcome to contribute it;
6469 please contact @email{bug-cc-mode@@gnu.org}.
6471 Line-up functions are passed a single argument, the syntactic
6472 element (see below). The return value is a @code{c-offsets-alist}
6473 offset specification: for example, an integer, a symbol such as
6474 @code{+}, a vector, @code{nil}@footnote{Returning @code{nil} is useful
6475 when the offset specification for a syntactic element is a list
6476 containing the line-up function (@pxref{c-offsets-alist}).}, or even
6477 another line-up function. Full details of these are in
6478 @ref{c-offsets-alist}.
6480 Line-up functions must not move point or change the content of the
6481 buffer (except temporarily). They are however allowed to do
6482 @dfn{hidden buffer changes}, i.e. setting text properties for caching
6483 purposes etc. Buffer undo recording is disabled while they run.
6485 The syntactic element passed as the parameter to a line-up function is
6486 a cons cell of the form
6489 (@r{@var{syntactic-symbol}} . @r{@var{anchor-position}})
6493 @c FIXME!!! The following sentence might be better omitted, since the
6494 @c information is in the cross reference "Syntactic Analysis". 2005/10/2.
6495 where @var{syntactic-symbol} is the symbol that the function was
6496 called for, and @var{anchor-position} is the anchor position (if any)
6497 for the construct that triggered the syntactic symbol
6498 (@pxref{Syntactic Analysis}). This cons cell is how the syntactic
6499 element of a line used to be represented in @ccmode{} 5.28 and
6500 earlier. Line-up functions are still passed this cons cell, so as to
6501 preserve compatibility with older configurations. In the future, we
6502 may decide to convert to using the full list format---you can prepare
6503 your setup for this by using the access functions
6504 (@code{c-langelem-sym}, etc.) described below.
6506 @vindex c-syntactic-element
6507 @vindex syntactic-element (c-)
6508 @vindex c-syntactic-context
6509 @vindex syntactic-context (c-)
6510 Some syntactic symbols, e.g. @code{arglist-cont-nonempty}, have more
6511 info in the syntactic element - typically other positions that can be
6512 interesting besides the anchor position. That info can't be accessed
6513 through the passed argument, which is a cons cell. Instead, you can
6514 get this information from the variable @code{c-syntactic-element},
6515 which is dynamically bound to the complete syntactic element. The
6516 variable @code{c-syntactic-context} might also be useful - it gets
6517 dynamically bound to the complete syntactic context. @xref{Custom
6520 @ccmode{} provides a few functions to access parts of syntactic
6521 elements in a more abstract way. Besides making the code easier to
6522 read, they also hide the difference between the old cons cell form
6523 used in the line-up function argument and the new list form used in
6524 @code{c-syntactic-element} and everywhere else. The functions are:
6526 @defun c-langelem-sym langelem
6527 @findex langelem-sym (c-)
6528 Return the syntactic symbol in @var{langelem}.
6531 @defun c-langelem-pos langelem
6532 @findex langelem-pos (c-)
6533 Return the anchor position in @var{langelem}, or nil if there is none.
6536 @defun c-langelem-col langelem &optional preserve-point
6537 @findex langelem-col (c-)
6538 Return the column of the anchor position in @var{langelem}. Also move
6539 the point to that position unless @var{preserve-point} is
6543 @defun c-langelem-2nd-pos langelem
6544 @findex langelem-2nd-pos (c-)
6545 Return the secondary position in @var{langelem}, or @code{nil} if there
6548 Note that the return value of this function is always @code{nil} if
6549 @var{langelem} is in the old cons cell form. Thus this function is
6550 only meaningful when used on syntactic elements taken from
6551 @code{c-syntactic-element} or @code{c-syntactic-context}.
6554 Custom line-up functions can be as simple or as complex as you like, and
6555 any syntactic symbol that appears in @code{c-offsets-alist} can have a
6556 custom line-up function associated with it.
6558 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6559 @node Other Indentation, , Custom Line-Up, Customizing Indentation
6560 @comment node-name, next, previous, up
6561 @section Other Special Indentations
6562 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6564 Here are the remaining odds and ends regarding indentation:
6566 @defopt c-label-minimum-indentation
6567 @vindex label-minimum-indentation (c-)
6568 In @samp{gnu} style (@pxref{Built-in Styles}), a minimum indentation is
6569 imposed on lines inside code blocks. This minimum indentation is
6570 controlled by this style variable. The default value is 1.
6572 @findex c-gnu-impose-minimum
6573 @findex gnu-impose-minimum (c-)
6574 It's the function @code{c-gnu-impose-minimum} that enforces this minimum
6575 indentation. It must be present on @code{c-special-indent-hook} to
6579 @defopt c-special-indent-hook
6580 @vindex special-indent-hook (c-)
6581 This style variable is a standard hook variable that is called after
6582 every line is indented by @ccmode{}. It is called only if
6583 @code{c-syntactic-indentation} is non-@code{nil} (which it is by
6584 default (@pxref{Indentation Engine Basics})). You can put a function
6585 on this hook to do any special indentation or ad hoc line adjustments
6586 your style dictates, such as adding extra indentation to constructors
6587 or destructor declarations in a class definition, etc. Sometimes it
6588 is better to write a custom Line-up Function instead (@pxref{Custom
6591 When the indentation engine calls this hook, the variable
6592 @code{c-syntactic-context} is bound to the current syntactic context
6593 (i.e. what you would get by typing @kbd{C-c C-s} on the source line.
6594 @xref{Custom Braces}.). Note that you should not change point or mark
6595 inside a @code{c-special-indent-hook} function, i.e. you'll probably
6596 want to wrap your function in a @code{save-excursion}@footnote{The
6597 numerical value returned by @code{point} will change if you change the
6598 indentation of the line within a @code{save-excursion} form, but point
6599 itself will still be over the same piece of text.}.
6601 Setting @code{c-special-indent-hook} in style definitions is handled
6602 slightly differently from other variables---A style can only add
6603 functions to this hook, not remove them. @xref{Style Variables}.
6607 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6608 @node Custom Macros, Odds and Ends, Customizing Indentation, Top
6609 @comment node-name, next, previous, up
6610 @chapter Customizing Macros
6612 @cindex preprocessor directives
6613 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6615 Normally, the lines in a multi-line macro are indented relative to
6616 each other as though they were code. You can suppress this behavior
6617 by setting the following user option:
6619 @defopt c-syntactic-indentation-in-macros
6620 @vindex syntactic-indentation-in-macros (c-)
6621 Enable syntactic analysis inside macros, which is the default. If this
6622 is @code{nil}, all lines inside macro definitions are analyzed as
6623 @code{cpp-macro-cont}.
6626 @ccmode{} provides some tools to help keep the line continuation
6627 backslashes in macros neat and tidy. Their precise action is
6628 customized with these variables:
6630 @defopt c-backslash-column
6631 @vindex backslash-column (c-)
6632 @defoptx c-backslash-max-column
6633 @vindex backslash-max-column (c-)
6634 These variables control the alignment columns for line continuation
6635 backslashes in multiline macros. They are used by the functions that
6636 automatically insert or align such backslashes,
6637 e.g. @code{c-backslash-region} and @code{c-context-line-break}.
6639 @code{c-backslash-column} specifies the minimum column for the
6640 backslashes. If any line in the macro goes past this column, then the
6641 next tab stop (i.e. next multiple of @code{tab-width}) in that line is
6642 used as the alignment column for all the backslashes, so that they
6643 remain in a single column. However, if any lines go past
6644 @code{c-backslash-max-column} then the backslashes in the rest of the
6645 macro will be kept at that column, so that the lines which are too
6646 long ``stick out'' instead.
6648 Don't ever set these variables to @code{nil}. If you want to disable
6649 the automatic alignment of backslashes, use
6650 @code{c-auto-align-backslashes}.
6653 @defopt c-auto-align-backslashes
6654 @vindex auto-align-backslashes (c-)
6655 Align automatically inserted line continuation backslashes if
6656 non-@code{nil}. When line continuation backslashes are inserted
6657 automatically for line breaks in multiline macros, e.g. by
6658 @code{c-context-line-break}, they are aligned with the other
6659 backslashes in the same macro if this flag is set.
6661 If @code{c-auto-align-backslashes} is @code{nil}, automatically
6662 inserted backslashes are preceded by a single space, and backslashes
6663 get aligned only when you explicitly invoke the command
6664 @code{c-backslash-region} (@kbd{C-c C-\}).
6667 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6668 @node Odds and Ends, Sample .emacs File, Custom Macros, Top
6669 @comment node-name, next, previous, up
6670 @chapter Odds and Ends
6671 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6673 The stuff that didn't fit in anywhere else is documented here.
6675 @defopt c-require-final-newline
6676 @vindex require-final-newline (c-)
6677 Controls whether a final newline is enforced when the file is saved.
6678 The value is an association list that for each language mode specifies
6679 the value to give to @code{require-final-newline} (@pxref{Saving
6680 Buffers,,, @lispref{}, @lispreftitle{}}) at mode initialization. If a
6681 language isn't present on the association list, CC Mode won't touch
6682 @code{require-final-newline} in buffers for that language.
6684 The default is to set @code{require-final-newline} to @code{t} in the
6685 languages that mandate that source files should end with newlines.
6686 These are C, C++ and Objective-C.
6689 @defopt c-echo-syntactic-information-p
6690 @vindex echo-syntactic-information-p (c-)
6691 If non-@code{nil}, the syntactic analysis for the current line is shown
6692 in the echo area when it's indented (unless
6693 @code{c-syntactic-indentation} is @code{nil}). That's useful when
6694 finding out which syntactic symbols to modify to get the indentation you
6698 @defopt c-report-syntactic-errors
6699 @vindex report-syntactic-errors (c-)
6700 If non-@code{nil}, certain syntactic errors are reported with a ding and
6701 a message, for example when an @code{else} is indented for which there
6702 is no corresponding @code{if}.
6704 Note however that @ccmode{} doesn't make any special effort to check for
6705 syntactic errors; that's the job of the compiler. The reason it can
6706 report cases like the one above is that it can't find the correct
6707 anchoring position to indent the line in that case.
6711 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6712 @node Sample .emacs File, Performance Issues, Odds and Ends, Top
6713 @comment node-name, next, previous, up
6714 @appendix Sample .emacs File
6715 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6717 Here's a sample .emacs file fragment that might help you along the way.
6718 Just copy this region and paste it into your .emacs file. You might want
6719 to change some of the actual values.
6722 ;; Make a non-standard key binding. We can put this in
6723 ;; c-mode-base-map because c-mode-map, c++-mode-map, and so on,
6725 (defun my-c-initialization-hook ()
6726 (define-key c-mode-base-map "\C-m" 'c-context-line-break))
6727 (add-hook 'c-initialization-hook 'my-c-initialization-hook)
6729 ;; offset customizations not in my-c-style
6730 ;; This will take precedence over any setting of the syntactic symbol
6732 (setq c-offsets-alist '((member-init-intro . ++)))
6734 ;; Create my personal style.
6735 (defconst my-c-style
6736 '((c-tab-always-indent . t)
6737 (c-comment-only-line-offset . 4)
6738 (c-hanging-braces-alist . ((substatement-open after)
6740 (c-hanging-colons-alist . ((member-init-intro before)
6744 (access-label after)))
6745 (c-cleanup-list . (scope-operator
6748 (c-offsets-alist . ((arglist-close . c-lineup-arglist)
6749 (substatement-open . 0)
6752 (knr-argdecl-intro . -)))
6753 (c-echo-syntactic-information-p . t))
6754 "My C Programming Style")
6755 (c-add-style "PERSONAL" my-c-style)
6757 ;; Customizations for all modes in CC Mode.
6758 (defun my-c-mode-common-hook ()
6759 ;; set my personal style for the current buffer
6760 (c-set-style "PERSONAL")
6761 ;; other customizations
6763 ;; this will make sure spaces are used instead of tabs
6764 indent-tabs-mode nil)
6765 ;; we like auto-newline, but not hungry-delete
6766 (c-toggle-auto-newline 1))
6767 (add-hook 'c-mode-common-hook 'my-c-mode-common-hook)
6770 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6771 @node Performance Issues, Limitations and Known Bugs, Sample .emacs File, Top
6772 @comment node-name, next, previous, up
6773 @chapter Performance Issues
6775 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6777 @comment FIXME: (ACM, 2003/5/24). Check whether AWK needs mentioning here.
6779 C and its derivative languages are highly complex creatures. Often,
6780 ambiguous code situations arise that require @ccmode{} to scan large
6781 portions of the buffer to determine syntactic context. Such
6782 pathological code can cause @ccmode{} to perform fairly badly. This
6783 section gives some insight in how @ccmode{} operates, how that interacts
6784 with some coding styles, and what you can use to improve performance.
6786 The overall goal is that @ccmode{} shouldn't be overly slow (i.e. take
6787 more than a fraction of a second) in any interactive operation.
6788 I.e. it's tuned to limit the maximum response time in single operations,
6789 which is sometimes at the expense of batch-like operations like
6790 reindenting whole blocks. If you find that @ccmode{} gradually gets
6791 slower and slower in certain situations, perhaps as the file grows in
6792 size or as the macro or comment you're editing gets bigger, then chances
6793 are that something isn't working right. You should consider reporting
6794 it, unless it's something that's mentioned in this section.
6796 Because @ccmode{} has to scan the buffer backwards from the current
6797 insertion point, and because C's syntax is fairly difficult to parse in
6798 the backwards direction, @ccmode{} often tries to find the nearest
6799 position higher up in the buffer from which to begin a forward scan
6800 (it's typically an opening or closing parenthesis of some kind). The
6801 farther this position is from the current insertion point, the slower it
6804 @findex beginning-of-defun
6805 In earlier versions of @ccmode{}, we used to recommend putting the
6806 opening brace of a top-level construct@footnote{E.g. a function in C,
6807 or outermost class definition in C++ or Java.} into the leftmost
6808 column. Earlier still, this used to be a rigid Emacs constraint, as
6809 embodied in the @code{beginning-of-defun} function. @ccmode now
6810 caches syntactic information much better, so that the delay caused by
6811 searching for such a brace when it's not in column 0 is minimal,
6812 except perhaps when you've just moved a long way inside the file.
6814 @findex defun-prompt-regexp
6815 @vindex c-Java-defun-prompt-regexp
6816 @vindex Java-defun-prompt-regexp (c-)
6817 A special note about @code{defun-prompt-regexp} in Java mode: The common
6818 style is to hang the opening braces of functions and classes on the
6819 right side of the line, and that doesn't work well with the Emacs
6820 approach. @ccmode{} comes with a constant
6821 @code{c-Java-defun-prompt-regexp} which tries to define a regular
6822 expression usable for this style, but there are problems with it. In
6823 some cases it can cause @code{beginning-of-defun} to hang@footnote{This
6824 has been observed in Emacs 19.34 and XEmacs 19.15.}. For this reason,
6825 it is not used by default, but if you feel adventurous, you can set
6826 @code{defun-prompt-regexp} to it in your mode hook. In any event,
6827 setting and relying on @code{defun-prompt-regexp} will definitely slow
6828 things down because (X)Emacs will be doing regular expression searches a
6829 lot, so you'll probably be taking a hit either way!
6831 @ccmode{} maintains a cache of the opening parentheses of the blocks
6832 surrounding the point, and it adapts that cache as the point is moved
6833 around. That means that in bad cases it can take noticeable time to
6834 indent a line in a new surrounding, but after that it gets fast as long
6835 as the point isn't moved far off. The farther the point is moved, the
6836 less useful is the cache. Since editing typically is done in ``chunks''
6837 rather than on single lines far apart from each other, the cache
6838 typically gives good performance even when the code doesn't fit the
6839 Emacs approach to finding the defun starts.
6841 @vindex c-enable-xemacs-performance-kludge-p
6842 @vindex enable-xemacs-performance-kludge-p (c-)
6843 XEmacs users can set the variable
6844 @code{c-enable-xemacs-performance-kludge-p} to non-@code{nil}. This
6845 tells @ccmode{} to use XEmacs-specific built-in functions which, in some
6846 circumstances, can locate the top-most opening brace much more quickly than
6847 @code{beginning-of-defun}. Preliminary testing has shown that for
6848 styles where these braces are hung (e.g. most JDK-derived Java styles),
6849 this hack can improve performance of the core syntax parsing routines
6850 from 3 to 60 times. However, for styles which @emph{do} conform to
6851 Emacs' recommended style of putting top-level braces in column zero,
6852 this hack can degrade performance by about as much. Thus this variable
6853 is set to @code{nil} by default, since the Emacs-friendly styles should
6854 be more common (and encouraged!). Note that this variable has no effect
6855 in Emacs since the necessary built-in functions don't exist (in Emacs
6856 22.1 as of this writing in February 2007).
6858 Text properties are used to speed up skipping over syntactic whitespace,
6859 i.e. comments and preprocessor directives. Indenting a line after a
6860 huge macro definition can be slow the first time, but after that the
6861 text properties are in place and it should be fast (even after you've
6862 edited other parts of the file and then moved back).
6864 Font locking can be a CPU hog, especially the font locking done on
6865 decoration level 3 which tries to be very accurate. Note that that
6866 level is designed to be used with a font lock support mode that only
6867 fontifies the text that's actually shown, i.e. Lazy Lock or Just-in-time
6868 Lock mode, so make sure you use one of them. Fontification of a whole
6869 buffer with some thousand lines can often take over a minute. That is
6870 a known weakness; the idea is that it never should happen.
6872 The most effective way to speed up font locking is to reduce the
6873 decoration level to 2 by setting @code{font-lock-maximum-decoration}
6874 appropriately. That level is designed to be as pretty as possible
6875 without sacrificing performance. @xref{Font Locking Preliminaries}, for
6879 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6880 @node Limitations and Known Bugs, FAQ, Performance Issues, Top
6881 @comment node-name, next, previous, up
6882 @chapter Limitations and Known Bugs
6885 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6889 @ccmode{} doesn't support trigraphs. (These are character sequences
6890 such as @samp{??(}, which represents @samp{[}. They date from a time
6891 when some character sets didn't have all the characters that C needs,
6892 and are now utterly obsolete.)
6895 There is no way to apply auto newline settings (@pxref{Auto-newlines})
6896 on already typed lines. That's only a feature to ease interactive
6899 To generalize this issue a bit: @ccmode{} is not intended to be used as
6900 a reformatter for old code in some more or less batch-like way. With
6901 the exception of some functions like @code{c-indent-region}, it's only
6902 geared to be used interactively to edit new code. There's currently no
6903 intention to change this goal.
6905 If you want to reformat old code, you're probably better off using some
6906 other tool instead, e.g. @ref{Top, , GNU indent, indent, The `indent'
6907 Manual}, which has more powerful reformatting capabilities than
6911 The support for C++ templates (in angle brackets) is not yet complete.
6912 When a non-nested template is used in a declaration, @ccmode{} indents
6913 it and font-locks it OK. Templates used in expressions, and nested
6914 templates do not fare so well. Sometimes a workaround is to refontify
6915 the expression after typing the closing @samp{>}.
6918 In a @dfn{k&r region} (the part of an old-fashioned C function
6919 declaration which specifies the types of its parameters, coming
6920 between the parameter list and the opening brace), there should be at
6921 most 20 top-level parenthesis and bracket pairs. This limit has been
6922 imposed for performance reasons. If it is violated, the source file
6923 might be incorrectly indented or fontified.
6926 On loading @ccmode{}, sometimes this error message appears:
6929 File mode specification error: (void-variable c-font-lock-keywords-3)
6932 This is due to a bug in the function @code{eval-after-load} in some
6933 versions of (X)Emacs. It can manifest itself when there is a symbolic
6934 link in the path of the directory which contains (X)Emacs. As a
6935 workaround, put the following into your @file{.emacs} file, fairly
6939 (defun my-load-cc-fonts ()
6940 (require "cc-fonts"))
6941 (add-hook 'c-initialization-hook 'my-load-cc-fonts)
6945 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6946 @node FAQ, Updating CC Mode, Limitations and Known Bugs, Top
6947 @comment node-name, next, previous, up
6948 @appendix Frequently Asked Questions
6949 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6953 @emph{How can I change the indent level from 4 spaces to 2 spaces?}
6955 Set the variable @code{c-basic-offset}. @xref{Getting Started}.
6960 @emph{Why doesn't the @kbd{RET} key indent the new line?}
6962 Emacs' convention is that @kbd{RET} just adds a newline, and that
6963 @kbd{C-j} adds a newline and indents it. You can make @kbd{RET} do this
6964 too by adding this to your @code{c-initialization-hook}:
6967 (define-key c-mode-base-map "\C-m" 'c-context-line-break)
6970 @xref{Getting Started}. This is a very common question. If you want
6971 this to be the default behavior, don't lobby us, lobby RMS! @t{:-)}
6974 @emph{How do I stop my code jumping all over the place when I type?}
6976 Deactivate ``electric minor mode'' with @kbd{C-c C-l}. @xref{Getting
6982 @emph{How do I reindent the whole file?}
6984 Visit the file and hit @kbd{C-x h} to mark the whole buffer. Then hit
6985 @kbd{C-M-\}. @xref{Indentation Commands}.
6990 @emph{How do I reindent the current block?}
6992 First move to the brace which opens the block with @kbd{C-M-u}, then
6993 reindent that expression with @kbd{C-M-q}. @xref{Indentation
6997 @emph{I put @code{(c-set-offset 'substatement-open 0)} in my
6998 @file{.emacs} file but I get an error saying that @code{c-set-offset}'s
6999 function definition is void. What's wrong?}
7001 This means that @ccmode{} hasn't yet been loaded into your Emacs
7002 session by the time the @code{c-set-offset} call is reached, most
7003 likely because @ccmode{} is being autoloaded. Instead of putting the
7004 @code{c-set-offset} line in your top-level @file{.emacs} file, put it
7005 in your @code{c-initialization-hook} (@pxref{CC Hooks}), or simply
7006 modify @code{c-offsets-alist} directly:
7009 (setq c-offsets-alist '((substatement-open . 0)))
7013 @cindex open paren in column zero
7014 @emph{I have an open paren character at column zero inside a comment or
7015 multiline string literal, and it causes the fontification and/or
7016 indentation to go haywire. What gives?}
7018 It's due to the ad-hoc rule in (X)Emacs that such open parens always
7019 start defuns (which translates to functions, classes, namespaces or any
7020 other top-level block constructs in the @ccmode{} languages).
7022 @xref{Defuns,,, xemacs, XEmacs User's Manual}, for details.
7025 @xref{Left Margin Paren,,, emacs, GNU Emacs Manual}, for details
7026 (@xref{Defuns,,, emacs, GNU Emacs Manual}, in the Emacs 20 manual).
7029 This heuristic is built into the core syntax analysis routines in
7030 (X)Emacs, so it's not really a @ccmode{} issue. However, in Emacs
7031 21.1 it became possible to turn it off@footnote{Using the variable
7032 @code{open-paren-in-column-0-is-defun-start}.} and @ccmode{} does so
7033 there since it's got its own system to keep track of blocks.
7038 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
7039 @node Updating CC Mode, Mailing Lists and Bug Reports, FAQ, Top
7040 @comment node-name, next, previous, up
7041 @appendix Getting the Latest CC Mode Release
7042 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
7044 @ccmode{} has been standard with all versions of Emacs since 19.34 and
7045 of XEmacs since 19.16.
7048 Due to release schedule skew, it is likely that all of these Emacsen
7049 have old versions of @ccmode{} and so should be upgraded. Access to the
7050 @ccmode{} source code, as well as more detailed information on Emacsen
7051 compatibility, etc. are all available on the web site:
7054 @uref{http://cc-mode.sourceforge.net/}
7058 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
7059 @node Mailing Lists and Bug Reports, GNU Free Documentation License, Updating CC Mode, Top
7060 @comment node-name, next, previous, up
7061 @appendix Mailing Lists and Submitting Bug Reports
7062 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
7065 @findex c-submit-bug-report
7066 @findex submit-bug-report (c-)
7067 To report bugs, use the @kbd{C-c C-b} (bound to
7068 @code{c-submit-bug-report}) command. This provides vital information
7069 we need to reproduce your problem. Make sure you include a concise,
7070 but complete code example. Please try to boil your example down to
7071 just the essential code needed to reproduce the problem, and include
7072 an exact recipe of steps needed to expose the bug. Be especially sure
7073 to include any code that appears @emph{before} your bug example, if
7074 you think it might affect our ability to reproduce it.
7076 Please try to produce the problem in an Emacs instance without any
7077 customizations loaded (i.e. start it with the @samp{-q --no-site-file}
7078 arguments). If it works correctly there, the problem might be caused
7079 by faulty customizations in either your own or your site
7080 configuration. In that case, we'd appreciate it if you isolate the
7081 Emacs Lisp code that triggers the bug and include it in your report.
7083 @cindex bug report mailing list
7084 Bug reports should be sent to @email{bug-cc-mode@@gnu.org}. You can
7085 also send other questions and suggestions (kudos? @t{;-)} to that
7086 address. It's a mailing list which you can join or browse an archive
7087 of; see the web site at @uref{http://cc-mode.sourceforge.net/} for
7090 @cindex announcement mailing list
7091 If you want to get announcements of new @ccmode{} releases, send the
7092 word @emph{subscribe} in the body of a message to
7093 @email{cc-mode-announce-request@@lists.sourceforge.net}. It's possible
7094 to subscribe from the web site too. Announcements will also be posted
7095 to the Usenet newsgroups @code{gnu.emacs.sources}, @code{comp.emacs},
7096 @code{comp.emacs.xemacs}, @code{comp.lang.c}, @code{comp.lang.c++},
7097 @code{comp.lang.objective-c}, @code{comp.lang.java.softwaretools},
7098 @code{comp.lang.idl}, and @code{comp.lang.awk}.
7099 @c There is no newsgroup for Pike. :-(
7102 @node GNU Free Documentation License, Command and Function Index, Mailing Lists and Bug Reports, Top
7103 @appendix GNU Free Documentation License
7104 @include doclicense.texi
7107 @c Removed the tentative node "Mode Initialization" from here, 2005/8/27.
7108 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
7109 @node Command and Function Index, Variable Index, GNU Free Documentation License, Top
7110 @comment node-name, next, previous, up
7111 @unnumbered Command and Function Index
7112 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
7114 Since most @ccmode{} commands are prepended with the string
7115 @samp{c-}, each appears under its @code{c-@var{thing}} name and its
7116 @code{@var{thing} (c-)} name.
7123 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
7124 @node Variable Index, Concept and Key Index, Command and Function Index, Top
7125 @comment node-name, next, previous, up
7126 @unnumbered Variable Index
7127 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
7129 Since most @ccmode{} variables are prepended with the string
7130 @samp{c-}, each appears under its @code{c-@var{thing}} name and its
7131 @code{@var{thing} (c-)} name.
7138 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
7139 @node Concept and Key Index, , Variable Index, Top
7140 @comment node-name, next, previous, up
7141 @unnumbered Concept and Key Index
7142 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
7147 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
7149 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!