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, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
163 2003, 2004, 2005 Free Software Foundation, Inc.
166 Permission is granted to copy, distribute and/or modify this document
167 under the terms of the GNU Free Documentation License, Version 1.2 or
168 any later version published by the Free Software Foundation; with the
169 Invariant Sections being ``The GNU Manifesto'', ``Distribution'' and
170 ``GNU GENERAL PUBLIC LICENSE'', with the Front-Cover texts being ``A GNU
171 Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
172 license is included in the section entitled ``GNU Free Documentation
173 License'' in the Emacs manual.
175 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
176 this GNU Manual, like GNU software. Copies published by the Free
177 Software Foundation raise funds for GNU development.''
179 This document is part of a collection distributed under the GNU Free
180 Documentation License. If you want to distribute this document
181 separately from the collection, you can do so by adding a copy of the
182 license to the document, as described in section 6 of the license.
186 @comment Info directory entry for use by install-info. The indentation
187 @comment here is by request from the FSF folks.
190 * CC Mode: (ccmode). Emacs mode for editing C, C++, Objective-C,
191 Java, Pike, AWK, and CORBA IDL code.
194 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
195 @comment TeX title page
196 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
201 @center @titlefont{CC Mode 5.31}
203 @center @subtitlefont{A GNU Emacs mode for editing C and C-like languages}
205 @center Barry A. Warsaw, Martin Stjernholm, Alan Mackenzie
208 @vskip 0pt plus 1filll
211 This manual was generated from $Revision$ of $RCSfile$, which can be
213 @url{http://cvs.sf.net/viewcvs.py/cc-mode/cc-mode/cc-mode.texi}.
216 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
217 @comment The Top node contains the master menu for the Info file.
218 @comment This appears only in the Info file, not the printed manual.
219 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
221 @node Top, Introduction, (dir), (dir)
222 @comment node-name, next, previous, up
227 @ccmode{} is a GNU Emacs mode for editing files containing C, C++,
228 Objective-C, Java, CORBA IDL (and the variants PSDL and CIDL), Pike
229 and AWK code. It provides syntax-based indentation, font locking, and
230 has several handy commands and some minor modes to make the editing
231 easier. It does not provide tools to look up and navigate between
232 functions, classes etc - there are other packages for that.
235 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
236 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
245 * Custom Filling and Breaking::
246 * Custom Auto-newlines::
248 * Indentation Engine Basics::
249 * Customizing Indentation::
252 * Sample .emacs File::
253 * Performance Issues::
254 * Limitations and Known Bugs::
257 * Mailing Lists and Bug Reports::
258 * Command and Function Index::
260 * Concept and Key Index::
263 --- The Detailed Node Listing ---
267 * Indentation Commands::
269 * Movement Commands::
270 * Filling and Breaking::
274 * Hungry WS Deletion::
280 * Font Locking Preliminaries::
283 * AWK Mode Font Locking::
298 Customizing Auto-newlines
302 * Hanging Semicolons and Commas::
308 Indentation Engine Basics
310 * Syntactic Analysis::
311 * Syntactic Symbols::
312 * Indentation Calculation::
318 * Conditional Construct Symbols::
319 * Switch Statement Symbols::
320 * Brace List Symbols::
321 * External Scope Symbols::
322 * Paren List Symbols::
324 * Multiline Macro Symbols::
325 * Objective-C Method Symbols::
326 * Anonymous Class Symbol::
327 * Statement Block Symbols::
330 Customizing Indentation
333 * Interactive Customization::
334 * Line-Up Functions::
336 * Other Indentation::
340 * Brace/Paren Line-Up::
349 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
350 @node Introduction, Overview, Top, Top
351 @comment node-name, next, previous, up
352 @chapter Introduction
353 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
361 Welcome to @ccmode{}, a GNU Emacs mode for editing files containing C,
362 C++, Objective-C, Java, CORBA IDL (and the variants CORBA PSDL and
363 CIDL), Pike and AWK code. This incarnation of the mode is descended
364 from @file{c-mode.el} (also called ``Boring Old C Mode'' or BOCM
365 @t{:-)}, @file{c++-mode.el} version 2, which Barry Warsaw had been
366 maintaining since 1992, and @file{awk-mode.el}, a long neglected mode
367 in the (X)Emacs base.
369 Late in 1997, Martin Stjernholm joined Barry on the @ccmode{}
370 Maintainers Team, and implemented the Pike support. In 2000 Martin
371 took over as the sole maintainer. In 2001 Alan Mackenzie joined the
372 team, implementing AWK support in version 5.30. @ccmode{} did not
373 originally contain the font lock support for its languages --- that
374 was added in version 5.30.
376 This manual describes @ccmode{}
377 @comment The following line must appear on its own, so that the
379 @comment Release.py script can update the version number automatically
381 @ccmode{} supports the editing of K&R and ANSI C, C++, Objective-C,
382 Java, CORBA's Interface Definition Language, Pike@footnote{A C-like
383 scripting language with its roots in the LPC language used in some MUD
384 engines. See @uref{http://pike.ida.liu.se/}.} and AWK files. In this
385 way, you can easily set up consistent font locking and coding styles for
386 use in editing all of these languages, although AWK is not yet as
387 uniformly integrated as the other languages.
396 Note that the name of this package is ``@ccmode{}'', but there is no top
397 level @code{cc-mode} entry point. All of the variables, commands, and
398 functions in @ccmode{} are prefixed with @code{c-@var{thing}}, and
399 @code{c-mode}, @code{c++-mode}, @code{objc-mode}, @code{java-mode},
400 @code{idl-mode}, @code{pike-mode}, and @code{awk-mode} entry points are
401 provided. This package is intended to be a replacement for
402 @file{c-mode.el}, @file{c++-mode.el} and @file{awk-mode.el}.
404 A special word of thanks goes to Krishna Padmasola for his work in
405 converting the original @file{README} file to Texinfo format. I'd
406 also like to thank all the @ccmode{} victims who help enormously
407 during the early beta stages of @ccmode{}'s development.
409 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
410 @node Overview, Getting Started, Introduction, Top
411 @comment node-name, next, previous, up@cindex organization of the manual
412 @chapter Overview of the Manual
413 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
416 The manual starts with several introductory chapters (including this
420 The next chunk of the manual describes the day to day @emph{use} of
421 @ccmode{} (as contrasted with how to customize it).
425 The chapter ``Commands'' describes in detail how to use (nearly) all
426 of @ccmode{}'s features. There are extensive cross-references from
427 here to the corresponding sections later in the manual which tell you
428 how to customize these features.
431 ``Font Locking'' describes how ``syntax highlighting'' is applied to
432 your buffers. It is mainly background information and can be skipped
433 over at a first reading.
437 The next chunk of the manual describes how to @emph{customize}
438 @ccmode{}. Typically, an overview of a topic is given at the chapter
439 level, then the sections and subsections describe the material in
444 The chapter ``Configuration Basics'' tells you @emph{how} to write
445 customizations - whether in hooks, in styles, in both, or in neither,
446 depending on your needs. It describes the @ccmode{} style system and
447 lists the standard styles that @ccmode{} supplies.
450 The next few chapters, describe in detail how to customize the various
451 features of @ccmode{}.
454 Finally, there is a sample @file{.emacs} fragment, which might help you
455 in creating your own customization.
459 The manual ends with ``this and that'', things that don't fit cleanly
460 into any of the previous chunks.
464 Two chapters discuss the performance of @ccmode{} and known
468 The FAQ contains a list of common problems and questions.
471 The next two chapters tell you how to get in touch with the @ccmode{}
472 project - whether for updating @ccmode{} or submitting bug reports.
476 Finally, there are the customary indices.
478 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
479 @node Getting Started, Commands, Overview, Top
480 @comment node-name, next, previous, up
481 @chapter Getting Started
482 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
484 If you got this version of @ccmode{} with Emacs or XEmacs, it should
485 work just fine right out of the box. Note however that you might not
486 have the latest @ccmode{} release and might want to upgrade your copy
489 You should probably start by reading the entire chapter
490 @ref{Commands} to get an overview of @ccmode{}'s capabilities.
492 After trying out some commands, you may dislike some aspects of
493 @ccmode{}'s default configuration. Here is an outline of how to
494 change some of the settings that newcomers to @ccmode{} most often
499 This Lisp variable holds an integer, the number of columns @ccmode{}
500 indents nested code. To set this value to 6, customize
501 @code{c-basic-offset} or put this into your @file{.emacs}:
504 (setq c-basic-offset 6)
507 @item The (indentation) style
508 The basic ``shape'' of indentation created by @ccmode{}---by default,
509 this is @code{gnu} style (except for Java and AWK buffers). A list of
510 the availables styles and their descriptions can be found in
511 @ref{Built-in Styles}. A complete specification of the @ccmode{}
512 style system, including how to create your own style, can be found in
513 the chapter @ref{Styles}. To set your style to @code{linux}, either
514 customize @code{c-default-style} or put this into your @file{.emacs}:
517 (setq c-default-style '((java-mode . "java")
522 @item Electric Indentation
523 Normally, when you type ``punctuation'' characters such as @samp{;} or
524 @samp{@{}, @ccmode{} instantly reindents the current line. This can
525 be disconcerting until you get used to it. To disable @dfn{electric
526 indentation} in the current buffer, type @kbd{C-c C-l}. Type the same
527 thing to enable it again. To have electric indentation disabled by
528 default, put the following into your @file{.emacs} mode@footnote{There
529 is no ``easy customization'' facility for making this change.}:
532 (setq-default c-electric-flag nil)
536 Details of of this and other similar ``Minor Modes'' appear in the
537 section @ref{Minor Modes}.
539 @item Making the @key{RET} key indent the new line
540 The standard Emacs binding for @key{RET} just adds a new line. If you
541 want it to reindent the new line as well, rebind the key. Note that
542 the action of rebinding will fail if the pertinent keymap doesn't yet
543 exist---we thus need to delay the action until after @ccmode{} has
544 been loaded. Put the following code into your @file{.emacs}:
547 (defun my-make-CR-do-indent ()
548 (define-key c-mode-base-map "\C-m" 'c-context-line-break))
549 (add-hook 'c-initialization-hook 'my-make-CR-do-indent)
553 This example demonstrates the use of a very powerful @ccmode{} (and
554 Emacs) facility, the hook. The use of @ccmode{}'s hooks is described
558 All these settings should occur in your @file{.emacs} @emph{before}
559 any @ccmode{} buffers get loaded---in particular, before any call of
562 As you get to know the mode better, you may want to make more
563 ambitious changes to your configuration. For this, you should start
564 reading the chapter @ref{Config Basics}.
566 If you are upgrading an existing @ccmode{} installation, please see
567 the @file{README} file for installation details. In particular, if
568 you are going to be editing AWK files, @file{README} describes how to
569 configure your (X)Emacs so that @ccmode{} will supersede the obsolete
570 @code{awk-mode.el} which might have been supplied with your (X)Emacs.
571 @ccmode{} might not work with older versions of Emacs or XEmacs. See
572 the @ccmode{} release notes at @uref{http://cc-mode.sourceforge.net}
573 for the latest information on Emacs version and package compatibility
574 (@pxref{Updating CC Mode}).
576 @deffn Command c-version
578 You can find out what version of @ccmode{} you are using by visiting a C
579 file and entering @kbd{M-x c-version RET}. You should see this message in
583 Using CC Mode version 5.XX
587 where @samp{XX} is the minor release number.
590 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
591 @node Commands, Font Locking, Getting Started, Top
592 @comment node-name, next, previous, up
594 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
596 This chapter specifies all of CC Mode's commands, and thus contains
597 nearly everything you need to know to @emph{use} @ccmode{} (as
598 contrasted with configuring it). @dfn{Commands} here means both
599 control key sequences and @dfn{electric keys}, these being characters
600 such as @samp{;} which, as well as inserting themselves into the
601 buffer, also do other things.
603 You might well want to review
605 @ref{Lists,,,@emacsman{}, @emacsmantitle{}},
608 @ref{Moving by Parens,,,@emacsman{}, @emacsmantitle{}},
610 which describes commands for moving around brace and parenthesis
615 * Indentation Commands::
617 * Movement Commands::
618 * Filling and Breaking::
622 * Hungry WS Deletion::
627 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
628 @node Indentation Commands, Comment Commands, Commands, Commands
629 @comment node-name, next, previous,up
630 @section Indentation Commands
632 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
634 The following commands reindent C constructs. Note that when you
635 change your coding style, either interactively or through some other
636 means, your file does @emph{not} automatically get reindented. You
637 will need to execute one of the following commands to see the effects
640 @cindex GNU indent program
641 Also, variables like @code{c-hanging-*} and @code{c-cleanup-list}
642 (@pxref{Custom Auto-newlines}) only affect how on-the-fly code is
643 formatted. Changing the ``hanginess'' of a brace and then
644 reindenting, will not move the brace to a different line. For this,
645 you're better off getting an external program like GNU @code{indent},
646 which will rearrange brace location, amongst other things.
648 Preprocessor directives are handled as syntactic whitespace from other
649 code, i.e. they can be interspersed anywhere without affecting the
650 indentation of the surrounding code, just like comments.
652 The code inside macro definitions is, by default, still analyzed
653 syntactically so that you get relative indentation there just as you'd
654 get if the same code was outside a macro. However, since there is no
655 hint about the syntactic context, i.e. whether the macro expands to an
656 expression, to some statements, or perhaps to whole functions, the
657 syntactic recognition can be wrong. @ccmode{} manages to figure it
658 out correctly most of the time, though.
660 Reindenting large sections of code can take a long time. When
661 @ccmode{} reindents a region of code, it is essentially equivalent to
662 hitting @key{TAB} on every line of the region.
664 These commands indent code:
667 @item @kbd{@key{TAB}} (@code{c-indent-command})
669 @findex c-indent-command
670 @findex indent-command (c-)
671 This command indents the current line. That is all you need to know
672 about it for normal use.
674 @code{c-indent-command} does different things, depending on the
675 settting of @code{c-syntactic-indentation} (@pxref{Indentation Engine
680 When it's non-@code{nil} (which it normally is), the command indents
681 the line according to its syntactic context. With a prefix argument
682 (@kbd{C-u @key{TAB}}), it will re-indent the entire
683 expression@footnote{this is only useful for a line starting with a
684 comment opener or an opening brace, parenthesis, or string quote.}
685 that begins at the line's left margin.
688 When it's @code{nil}, the command indents the line by an extra
689 @code{c-basic-offset} columns. A prefix argument acts as a
690 multiplier. A bare prefix (@kbd{C-u @key{TAB}} is equivalent to -1,
691 removing @code{c-basic-offset} columns from the indentation.
694 The precise behavior is modified by several variables: With
695 @code{c-tab-always-indent}, you can make @key{TAB} insert whitespace
696 in some circumstances---@code{c-insert-tab-function} then defines
697 precisely what sort of ``whitespace'' this will be. Set the standard
698 Emacs variable @code{indent-tabs-mode} to @code{t} if you want real
699 @samp{tab} characters to be used in the indentation, to @code{nil} if
700 you want only spaces. @xref{Just Spaces,,, @emacsman{},
703 @defopt c-tab-always-indent
704 @vindex tab-always-indent (c-)
706 This variable modifies how @key{TAB} operates.
709 When it is @code{t} (the default), @key{TAB} simply indents the
712 When it is @code{nil}, @key{TAB} (re)indents the line only if point is
713 to the left of the first non-whitespace character on the line.
714 Otherwise it inserts some whitespace (a tab or an equivalent number of
715 spaces - see below) at point.
717 With some other value, the line is reindented. Additionally, if point
718 is within a string or comment, some whitespace is inserted.
722 @defopt c-insert-tab-function
723 @vindex insert-tab-function (c-)
724 @findex tab-to-tab-stop
725 When ``some whitespace'' is inserted as described above, what actually
726 happens is that the function stored in @code{c-insert-tab-function} is
727 called. Normally, this is @code{insert-tab}, which inserts a real tab
728 character or the equivalent number of spaces (depending on
729 @code{indent-tabs-mode}). Some people, however, set
730 @code{c-insert-tab-function} to @code{tab-to-tab-stop} so as to get
731 hard tab stops when indenting.
736 The kind of indentation the next five commands do depends on the
737 setting of @code{c-syntactic-indentation} (@pxref{Indentation Engine
741 when it is non-@code{nil} (the default), the commands indent lines
742 according to their syntactic context;
744 when it is @code{nil}, they just indent each line the same amount as
745 the previous non-blank line. The commands that indent a region aren't
746 very useful in this case.
750 @item @kbd{C-j} (@code{newline-and-indent})
752 @findex newline-and-indent
753 Inserts a newline and indents the new blank line, ready to start
754 typing. This is a standard (X)Emacs command.
756 @item @kbd{C-M-q} (@code{c-indent-exp})
759 @findex indent-exp (c-)
760 Indents an entire balanced brace or parenthesis expression. Note that
761 point must be on the opening brace or parenthesis of the expression
764 @item @kbd{C-c C-q} (@code{c-indent-defun})
766 @findex c-indent-defun
767 @findex indent-defun (c-)
768 Indents the entire top-level function, class or macro definition
769 encompassing point. It leaves point unchanged. This function can't be
770 used to reindent a nested brace construct, such as a nested class or
771 function, or a Java method. The top-level construct being reindented
772 must be complete, i.e. it must have both a beginning brace and an ending
775 @item @kbd{C-M-\} (@code{indent-region})
777 @findex indent-region
778 Indents an arbitrary region of code. This is a standard Emacs command,
779 tailored for C code in a @ccmode{} buffer. Note, of course, that point
780 and mark must delineate the region you want to indent.
782 @item @kbd{C-M-h} (@code{c-mark-function})
784 @findex c-mark-function
785 @findex mark-function (c-)
786 While not strictly an indentation command, this is useful for marking
787 the current top-level function or class definition as the current
788 region. As with @code{c-indent-defun}, this command operates on
789 top-level constructs, and can't be used to mark say, a Java method.
792 These variables are also useful when indenting code:
794 @defopt indent-tabs-mode
795 This is a standard Emacs variable that controls how line indentation
796 is composed. When it's non-@code{nil}, tabs can be used in a line's
797 indentation, otherwise only spaces are used.
800 @defopt c-progress-interval
801 @vindex progress-interval (c-)
802 When indenting large regions of code, this variable controls how often a
803 progress message is displayed. Set this variable to @code{nil} to
804 inhibit the progress messages, or set it to an integer which is how
805 often (in seconds) progress messages are to be displayed.
808 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
809 @node Comment Commands, Movement Commands, Indentation Commands, Commands
810 @comment node-name, next, previous, up
811 @section Comment Commands
812 @cindex comments (insertion of)
813 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
816 @item @kbd{C-c C-c} (@code{comment-region})
818 @findex comment-region
819 This command comments out the lines that start in the region. With a
820 negative argument, it does the opposite - it deletes the comment
821 delimiters from these lines. @xref{Multi-Line Comments,,, emacs, GNU
822 Emacs Manual}, for fuller details. @code{comment-region} isn't
823 actually part of @ccmode{} - it is given a @ccmode{} binding for
826 @item @kbd{M-;} (@code{comment-dwim} or @code{indent-for-comment} @footnote{The name of this command varies between (X)Emacs versions.})
829 @findex indent-for-comment
830 Insert a comment at the end of the current line, if none is there
831 already. Then reindent the comment according to @code{comment-column}
833 (@pxref{Options for Comments,,, emacs, GNU Emacs Manual})
836 (@pxref{Comments,,, xemacs, XEmacs User's Manual})
838 and the variables below. Finally, position the point after the
839 comment starter. This is a standard Emacs command, but @ccmode{}
840 enhances it a bit with two variables:
842 @defopt c-indent-comment-alist
843 @vindex indent-comment-alist (c-)
844 @vindex comment-column
845 This style variable allows you to vary the column that @kbd{M-;} puts
846 the comment at, depending on what sort of code is on the line, and
847 possibly the indentation of any similar comment on the preceding line.
848 It is an association list that maps different types of lines to
849 actions describing how they should be handled. If a certain line type
850 isn't present on the list then the line is indented to the column
851 specified by @code{comment-column}.
853 See the documentation string for for a full description of this
854 variable (use @kbd{C-h v c-indent-comment-alist}).
857 @defopt c-indent-comments-syntactically-p
858 @vindex indent-comments-syntactically-p (c-)
859 Normally, when this style variable is @code{nil}, @kbd{M-;} will
860 indent comment-only lines according to @code{c-indent-comment-alist},
861 just as it does with lines where other code precede the comments.
862 However, if you want it to act just like @key{TAB} for comment-only
863 lines you can get that by setting
864 @code{c-indent-comments-syntactically-p} to non-@code{nil}.
866 If @code{c-indent-comments-syntactically-p} is non-@code{nil} then
867 @code{c-indent-comment-alist} won't be consulted at all for comment-only
872 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
873 @node Movement Commands, Filling and Breaking, Comment Commands, Commands
874 @comment node-name, next, previous, up
875 @section Movement Commands
877 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
879 @ccmode{} contains some useful commands for moving around in C code.
882 @item @kbd{M-x c-beginning-of-defun}
883 @itemx @kbd{M-x c-end-of-defun}
884 @findex c-beginning-of-defun
885 @findex c-end-of-defun
886 @findex beginning-of-defun (c-)
887 @findex end-of-defun (c-)
888 @findex beginning-of-defun
890 Move to the start or end of the current top-level definition, this
891 being the outermost brace pair which encloses point. These functions
892 are analogous to the Emacs built-in commands @code{beginning-of-defun}
893 and @code{end-of-defun}, except they eliminate the constraint that the
894 top-level opening brace of the defun must be in column zero. See
895 @ref{Defuns,,,@emacsman{}, @emacsmantitle{}}, for more information.
897 Depending on the coding style you're using, you might prefer these two
898 commands to the standard Emacs ones. If so, consider binding them to
899 @kbd{C-M-a} and @kbd{C-M-e}. @xref{Sample .emacs File}. This
900 customization won't affect the special bindings for these key
901 sequences in force in AWK Mode. For backwards compatibility reasons,
902 the default bindings for @kbd{C-M-a} and @kbd{C-M-e} remain in effect.
904 @item @kbd{C-M-a} (AWK Mode) (@code{c-awk-beginning-of-defun})
905 @itemx @kbd{C-M-e} (AWK Mode) (@code{c-awk-end-of-defun})
906 @kindex C-M-a (AWK Mode)
907 @kindex C-M-e (AWK Mode)
908 @findex c-awk-beginning-of-defun
909 @findex awk-beginning-of-defun (c-)
910 @findex c-awk-end-of-defun
911 @findex awk-end-of-defun (c-)
912 Move back to the beginning or forward to the end of the current AWK
913 defun. These functions are bound to @kbd{C-M-a} and @kbd{C-M-e} by
914 default in AWK Mode. They can take prefix-arguments, their
915 functionality being entirely equivalent to @code{beginning-of-defun}
916 and @code{end-of-defun}.
918 AWK Mode @dfn{defuns} are either pattern/action pairs (either of which
919 might be implicit) or user defined functions. Having the @samp{@{} and
920 @samp{@}} (if there are any) in column zero, as is suggested for some
921 modes, is neither necessary nor helpful in AWK mode.
923 @item @kbd{M-a} (@code{c-beginning-of-statement})
924 @itemx @kbd{M-e} (@code{c-end-of-statement})
927 @findex c-beginning-of-statement
928 @findex c-end-of-statement
929 @findex beginning-of-statement (c-)
930 @findex end-of-statement (c-)
931 Move to the beginning or end of the innermost C statement. If point
932 is already there, move to the next beginning or end of a statement,
933 even if that means moving into a block. (Use @kbd{C-M-b} or
934 @kbd{C-M-f} to move over a balanced block.) A prefix argument @var{n}
935 means move over @var{n} statements.
937 If point is within or next to a comment or a string which spans more
938 than one line, these commands move by sentences instead of statements.
940 When called from a program, these functions take three optional
941 arguments: the repetition count, a buffer position limit which is the
942 farthest back to search for the syntactic context, and a flag saying
943 whether to do sentence motion in or near comments and multiline
946 @item @kbd{C-c C-u} (@code{c-up-conditional})
948 @findex c-up-conditional
949 @findex up-conditional (c-)
950 Move back to the containing preprocessor conditional, leaving the mark
951 behind. A prefix argument acts as a repeat count. With a negative
952 argument, move forward to the end of the containing preprocessor
955 @samp{#elif} is treated like @samp{#else} followed by @samp{#if}, so the
956 function stops at them when going backward, but not when going
959 This key sequence is not bound in AWK Mode, which doesn't have
960 preprocessor statements.
962 @item @kbd{M-x c-up-conditional-with-else}
963 @findex c-up-conditional-with-else
964 @findex up-conditional-with-else (c-)
965 A variety of @code{c-up-conditional} that also stops at @samp{#else}
966 lines. Normally those lines are ignored.
968 @item @kbd{M-x c-down-conditional}
969 @findex c-down-conditional
970 @findex down-conditional (c-)
971 Move forward into the next nested preprocessor conditional, leaving
972 the mark behind. A prefix argument acts as a repeat count. With a
973 negative argument, move backward into the previous nested preprocessor
976 @samp{#elif} is treated like @samp{#else} followed by @samp{#if}, so the
977 function stops at them when going forward, but not when going backward.
979 @item @kbd{M-x c-down-conditional-with-else}
980 @findex c-down-conditional-with-else
981 @findex down-conditional-with-else (c-)
982 A variety of @code{c-down-conditional} that also stops at @samp{#else}
983 lines. Normally those lines are ignored.
985 @item @kbd{C-c C-p} (@code{c-backward-conditional})
986 @itemx @kbd{C-c C-n} (@code{c-forward-conditional})
989 @findex c-backward-conditional
990 @findex c-forward-conditional
991 @findex backward-conditional (c-)
992 @findex forward-conditional (c-)
993 Move backward or forward across a preprocessor conditional, leaving
994 the mark behind. A prefix argument acts as a repeat count. With a
995 negative argument, move in the opposite direction.
997 These key sequences are not bound in AWK Mode, which doesn't have
998 preprocessor statements.
1000 @item @kbd{M-x c-backward-into-nomenclature}
1001 @itemx @kbd{M-x c-forward-into-nomenclature}
1002 @findex c-backward-into-nomenclature
1003 @findex c-forward-into-nomenclature
1004 @findex backward-into-nomenclature (c-)
1005 @findex forward-into-nomenclature (c-)
1006 A popular programming style, especially for object-oriented languages
1007 such as C++ is to write symbols in a mixed case format, where the
1008 first letter of each word is capitalized, and not separated by
1009 underscores. E.g. @samp{SymbolsWithMixedCaseAndNoUnderlines}.
1011 These commands move backward or forward to the beginning of the next
1012 capitalized word. With prefix argument @var{n}, move @var{n} times.
1013 If @var{n} is negative, move in the opposite direction.
1015 Note that these two commands have been superseded by
1016 @code{c-subword-mode}, which you should use instead. @xref{Subword
1017 Movement}. They might be removed from a future release of @ccmode{}.
1020 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1021 @node Filling and Breaking, Minor Modes, Movement Commands, Commands
1022 @comment node-name, next, previous, up
1023 @section Filling and Line Breaking Commands
1024 @cindex text filling
1025 @cindex line breaking
1026 @cindex comment handling
1027 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1029 Since there's a lot of normal text in comments and string literals,
1030 @ccmode{} provides features to edit these like in text mode. The goal
1031 is to do it seamlessly, i.e. you can use auto fill mode, sentence and
1032 paragraph movement, paragraph filling, adaptive filling etc. wherever
1033 there's a piece of normal text without having to think much about it.
1034 @ccmode{} keeps the indentation, fixes suitable comment line prefixes,
1037 You can configure the exact way comments get filled and broken, and
1038 where Emacs does auto-filling (see @pxref{Custom Filling and
1039 Breaking}). Typically, the style system (@pxref{Styles}) will have
1040 set this up for you, so you probably won't have to bother.
1042 @findex auto-fill-mode
1043 @cindex Auto Fill mode
1044 @cindex paragraph filling
1045 Line breaks are by default handled (almost) the same regardless of
1046 whether they are made by auto fill mode (@pxref{Auto Fill,,,
1047 @emacsman{}, @emacsmantitle{}}), by paragraph filling (e.g. with
1048 @kbd{M-q}), or explicitly with @kbd{M-j} or similar methods. In
1049 string literals, the new line gets the same indentation as the
1050 previous nonempty line.@footnote{You can change this default by
1051 setting the @code{string} syntactic symbol (@pxref{Syntactic Symbols}
1052 and @pxref{Customizing Indentation})}.
1055 @item @kbd{M-q} (@code{c-fill-paragraph})
1057 @findex c-fill-paragraph
1058 @findex fill-paragraph (c-)
1059 @cindex Javadoc markup
1060 @cindex Pike autodoc markup
1061 This command fills multiline string literals and both block
1062 and line style comments. In Java buffers, the Javadoc markup words
1063 are recognized as paragraph starters. The line oriented Pike autodoc
1064 markup words are recognized in the same way in Pike mode.
1066 The formatting of the starters (@code{/*}) and enders (@code{*/}) of
1067 block comments are kept as they were before the filling. I.e., if
1068 either the starter or ender were on a line of its own, then it stays
1069 on its own line; conversely, if the delimiter has comment text on its
1070 line, it keeps at least one word of that text with it on the line.
1072 This command is the replacement for @code{fill-paragraph} in @ccmode{}
1075 @item @kbd{M-j} (@code{c-indent-new-comment-line})
1077 @findex c-indent-new-comment-line
1078 @findex indent-new-comment-line (c-)
1079 This breaks the current line at point and indents the new line. If
1080 point was in a comment, the new line gets the proper comment line
1081 prefix. If point was inside a macro, a backslash is inserted before
1082 the line break. It is the replacement for
1083 @code{indent-new-comment-line}.
1085 @item @kbd{M-x c-context-line-break}
1086 @findex c-context-line-break
1087 @findex context-line-break (c-)
1088 Insert a line break suitable to the context: If the point is inside a
1089 comment, the new line gets the suitable indentation and comment line
1090 prefix like @code{c-indent-new-comment-line}. In normal code it's
1091 indented like @code{newline-and-indent} would do. In macros it acts
1092 like @code{newline-and-indent} but additionally inserts and optionally
1093 aligns the line ending backslash so that the macro remains unbroken.
1094 @xref{Custom Macros}, for details about the backslash alignment.
1096 This function is not bound to a key by default, but it's intended to be
1097 used on the @kbd{RET} key. If you like the behavior of
1098 @code{newline-and-indent} on @kbd{RET}, you should consider switching to
1099 this function. @xref{Sample .emacs File}.
1101 @item @kbd{M-x c-context-open-line}
1102 @findex c-context-open-line
1103 @findex context-open-line (c-)
1104 This is to @kbd{C-o} (@kbd{M-x open-line}) as
1105 @code{c-context-line-break} is to @kbd{RET}. I.e. it works just like
1106 @code{c-context-line-break} but leaves the point before the inserted
1111 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1112 @node Minor Modes, Electric Keys, Filling and Breaking, Commands
1113 @comment node-name, next, previous, up
1114 @section Minor Modes
1116 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1118 @ccmode{} contains several minor-mode-like features that you might
1119 find useful while writing new code or editing old code:
1123 When this is enabled, certain visible characters cause reformatting as
1124 they are typed. This is normally helpful, but can be a nuisance when
1125 editing chaotically formatted code. It can also be disconcerting,
1126 especially for users who are new to @ccmode{}.
1127 @item auto-newline mode
1128 This automatically inserts newlines where you'd probably want to type
1129 them yourself, e.g. after typing @samp{@}}s. Its action is suppressed
1130 when electric mode is disabled.
1131 @item hungry-delete mode
1132 This lets you delete a contiguous block of whitespace with a single
1133 key - for example, the newline and indentation just inserted by
1134 auto-newline when you want to back up and write a comment after the
1137 This mode makes basic word movement commands like @kbd{M-f}
1138 (@code{forward-word}) and @kbd{M-b} (@code{backward-word}) treat the
1139 parts of sillycapsed symbols as different words.
1140 E.g. @samp{NSGraphicsContext} is treated as three words @samp{NS},
1141 @samp{Graphics}, and @samp{Context}.
1142 @item syntactic-indentation mode
1143 When this is enabled (which it normally is), indentation commands such
1144 as @kbd{C-j} indent lines of code according to their syntactic
1145 structure. Otherwise, a line is simply indented to the same level as
1146 the previous one and @kbd{@key{TAB}} adjusts the indentation in steps
1147 of `c-basic-offset'.
1150 Full details on how these minor modes work are at @ref{Electric Keys},
1151 @ref{Auto-newlines}, @ref{Hungry WS Deletion}, @ref{Subword Movement},
1152 and @ref{Indentation Engine Basics}.
1154 You can toggle each of these minor modes on and off, and you can
1155 configure @ccmode{} so that it starts up with your favourite
1156 combination of them (@pxref{Sample .emacs File}). By default, when
1157 you initialize a buffer, electric mode and syntactic-indentation mode
1158 are enabled but the other two modes are disabled.
1160 @ccmode{} displays the current state of the first four of these minor
1161 modes on the modeline by appending letters to the major mode's name,
1162 one letter for each enabled minor mode - @samp{l} for electric mode,
1163 @samp{a} for auto-newline mode, @samp{h} for hungry delete mode, and
1164 @samp{w} for subword mode. If all these modes were enabled, you'd see
1165 @samp{C/lahw}@footnote{The @samp{C} would be replaced with the name of
1166 the language in question for the other languages @ccmode{} supports.}.
1168 Here are the commands to toggle these modes:
1171 @item @kbd{C-c C-l} (@code{c-toggle-electric-state})
1173 @findex c-toggle-electric-state
1174 @findex toggle-electric-state (c-)
1175 Toggle electric minor mode. When the command turns the mode off, it
1176 also suppresses auto-newline mode.
1178 @item @kbd{C-c C-a} (@code{c-toggle-auto-newline})
1180 @findex c-toggle-auto-newline
1181 @findex toggle-auto-newline (c-)
1182 Toggle auto-newline minor mode. When the command turns the mode on,
1183 it also enables electric minor mode.
1185 @item @kbd{M-x c-toggle-hungry-state}@footnote{Prior to @ccmode{} 5.31, this command was bound to @kbd{C-c C-d}.}
1186 @findex c-toggle-hungry-state
1187 @findex toggle-hungry-state (c-)
1188 Toggle hungry-delete minor mode.
1190 @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}.}
1191 @findex c-toggle-auto-hungry-state
1192 @findex toggle-auto-hungry-state (c-)
1193 Toggle both auto-newline and hungry delete minor modes.
1195 @item @kbd{C-c C-w} (@code{M-x c-subword-mode})
1197 @findex c-subword-mode
1198 @findex subword-mode (c-)
1199 Toggle subword mode.
1201 @item @kbd{M-x c-toggle-syntactic-indentation}
1202 @findex c-toggle-syntactic-indentation
1203 @findex toggle-syntactic-indentation (c-)
1204 Toggle syntactic-indentation mode.
1207 Common to all the toggle functions above is that if they are called
1208 programmatically, they take an optional numerical argument. A
1209 positive value will turn on the minor mode (or both of them in the
1210 case of @code{c-toggle-auto-hungry-state}) and a negative value will
1211 turn it (or them) off.
1214 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1215 @node Electric Keys, Auto-newlines, Minor Modes, Commands
1216 @comment node-name, next, previous, up
1217 @section Electric Keys and Keywords
1218 @cindex electric characters
1219 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1221 Most punctuation keys provide @dfn{electric} behavior - as well as
1222 inserting themselves they perform some other action, such as
1223 reindenting the line. A few keywords, such as @code{else}, also
1224 trigger electric action.
1226 You can inhibit the electric behaviour described here by disabling
1227 electric minor mode (@pxref{Minor Modes}.)
1229 Common to all of them is that they only behave electrically when used
1230 in normal code (as contrasted with getting typed in a string literal
1231 or comment). Those which cause re-indentation do so only when
1232 @code{c-syntactic-indentation} has a non-@code{nil} value (which it
1235 These keys and keywords are:
1236 @c ACM, 2004/8/24: c-electric-pound doesn't check c-s-i: this is more
1237 @c like a bug in the code than a bug in this document. It'll get
1238 @c fixed in the code sometime.
1243 @findex c-electric-pound
1244 @findex electric-pound (c-)
1245 @vindex c-electric-pound-behavior
1246 @vindex electric-pound-behavior (c-)
1247 Pound (bound to @code{c-electric-pound}) is electric when typed as the
1248 first non-whitespace character on a line and not within a macro
1249 definition. In this case, the variable @code{c-electric-pound-behavior}
1250 is consulted for the electric behavior. This variable takes a list
1251 value, although the only element currently defined is @code{alignleft},
1252 which tells this command to force the @samp{#} character into column
1253 zero. This is useful for entering preprocessor macro definitions.
1255 Pound is not electric in AWK buffers, where @samp{#} starts a comment,
1256 and is bound to @code{self-insert-command} like any typical printable
1258 @c ACM, 2004/8/24: Change this (and the code) to do AWK comment
1265 @findex c-electric-star
1266 @findex electric-star (c-)
1267 @findex c-electric-slash
1268 @findex electric-slash (c-)
1269 A star (bound to @code{c-electric-star}) or a slash
1270 (@code{c-electric-slash}) causes reindentation when you type it as the
1271 second component of a C style block comment opener (@samp{/*}) or a
1272 C++ line comment opener (@samp{//}) respectively, but only if the
1273 comment opener is the first thing on the line (i.e. there's only
1274 whitespace before it).
1276 Additionally, you can configure @ccmode{} so that typing a slash at
1277 the start of a line within a block comment will terminate the
1278 comment. You don't need to have electric minor mode enabled to get
1279 this behaviour. @xref{Clean-ups}.
1281 In AWK mode, @samp{*} and @samp{/} do not delimit comments and are not
1288 @findex c-electric-lt-gt
1289 @findex electric-lt-gt (c-)
1290 A less-than or greater-than sign (bound to @code{c-electric-lt-gt}) is
1291 electric in two circumstances: when it is an angle bracket in a C++
1292 @samp{template} declaration (and similar constructs in other
1293 languages) and when it is the second of two @kbd{<} or @kbd{>}
1294 characters in a C++ style stream operator. In either case, the line
1295 is reindented. Angle brackets in C @samp{#include} directives are not
1302 @findex c-electric-paren
1303 @findex electric-paren (c-)
1304 The normal parenthesis characters @samp{(} and @samp{)} (bound to
1305 @code{c-electric-paren}) reindent the current line. This is useful
1306 for getting the closing parenthesis of an argument list aligned
1309 You can also configure @ccmode{} to insert a space automatically
1310 between a function name and the @samp{(} you've just typed, and to
1311 remove it automatically after typing @samp{)}, should the argument
1312 list be empty. You don't need to have electric minor mode enabled to
1313 get these actions. @xref{Clean-ups}.
1319 @findex c-electric-brace
1320 @findex electric-brace (c-)
1321 Typing a brace (bound to @code{c-electric-brace}) reindents the
1322 current line. Also, one or more newlines might be inserted if
1323 auto-newline minor mode is enabled. @xref{Auto-newlines}.
1324 Additionally, you can configure @ccmode{} to compact excess whitespace
1325 inserted by auto-newline mode in certain circumstances.
1330 @findex c-electric-colon
1331 @findex electric-colon (c-)
1332 Typing a colon (bound to @code{c-electric-colon}) reindents the
1333 current line. Additionally, one or more newlines might be inserted if
1334 auto-newline minor mode is enabled. @xref{Auto-newlines}. If you
1335 type a second colon immediately after such an auto-newline, by default
1336 the whitespace between the two colons is removed, leaving a C++ scope
1337 operator. @xref{Clean-ups}.
1339 If you prefer, you can insert @samp{::} in a single operation,
1340 avoiding all these spurious reindentations, newlines, and clean-ups.
1341 @xref{Other Commands}.
1347 @findex c-electric-semi&comma
1348 @findex electric-semi&comma (c-)
1349 Typing a semicolon or comma (bound to @code{c-electric-semi&comma})
1350 reindents the current line. Also, a newline might be inserted if
1351 auto-newline minor mode is enabled. @xref{Auto-newlines}.
1352 Additionally, you can configure @ccmode{} so that when auto-newline
1353 has inserted whitespace after a @samp{@}}, it will be removed again
1354 when you type a semicolon or comma just after it. @xref{Clean-ups}.
1358 @deffn Command c-electric-continued-statement
1359 @findex electric-continued-statement (c-)
1361 Certain keywords are electric, causing reindentation when they are
1362 preceded only by whitespace on the line. The keywords are those that
1363 continue an earlier statement instead of starting a new one:
1364 @code{else}, @code{while}, @code{catch} (only in C++ and Java) and
1365 @code{finally} (only in Java).
1371 for (i = 0; i < 17; i++)
1373 res += a[i]->offset;
1378 Here, the @code{else} should be indented like the preceding @code{if},
1379 since it continues that statement. @ccmode{} will automatically
1380 reindent it after the @code{else} has been typed in full, since only
1381 then is it possible to decide whether it's a new statement or a
1382 continuation of the preceding @code{if}.
1387 @ccmode{} uses Abbrev mode (@pxref{Abbrevs,,, @emacsman{}, @emacsmantitle{}})
1388 to accomplish this. It's therefore turned on by default in all language
1389 modes except IDL mode, since CORBA IDL doesn't have any statements.
1393 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1394 @node Auto-newlines, Hungry WS Deletion, Electric Keys, Commands
1395 @comment node-name, next, previous, up
1396 @section Auto-newline Insertion
1397 @cindex auto-newline
1398 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1400 When you have @dfn{Auto-newline minor mode} enabled (@pxref{Minor
1401 Modes}), @ccmode{} inserts newlines for you automatically (in certain
1402 syntactic contexts) when you type a left or right brace, a colon, a
1403 semicolon, or a comma. Sometimes a newline appears before the
1404 character you type, sometimes after it, sometimes both.
1406 Auto-newline only triggers when the following conditions hold:
1410 Auto-newline minor mode is enabled, as evidenced by the indicator
1411 @samp{a} after the mode name on the modeline (e.g. @samp{C/a} or
1415 The character was typed at the end of a line, or with only whitespace
1416 after it, and possibly a @samp{\} escaping the newline.
1419 The character is not on its own line already. (This applies only to
1420 insertion of a newline @emph{before} the character.)
1424 @cindex syntactic whitespace
1425 The character was not typed inside of a literal @footnote{A
1426 @dfn{literal} is defined as any comment, string, or preprocessor macro
1427 definition. These constructs are also known as @dfn{syntactic
1428 whitespace} since they are usually ignored when scanning C code.}.
1431 No numeric argument was supplied to the command (i.e. it was typed as
1432 normal, with no @kbd{C-u} prefix).
1435 You can configure the precise circumstances in which newlines get
1436 inserted (see @pxref{Custom Auto-newlines}). Typically, the style
1437 system (@pxref{Styles}) will have set this up for you, so you probably
1438 won't have to bother.
1440 Sometimes @ccmode{} inserts an auto-newline where you don't want one,
1441 such as after a @samp{@}} when you're about to type a @samp{;}.
1442 Hungry deletion can help here (@pxref{Hungry WS Deletion}), or you can
1443 activate an appropriate @dfn{clean-up}, which will remove the excess
1444 whitespace after you've typed the @samp{;}. See @ref{Clean-ups} for a
1445 full description. See also @ref{Electric Keys} for a summary of
1446 clean-ups listed by key.
1449 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1450 @node Hungry WS Deletion, Subword Movement, Auto-newlines, Commands
1451 @comment node-name, next, previous, up
1452 @section Hungry Deletion of Whitespace
1453 @cindex hungry-deletion
1454 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1458 If you want to delete an entire block of whitespace at point, you can
1459 use @dfn{hungry deletion}. This deletes all the contiguous whitespace
1460 either before point or after point in a single operation.
1461 ``Whitespace'' here includes tabs and newlines, but not comments or
1462 preprocessor commands. Hungry deletion can markedly cut down on the
1463 number of times you have to hit deletion keys when, for example,
1464 you've made a mistake on the preceding line and have already pressed
1467 Hungry deletion is a simple feature that some people find extremely
1468 useful. In fact, you might find yourself wanting it in @strong{all}
1471 There are two different ways you can use hungry deletion:
1474 @item Using @dfn{Hungry Delete Mode} with @kbd{@key{DEL}} and @kbd{C-d}
1475 Here you toggle Hungry Delete minor mode with @kbd{M-x
1476 c-toggle-hungry-state}@footnote{Prior to @ccmode{} 5.31, this command
1477 was bound to @kbd{C-c C-d}. @kbd{C-c C-d} is now the default binding
1478 for @code{c-hungry-delete-forward}.} (@pxref{Minor Modes}.) This
1479 makes @kbd{@key{DEL}} and @kbd{C-d} do forward and backwards hungry
1483 @item @kbd{@key{DEL}} (@code{c-electric-backspace})
1485 @findex c-electric-backspace
1486 @findex electric-backspace (c-)
1487 This command is run by default when you hit the @kbd{DEL} key. When
1488 hungry delete mode is enabled, it deletes any amount of whitespace in
1489 the backwards direction. Otherwise, or when used with a prefix
1490 argument or in a literal (@pxref{Auto-newlines}), the command just
1491 deletes backwards in the usual way. (More precisely, it calls the
1492 function contained in the variable @code{c-backspace-function},
1493 passing it the prefix argument, if any.)
1495 @item @code{c-backspace-function}
1496 @vindex c-backspace-function
1497 @vindex backspace-function (c-)
1498 @findex backward-delete-char-untabify
1499 Hook that gets called by @code{c-electric-backspace} when it doesn't
1500 do an ``electric'' deletion of the preceding whitespace. The default
1501 value is @code{backward-delete-char-untabify}
1502 (@pxref{Deletion,,,@lispref{}, @lispreftitle{}}, the function which
1503 deletes a single character.
1505 @item @kbd{C-d} (@code{c-electric-delete-forward})
1507 @findex c-electric-delete-forward
1508 @findex electric-delete-forward (c-)
1509 This function, which is bound to @kbd{C-d} by default, works just like
1510 @code{c-electric-backspace} but in the forward direction. When it
1511 doesn't do an ``electric'' deletion of the following whitespace, it
1512 just does @code{delete-char}, more or less. (Strictly speaking, it
1513 calls the function in @code{c-delete-function} with the prefix
1516 @item @code{c-delete-function}
1517 @vindex c-delete-function
1518 @vindex delete-function (c-)
1520 Hook that gets called by @code{c-electric-delete-forward} when it
1521 doesn't do an ``electric'' deletion of the following whitespace. The
1522 default value is @code{delete-char}.
1525 @item Using Distinct Bindings
1526 The other (newer and recommended) way to use hungry deletion is to
1527 perform @code{c-hungry-backspace} and @code{c-hungry-delete-forward}
1528 directly through their key sequences rather than using the minor mode
1532 @item @kbd{C-c C-@key{Backspace}}, @kbd{C-c DEL}, or @kbd{C-c @key{Backspace}} (@code{c-hungry-backspace})
1533 @kindex C-c C-<backspace>
1535 @kindex C-c <backspace>
1536 @findex c-hungry-backspace
1537 @findex hungry-backspace (c-)
1538 Delete any amount of whitespace in the backwards direction (regardless
1539 whether hungry-delete mode is enabled or not). This command is bound
1540 to both @kbd{C-c C-@key{Backspace}} and @kbd{C-c @key{Backspace}},
1541 since the more natural one, @kbd{C-c C-@key{Backspace}}, is sometimes
1542 difficult to type at a character terminal.
1544 @item @kbd{C-c C-@key{Delete}}, @kbd{C-c C-d}, or @kbd{C-c @key{Delete}} (@code{c-hungry-delete-forward})
1545 @kindex C-c C-<delete>
1547 @kindex C-c <delete>
1548 @findex c-hungry-delete-forward
1549 @findex hungry-delete-forward (c-)
1550 Delete any amount of whitespace in the forward direction (regardless
1551 whether hungry-delete mode is enabled or not). This command is bound
1552 to both @kbd{C-c C-@key{Delete}} and @kbd{C-c @key{Delete}} for the
1553 same reason as for @key{Backspace} above.
1560 When we talk about @kbd{DEL}, @kbd{C-d}, @key{Backspace} and
1561 @key{Delete} above, we actually do so without connecting them to the
1562 physical keys commonly known as @key{Backspace} and @key{Delete}. The
1563 default bindings to those two keys depends on the flavor of (X)Emacs
1566 @findex c-electric-delete
1567 @findex electric-delete (c-)
1568 @findex c-hungry-delete
1569 @findex hungry-delete (c-)
1570 @vindex delete-key-deletes-forward
1572 In XEmacs 20.3 and beyond, the @key{Backspace} key is bound to
1573 @code{c-electric-backspace} and the @key{Delete} key is bound to
1574 @code{c-electric-delete}. You control the direction it deletes in by
1575 setting the variable @code{delete-key-deletes-forward}, a standard
1576 XEmacs variable. When this variable is non-@code{nil},
1577 @code{c-electric-delete} will do forward deletion with
1578 @code{c-electric-delete-forward}, otherwise it does backward deletion
1579 with @code{c-electric-backspace}. Similarly, @kbd{C-c @key{Delete}}
1580 and @kbd{C-c C-@key{Delete}} are bound to @code{c-hungry-delete} which
1581 is controlled in the same way by @code{delete-key-deletes-forward}.
1583 @findex normal-erase-is-backspace-mode
1585 Emacs 21 and later automatically binds @key{Backspace} and
1586 @key{Delete} to @kbd{DEL} and @kbd{C-d} according to your environment,
1587 and @ccmode{} extends those bindings to @kbd{C-c C-@key{Backspace}}
1588 etc. If you need to change the bindings through
1589 @code{normal-erase-is-backspace-mode} then @ccmode{} will also adapt
1590 its extended bindings accordingly.
1592 In earlier (X)Emacs versions, @ccmode{} doesn't bind either
1593 @key{Backspace} or @key{Delete} directly. Only the key codes
1594 @kbd{DEL} and @kbd{C-d} are bound, and it's up to the default bindings
1595 to map the physical keys to them. You might need to modify this
1596 yourself if the defaults are unsuitable.
1598 Getting your @key{Backspace} and @key{Delete} keys properly set up can
1599 sometimes be tricky. The information in @ref{DEL Does Not
1600 Delete,,,emacs, GNU Emacs Manual}, might be helpful if you're having
1601 trouble with this in GNU Emacs.
1604 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1605 @node Subword Movement, Other Commands, Hungry WS Deletion, Commands
1606 @comment node-name, next, previous, up
1607 @section Subword Movement and Editing
1608 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1610 @cindex nomenclature
1612 In spite of the GNU Coding Standards, it is popular to name a symbol
1613 by mixing uppercase and lowercase letters, e.g. @samp{GtkWidget},
1614 @samp{EmacsFrameClass}, or @samp{NSGraphicsContext}. Here we call
1615 these mixed case symbols @dfn{nomenclatures}. Also, each capitalized
1616 (or completely uppercase) part of a nomenclature is called a
1617 @dfn{subword}. Here are some examples:
1619 @multitable {@samp{NSGraphicsContext}} {@samp{NS}, @samp{Graphics}, and @samp{Context}}
1620 @headitem Nomenclature
1622 @item @samp{GtkWindow}
1623 @tab @samp{Gtk} and @samp{Window}
1624 @item @samp{EmacsFrameClass}
1625 @tab @samp{Emacs}, @samp{Frame}, and @samp{Class}
1626 @item @samp{NSGraphicsContext}
1627 @tab @samp{NS}, @samp{Graphics}, and @samp{Context}
1630 The subword minor mode replaces the basic word oriented movement and
1631 editing commands with variants that recognize subwords in a
1632 nomenclature and treat them as separate words:
1634 @findex c-forward-subword
1635 @findex forward-subword (c-)
1636 @findex c-backward-subword
1637 @findex backward-subword (c-)
1638 @findex c-mark-subword
1639 @findex mark-subword (c-)
1640 @findex c-kill-subword
1641 @findex kill-subword (c-)
1642 @findex c-backward-kill-subword
1643 @findex backward-kill-subword (c-)
1644 @findex c-transpose-subwords
1645 @findex transpose-subwords (c-)
1646 @findex c-capitalize-subword
1647 @findex capitalize-subword (c-)
1648 @findex c-upcase-subword
1649 @findex upcase-subword (c-)
1650 @findex c-downcase-subword
1651 @findex downcase-subword (c-)
1652 @multitable @columnfractions .20 .40 .40
1653 @headitem Key @tab Word oriented command @tab Subword oriented command
1654 @item @kbd{M-f} @tab @code{forward-word} @tab @code{c-forward-subword}
1655 @item @kbd{M-b} @tab @code{backward-word} @tab @code{c-backward-subword}
1656 @item @kbd{M-@@} @tab @code{mark-word} @tab @code{c-mark-subword}
1657 @item @kbd{M-d} @tab @code{kill-word} @tab @code{c-kill-subword}
1658 @item @kbd{M-DEL} @tab @code{backward-kill-word} @tab @code{c-backward-kill-subword}
1659 @item @kbd{M-t} @tab @code{transpose-words} @tab @code{c-transpose-subwords}
1660 @item @kbd{M-c} @tab @code{capitalize-word} @tab @code{c-capitalize-subword}
1661 @item @kbd{M-u} @tab @code{upcase-word} @tab @code{c-upcase-subword}
1662 @item @kbd{M-l} @tab @code{downcase-word} @tab @code{c-downcase-subword}
1665 Note that if you have changed the key bindings for the word oriented
1666 commands in your @file{.emacs} or a similar place, the keys you have
1667 configured are also used for the corresponding subword oriented
1670 Type @kbd{C-c C-w} to toggle subword mode on and off. To make the
1671 mode turn on automatically, put the following code in your
1675 (add-hook 'c-mode-common-hook
1676 (lambda () (c-subword-mode 1)))
1679 As a bonus, you can also use @code{c-subword-mode} in non-@ccmode{}
1680 buffers by typing @kbd{M-x c-subword-mode}.
1682 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1683 @node Other Commands, , Subword Movement, Commands
1684 @comment node-name, next, previous, up
1685 @section Other Commands
1686 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1688 Here are the various other commands that didn't fit anywhere else:
1691 @item @kbd{C-c :} (@code{c-scope-operator})
1693 @findex c-scope-operator
1694 @findex scope-operator (c-)
1695 In C++, it is also sometimes desirable to insert the double-colon scope
1696 operator without performing the electric behavior of colon insertion.
1697 @kbd{C-c :} does just this.
1699 @item @kbd{C-c C-\} (@code{c-backslash-region})
1701 @findex c-backslash-region
1702 @findex backslash-region (c-)
1703 This function inserts and aligns or deletes end-of-line backslashes in
1704 the current region. These are typically used in multi-line macros.
1706 With no prefix argument, it inserts any missing backslashes and aligns
1707 them according to the @code{c-backslash-column} and
1708 @code{c-backslash-max-column} variables. With a prefix argument, it
1709 deletes any backslashes.
1711 The function does not modify blank lines at the start of the region. If
1712 the region ends at the start of a line, it always deletes the backslash
1713 (if any) at the end of the previous line.
1715 To customize the precise workings of this command, @ref{Custom Macros}.
1719 The recommended line breaking function, @code{c-context-line-break}
1720 (@pxref{Filling and Breaking}), is especially nice if you edit
1721 multiline macros frequently. When used inside a macro, it
1722 automatically inserts and adjusts the mandatory backslash at the end
1723 of the line to keep the macro together, and it leaves the point at the
1724 right indentation column for the code. Thus you can write code inside
1725 macros almost exactly as you can elsewhere, without having to bother
1726 with the trailing backslashes.
1729 @item @kbd{C-c C-e} (@code{c-macro-expand})
1731 @findex c-macro-expand
1732 @findex macro-expand (c-)
1733 This command expands C, C++, Objective C or Pike macros in the region,
1734 using an appropriate external preprocessor program. Normally it
1735 displays its output in a temporary buffer, but if you give it a prefix
1736 arg (with @kbd{C-u C-c C-e}) it will overwrite the original region
1739 The command does not work in any of the other modes, and the key
1740 sequence is not bound in these other modes.
1742 @code{c-macro-expand} isn't actually part of @ccmode{}, even though it
1743 is bound to a @ccmode{} key sequence. If you need help setting it up
1744 or have other problems with it, you can either read its source code or
1745 ask for help in the standard (X)Emacs forums.
1748 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1749 @node Font Locking, Config Basics, Commands, Top
1750 @comment node-name, next, previous, up
1751 @chapter Font Locking
1752 @cindex font locking
1753 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1755 @cindex Font Lock mode
1757 @ccmode{} provides font locking for its supported languages by
1758 supplying patterns for use with Font Lock mode. This means that you
1759 get distinct faces on the various syntactic parts such as comments,
1760 strings, keywords and types, which is very helpful in telling them
1761 apart at a glance and discovering syntactic errors. @xref{Font
1762 Lock,,, emacs, GNU Emacs Manual}, for ways to enable font locking in
1765 @strong{Please note:} The font locking in AWK mode is currently not
1766 integrated with the rest of @ccmode{}. Only the last section of this
1767 chapter, @ref{AWK Mode Font Locking}, applies to AWK. The other
1768 sections apply to the other languages.
1771 * Font Locking Preliminaries::
1774 * AWK Mode Font Locking::
1778 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1779 @node Font Locking Preliminaries, Faces, Font Locking, Font Locking
1780 @comment node-name, next, previous, up
1781 @section Font Locking Preliminaries
1782 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1784 The font locking for most of the @ccmode{} languages were provided
1785 directly by the Font Lock package prior to version 5.30 of @ccmode{}.
1786 In the transition to @ccmode{} the patterns have been reworked
1787 completely and are applied uniformly across all the languages except AWK
1788 mode, just like the indentation rules (although each language still has
1789 some peculiarities of its own, of course). Since the languages
1790 previously had completely separate font locking patterns, this means
1791 that it's a bit different in most languages now.
1793 The main goal for the font locking in @ccmode{} is accuracy, to provide
1794 a dependable aid in recognizing the various constructs. Some, like
1795 strings and comments, are easy to recognize while others, like
1796 declarations and types, can be very tricky. @ccmode{} can go to great
1797 lengths to recognize declarations and casts correctly, especially when
1798 the types aren't recognized by standard patterns. This is a fairly
1799 demanding analysis which can be slow on older hardware, and it can
1800 therefore be disabled by choosing a lower decoration level with the
1801 variable @code{font-lock-maximum-decoration} (@pxref{Font Lock,,,
1802 emacs, GNU Emacs Manual}).
1804 @vindex font-lock-maximum-decoration
1806 The decoration levels are used as follows:
1811 Minimal font locking: Fontify only comments, strings and preprocessor
1812 directives (in the languages that use cpp).
1816 Fast font locking: In addition to level 1, fontify keywords, simple
1817 types and declarations that are easy to recognize. The variables
1818 @code{*-font-lock-extra-types} (where @samp{*} is the name of the
1819 language) are used to recognize types (see below). Documentation
1820 comments like Javadoc are fontified according to
1821 @code{c-doc-comment-style} (@pxref{Doc Comments}).
1823 Use this if you think the font locking is too slow. It's the closest
1824 corresponding level to level 3 in the old font lock patterns.
1828 Accurate font locking: Like level 2 but uses a different approach that
1829 can recognize types and declarations much more accurately. The
1830 @code{*-font-lock-extra-types} variables are still used, but user
1831 defined types are recognized correctly anyway in most cases. Therefore
1832 those variables should be fairly restrictive and not contain patterns
1835 @cindex Lazy Lock mode
1836 @cindex Just-in-time Lock mode
1838 This level is designed for fairly modern hardware and a font lock
1839 support mode like Lazy Lock or Just-in-time Lock mode that only
1840 fontifies the parts that are actually shown. Fontifying the whole
1841 buffer at once can easily get bothersomely slow even on contemporary
1843 @c ACM, 2005/8/28: There should be a page in the (X)Emacs manual
1844 @c describing these support modes. There wasn't in the
1845 @c fourteenth edition of the Emacs manual (released with Emacs 21.3).
1846 @c There might be one in the Emacs CVS for 22.1.
1849 @cindex user defined types
1850 @cindex types, user defined
1852 Since user defined types are hard to recognize you can provide
1853 additional regexps to match those you use:
1855 @defopt c-font-lock-extra-types
1856 @defoptx c++-font-lock-extra-types
1857 @defoptx objc-font-lock-extra-types
1858 @defoptx java-font-lock-extra-types
1859 @defoptx idl-font-lock-extra-types
1860 @defoptx pike-font-lock-extra-types
1861 For each language there's a variable @code{*-font-lock-extra-types},
1862 where @samp{*} stands for the language in question. It contains a list
1863 of regexps that matches identifiers that should be recognized as types,
1864 e.g. @samp{\\sw+_t} to recognize all identifiers ending with @samp{_t}
1865 as is customary in C code. Each regexp should not match more than a
1868 The default values contain regexps for many types in standard runtime
1869 libraries that are otherwise difficult to recognize, and patterns for
1870 standard type naming conventions like the @samp{_t} suffix in C and C++.
1871 Java, Objective-C and Pike have as a convention to start class names
1872 with capitals, so there are patterns for that in those languages.
1874 Despite the names of these variables, they are not only used for
1875 fontification but in other places as well where @ccmode{} needs to
1880 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1881 @node Faces, Doc Comments, Font Locking Preliminaries, Font Locking
1882 @comment node-name, next, previous, up
1885 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1887 @ccmode{} attempts to use the standard faces for programming languages
1888 in accordance with their intended purposes as far as possible. No extra
1889 faces are currently provided, with the exception of a replacement face
1890 @code{c-invalid-face} for emacsen that don't provide
1891 @code{font-lock-warning-face}.
1895 @vindex font-lock-comment-face
1896 Normal comments are fontified in @code{font-lock-comment-face}.
1899 @vindex font-lock-doc-face
1900 @vindex font-lock-doc-string-face
1901 @vindex font-lock-comment-face
1902 Comments that are recognized as documentation (@pxref{Doc Comments})
1903 get @code{font-lock-doc-face} (Emacs) or
1904 @code{font-lock-doc-string-face} (XEmacs) if those faces exist. If
1905 they don't then @code{font-lock-comment-face} is used.
1908 @vindex font-lock-string-face
1909 String and character literals are fontified in
1910 @code{font-lock-string-face}.
1913 @vindex font-lock-keyword-face
1914 Keywords are fontified with @code{font-lock-keyword-face}.
1917 @vindex font-lock-function-name-face
1918 @code{font-lock-function-name-face} is used for function names in
1919 declarations and definitions, and classes in those contexts. It's also
1920 used for preprocessor defines with arguments.
1923 @vindex font-lock-variable-name-face
1924 Variables in declarations and definitions, and other identifiers in such
1925 variable contexts, get @code{font-lock-variable-name-face}. It's also
1926 used for preprocessor defines without arguments.
1929 @vindex font-lock-constant-face
1930 @vindex font-lock-reference-face
1931 Builtin constants are fontified in @code{font-lock-constant-face} if it
1932 exists, @code{font-lock-reference-face} otherwise. As opposed to the
1933 preceding two faces, this is used on the names in expressions, and it's
1934 not used in declarations, even if there happen to be a @samp{const} in
1938 @vindex font-lock-type-face
1939 @code{font-lock-type-face} is put on types (both predefined and user
1940 defined) and classes in type contexts.
1943 @vindex font-lock-constant-face
1944 @vindex font-lock-reference-face
1945 Label identifiers get @code{font-lock-constant-face} if it exists,
1946 @code{font-lock-reference-face} otherwise.
1949 Name qualifiers and identifiers for scope constructs are fontified like
1953 Special markup inside documentation comments are also fontified like
1957 @vindex font-lock-preprocessor-face
1958 @vindex font-lock-builtin-face
1959 @vindex font-lock-reference-face
1960 Preprocessor directives get @code{font-lock-preprocessor-face} if it
1961 exists (i.e. XEmacs). In Emacs they get @code{font-lock-builtin-face}
1962 or @code{font-lock-reference-face}, for lack of a closer equivalent.
1965 @vindex font-lock-warning-face
1966 @vindex c-invalid-face
1967 @vindex invalid-face (c-)
1968 Some kinds of syntactic errors are fontified with
1969 @code{font-lock-warning-face} in Emacs. In older XEmacs versions
1970 there's no corresponding standard face, so there a special
1971 @code{c-invalid-face} is used, which is defined to stand out sharply by
1974 Note that it's not used for @samp{#error} or @samp{#warning} directives,
1975 since those aren't syntactic errors in themselves.
1979 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1980 @node Doc Comments, AWK Mode Font Locking, Faces, Font Locking
1981 @comment node-name, next, previous, up
1982 @section Documentation Comments
1983 @cindex documentation comments
1984 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1986 There are various tools to supply documentation in the source as
1987 specially structured comments, e.g. the standard Javadoc tool in Java.
1988 @ccmode{} provides an extensible mechanism to fontify such comments and
1989 the special markup inside them.
1991 @defopt c-doc-comment-style
1992 @vindex doc-comment-style (c-)
1993 This is a style variable that specifies which documentation comment
1994 style to recognize, e.g. @code{javadoc} for Javadoc comments.
1996 The value may also be a list of styles, in which case all of them are
1997 recognized simultaneously (presumably with markup cues that don't
2000 The value may also be an association list to specify different comment
2001 styles for different languages. The symbol for the major mode is then
2002 looked up in the alist, and the value of that element is interpreted as
2003 above if found. If it isn't found then the symbol `other' is looked up
2004 and its value is used instead.
2006 The default value for @code{c-doc-comment-style} is
2007 @w{@code{((java-mode . javadoc) (pike-mode . autodoc) (c-mode . gtkdoc))}}.
2009 Note that @ccmode{} uses this variable to set other variables that
2010 handle fontification etc. That's done at mode initialization or when
2011 you switch to a style which sets this variable. Thus, if you change it
2012 in some other way, e.g. interactively in a CC Mode buffer, you will need
2013 to do @kbd{M-x java-mode} (or whatever mode you're currently using) to
2016 @findex c-setup-doc-comment-style
2017 @findex setup-doc-comment-style (c-)
2018 Note also that when @ccmode{} starts up, the other variables are
2019 modified before the mode hooks are run. If you change this variable in
2020 a mode hook, you'll have to call @code{c-setup-doc-comment-style}
2021 afterwards to redo that work.
2024 @ccmode{} currently provides handing of the following doc comment
2029 @cindex Javadoc markup
2030 Javadoc comments, the standard tool in Java.
2033 @cindex Pike autodoc markup
2034 For Pike autodoc markup, the standard in Pike.
2037 @cindex GtkDoc markup
2038 For GtkDoc markup, widely used in the Gnome community.
2041 The above is by no means complete. If you'd like to see support for
2042 other doc comment styles, please let us know (@pxref{Mailing Lists and
2045 You can also write your own doc comment fontification support to use
2046 with @code{c-doc-comment-style}: Supply a variable or function
2047 @code{*-font-lock-keywords} where @samp{*} is the name you want to use
2048 in @code{c-doc-comment-style}. If it's a variable, it's prepended to
2049 @code{font-lock-keywords}. If it's a function, it's called at mode
2050 initialization and the result is prepended. For an example, see
2051 @code{javadoc-font-lock-keywords} in @file{cc-fonts.el}.
2053 If you add support for another doc comment style, please consider
2054 contributing it - send a note to @email{bug-cc-mode@@gnu.org}.
2057 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2058 @node AWK Mode Font Locking, , Doc Comments, Font Locking
2059 @comment node-name, next, previous, up
2060 @section AWK Mode Font Locking
2061 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2063 The general appearance of font-locking in AWK mode is much like in any
2064 other programming mode. @xref{Faces For Font Lock,,,elisp, GNU Emacs
2065 Lisp Reference Manual}.
2067 The following faces are, however, used in a non-standard fashion in
2071 @item @code{font-lock-variable-name-face}
2072 This face was intended for variable declarations. Since variables are
2073 not declared in AWK, this face is used instead for AWK system
2074 variables (such as @code{NF}) and ``Special File Names'' (such as
2075 @code{"/dev/stderr"}).
2077 @item @code{font-lock-builtin-face} (Emacs)/@code{font-lock-preprocessor-face} (XEmacs)
2078 This face is normally used for preprocessor directives in @ccmode{}.
2079 There are no such things in AWK, so this face is used instead for
2080 standard functions (such as @code{match}).
2082 @item @code{font-lock-string-face}
2083 As well as being used for strings, including localizable strings,
2084 (delimited by @samp{"} and @samp{_"}), this face is also used for AWK
2085 regular expressions (delimited by @samp{/}).
2087 @item @code{font-lock-warning-face} (Emacs)/@code{c-invalid-face} (XEmacs)
2088 This face highlights the following syntactically invalid AWK
2093 An unterminated string or regular expression. Here the opening
2094 delimiter (@samp{"} or @samp{/} or @samp{_"}) is displayed in
2095 @code{font-lock-warning-face}. This is most noticeable when typing in a
2096 new string/regular expression into a buffer, when the warning-face
2097 serves as a continual reminder to terminate the construct.
2099 AWK mode fontifies unterminated strings/regular expressions
2100 differently from other modes: Only the text up to the end of the line
2101 is fontified as a string (escaped newlines being handled correctly),
2102 rather than the text up to the next string quote.
2105 A space between the function name and opening parenthesis when calling
2106 a user function. The last character of the function name and the
2107 opening parenthesis are highlighted. This font-locking rule will
2108 spuriously highlight a valid concatenation expression where an
2109 identifier precedes a parenthesised expression. Unfortunately.
2112 Whitespace following the @samp{\} in what otherwise looks like an
2113 escaped newline. The @samp{\} is highlighted.
2118 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2119 @node Config Basics, Custom Filling and Breaking, Font Locking, Top
2120 @comment node-name, next, previous, up
2121 @chapter Configuration Basics
2122 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2124 @cindex Emacs Initiliazation File
2125 @cindex Configuration
2126 You configure @ccmode{} by setting Lisp variables and calling (and
2127 perhaps writing) Lisp functions@footnote{DON'T PANIC!!! This isn't
2128 difficult.}, which is usually done by adding code to an Emacs
2129 initialization file. This file might be @file{site-start.el} or
2130 @file{.emacs} or @file{init.el} or @file{default.el} or perhaps some
2131 other file. @xref{Init File,,,@emacsman{}, @emacsmantitle{}}. For
2132 the sake of conciseness, we just call this file ``your @file{.emacs}''
2133 throughout the rest of the manual.
2135 Several of these variables (currently 16), are known collectively as
2136 @dfn{style variables}. @ccmode{} provides a special mechanism, known
2137 as @dfn{styles} to make it easier to set these variables as a group,
2138 to ``inherit'' settings from one style into another, and so on. Style
2139 variables remain ordinary Lisp variables, whose values can be read and
2140 changed independently of the style system. @xref{Style Variables}.
2142 There are several ways you can write the code, depending on the
2143 precise effect you want---they are described further down on this page.
2144 If you are new to @ccmode{}, we suggest you begin with the simplest
2145 method, ``Top-level commands or the customization interface''.
2147 If you make conflicting settings in several of these ways, the way
2148 that takes precedence is the one that appears latest in this list:
2153 @itemx Top-level command or ``customization interface''
2159 Here is a summary of the different ways of writing your configuration
2163 @item Top-level commands or the ``customization interface''
2164 Most simply, you can write @code{setq} and similar commands at the top
2165 level of your @file{.emacs} file. When you load a @ccmode{} buffer,
2166 it initializes its configuration from these global values (at least,
2167 for those settings you have given values to), so it makes sense to
2168 have these @code{setq} commands run @emph{before} @ccmode{} is first
2169 initialized---in particular, before any call to @code{desktop-read}
2170 (@pxref{Saving Emacs Sessions,,, emacs, GNU Emacs Manual}). For
2171 example, you might set c-basic-offset thus:
2174 (setq c-basic-offset 4)
2177 You can use the more user friendly Customization interface instead,
2178 but this manual does not cover in detail how that works. To do this,
2179 start by typing @kbd{M-x customize-group @key{RET} c @key{RET}}.
2180 @xref{Easy Customization,,,@emacsman{}, @emacsmantitle{}}.
2181 @c The following note really belongs in the Emacs manual.
2182 Emacs normally writes the customizations at the end of your
2183 @file{.emacs} file. If you use @code{desktop-read}, you should edit
2184 your @file{.emacs} to place the call to @code{desktop-read} @emph{after}
2187 The first initialization of @ccmode{} puts a snapshot of the
2188 configuration settings into the special style @code{user}.
2189 @xref{Built-in Styles}.
2191 For basic use of Emacs, either of these ways of configuring is
2192 adequate. However, the settings are then the same in all @ccmode{}
2193 buffers and it can be clumsy to communicate them between programmers.
2194 For more flexibility, you'll want to use one (or both) of @ccmode{}'s
2195 more sophisticated facilities, hooks and styles.
2198 An Emacs @dfn{hook} is a place to put Lisp functions that you want
2199 Emacs to execute later in specific circumstances.
2200 @xref{Hooks,,,@lispref{}, @lispreftitle{}}. @ccmode{} supplies a main
2201 hook and a language-specific hook for each language it supports - any
2202 functions you put onto these hooks get executed as the last part of a
2203 buffer's initialization. Typically you put most of your customization
2204 within the main hook, and use the language-specific hooks to vary the
2205 customization settings between language modes. For example, if you
2206 wanted different (non-standard) values of @code{c-basic-offset} in C
2207 Mode and Java Mode buffers, you could do it like this:
2211 (defun my-c-mode-hook ()
2212 (setq c-basic-offset 3))
2213 (add-hook 'c-mode-hook 'my-c-mode-hook)
2215 (defun my-java-mode-hook ()
2216 (setq c-basic-offset 6))
2217 (add-hook 'java-mode-hook 'my-java-mode-hook)
2221 See @ref{CC Hooks} for more details on the use of @ccmode{} hooks.
2224 A @ccmode{} @dfn{style} is a coherent collection of customizations
2225 with a name. At any time, exactly one style is active in each
2226 @ccmode{} buffer, either the one you have selected or a default.
2227 @ccmode{} is delivered with several existing styles. Additionally,
2228 you can create your own styles, possibly based on these existing
2229 styles. If you worked in a programming team called the ``Free
2230 Group'', which had its own coding standards, you might well have this
2231 in your @file{.emacs} file:
2234 (setq c-default-style '((java-mode . "java")
2236 (other . "free-group-style")))
2239 See @ref{Styles} for fuller details on using @ccmode{} styles and how
2243 A @dfn{file style} is a rarely used variant of the ``style'' mechanism
2244 described above, which applies to an individual source file. To use
2245 it, you set certain Emacs local variables in a special block at the
2246 end of the source file. @xref{File Styles}.
2248 @item Hooks with Styles
2249 For ultimate flexibility, you can use hooks and styles together. For
2250 example, if your team were developing a product which required a
2251 Linux driver, you'd probably want to use the ``linux'' style for the
2252 driver, and your own team's style for the rest of the code. You
2253 could achieve this with code like this in your @file{.emacs}:
2257 (defun my-c-mode-hook ()
2259 (if (and (buffer-file-name)
2260 (string-match "/usr/src/linux" (buffer-file-name)))
2262 "free-group-style")))
2263 (add-hook 'c-mode-hook 'my-c-mode-hook)
2267 In a programming team, a hook is a also a good place for each member
2268 to put his own personal preferences. For example, you might be the
2269 only person in your team who likes Auto-newline minor mode. You could
2270 have it enabled by default by placing the following in your
2275 (defun my-turn-on-auto-newline ()
2276 (c-toggle-auto-newline 1))
2277 (add-hook 'c-mode-common-hook 'my-turn-on-auto-newline)
2288 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2289 @node CC Hooks, Style Variables, Config Basics, Config Basics
2290 @comment node-name, next, previous, up
2293 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2294 @c The node name is "CC Hooks" rather than "Hooks" because of a bug in
2295 @c some older versions of Info, e.g. the info.el in GNU Emacs 21.3.
2296 @c If you go to "Config Basics" and hit <CR> on the xref to "CC
2297 @c Hooks" the function Info-follow-reference searches for "*Note: CC
2298 @c Hooks" from the beginning of the page. If this node were instead
2299 @c named "Hooks", that search would spuriously find "*Note:
2300 @c Hooks(elisp)" and go to the wrong node.
2302 @ccmode{} provides several hooks that you can use to customize the
2303 mode for your coding style. The main hook is
2304 @code{c-mode-common-hook}; typically, you'll put the bulk of your
2305 customizations here. In addition, each language mode has its own
2306 hook, allowing you to fine tune your settings individually for the
2307 different @ccmode{} languages, and there is a package initialization
2308 hook. Finally, there is @code{c-special-indent-hook}, which enables
2309 you to solve anomalous indentation problems. It is described in
2310 @ref{Other Indentation}, not here. All these hooks adhere to the
2311 standard Emacs conventions.
2313 When you open a buffer, @ccmode{} first initializes it with the
2314 currently active style (@pxref{Styles}). Then it calls
2315 @code{c-mode-common-hook}, and finally it calls the language-specific
2316 hook. Thus, any style settings done in these hooks will override
2317 those set by @code{c-default-style}.
2319 @defvar c-initialization-hook
2320 @vindex initialization-hook (c-)
2321 Hook run only once per Emacs session, when @ccmode{} is initialized.
2322 This is a good place to change key bindings (or add new ones) in any
2323 of the @ccmode{} key maps. @xref{Sample .emacs File}.
2326 @defvar c-mode-common-hook
2327 @vindex mode-common-hook (c-)
2328 Common hook across all languages. It's run immediately before the
2329 language specific hook.
2333 @defvarx c++-mode-hook
2334 @defvarx objc-mode-hook
2335 @defvarx java-mode-hook
2336 @defvarx idl-mode-hook
2337 @defvarx pike-mode-hook
2338 @defvarx awk-mode-hook
2339 The language specific mode hooks. The appropriate one is run as the
2340 last thing when you enter that language mode.
2343 Although these hooks are variables defined in @ccmode{}, you can give
2344 them values before @ccmode{}'s code is loaded - indeed, this is the
2345 only way to use @code{c-initialization-hook}. Their values aren't
2346 overwritten when @ccmode{} gets loaded.
2348 Here's a simplified example of what you can add to your @file{.emacs}
2349 file to do things whenever any @ccmode{} language is edited. See the
2350 Emacs manuals for more information on customizing Emacs via hooks.
2351 @xref{Sample .emacs File}, for a more complete sample @file{.emacs}
2355 (defun my-c-mode-common-hook ()
2356 ;; my customizations for all of c-mode and related modes
2357 (no-case-fold-search)
2359 (add-hook 'c-mode-common-hook 'my-c-mode-common-hook)
2362 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2363 @node Style Variables, Styles, CC Hooks, Config Basics
2364 @comment node-name, next, previous, up
2365 @section Style Variables
2367 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2369 @cindex style variables
2370 The variables that @ccmode{}'s style system control are called
2371 @dfn{style variables}. Note that style variables are ordinary Lisp
2372 variables, which the style system initializes; you can change their
2373 values at any time (e.g. in a hook function). The style system can
2374 also also set other variables, to some extent. @xref{Styles}.
2376 @dfn{Style variables} are handled specially in several ways:
2380 Style variables are by default buffer-local variables. However, they
2381 can instead be made global by setting
2382 @code{c-style-variables-are-local-p} to @code{nil} before @ccmode{} is
2386 @vindex c-old-style-variable-behavior
2387 @vindex old-style-variable-behavior (c-)
2388 The default global binding of any style variable (with two exceptions
2389 - see below) is the special symbol @code{set-from-style}. When the
2390 style system initializes a buffer-local copy of a style variable for a
2391 @ccmode{} buffer, if its global binding is still that symbol then it
2392 will be set from the current style. Otherwise it will retain its
2393 global default@footnote{This is a big change from versions of
2394 @ccmode{} earlier than 5.26, where such settings would get overridden
2395 by the style system unless special precautions were taken. That was
2396 changed since it was counterintuitive and confusing, especially to
2397 novice users. If your configuration depends on the old overriding
2398 behavior, you can set the variable
2399 @code{c-old-style-variable-behavior} to non-@code{nil}.}. This
2400 ``otherwise'' happens, for example, when you've set the variable with
2401 @code{setq} at the top level of your @file{.emacs} (@pxref{Config
2405 The style variable @code{c-offsets-alist} (@pxref{c-offsets-alist}) is
2406 an association list with an element for each syntactic symbol. It's
2407 handled a little differently from the other style variables. It's
2408 default global binding is the empty list @code{nil}, rather than
2409 @code{set-from-style}. Before the style system is initialized, you
2410 can add individual elements to @code{c-offsets-alist} by calling
2411 @code{c-set-offset}(@pxref{c-offsets-alist}) just like you would set
2412 other style variables with @code{setq}. Those elements will then
2413 prevail when the style system later initializes a buffer-local copy of
2414 @code{c-offsets-alist}.
2417 The style variable @code{c-special-indent-hook} is also handled in a
2418 special way. Styles can only add functions to this hook, not remove
2419 them, so any global settings you put on it are always
2420 preserved@footnote{This did not change in version 5.26.}. The value
2421 you give this variable in a style definition can be either a function
2422 or a list of functions.
2425 The global bindings of the style variables get captured in the special
2426 @code{user} style when the style system is first initialized.
2427 @xref{Built-in Styles}, for details.
2430 The style variables are:@*
2431 @code{c-indent-comment-alist},
2432 @code{c-indent-comments-syntactically-p} (@pxref{Indentation
2434 @code{c-doc-comment-style} (@pxref{Doc Comments});@*
2435 @code{c-block-comment-prefix}, @code{c-comment-prefix-regexp}
2436 (@pxref{Custom Filling and Breaking});@*
2437 @code{c-hanging-braces-alist} (@pxref{Hanging Braces});@*
2438 @code{c-hanging-colons-alist} (@pxref{Hanging Colons});@*
2439 @code{c-hanging-semi&comma-criteria} (@pxref{Hanging Semicolons and
2441 @code{c-cleanup-list} (@pxref{Clean-ups});@*
2442 @code{c-basic-offset} (@pxref{Customizing Indentation});@*
2443 @code{c-offsets-alist} (@pxref{c-offsets-alist});@*
2444 @code{c-comment-only-line-offset} (@pxref{Comment Line-Up});@*
2445 @code{c-special-indent-hook}, @code{c-label-minimum-indentation}
2446 (@pxref{Other Indentation});@*
2447 @code{c-backslash-column}, @code{c-backslash-max-column}
2448 (@pxref{Custom Macros}).
2450 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2451 @node Styles, , Style Variables, Config Basics
2452 @comment node-name, next, previous, up
2455 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2457 Most people only need to edit code formatted in just a few well-defined
2458 and consistent styles. For example, their organization might impose a
2459 ``blessed'' style that all its programmers must conform to. Similarly,
2460 people who work on GNU software will have to use the GNU coding style.
2461 Some shops are more lenient, allowing a variety of coding styles, and as
2462 programmers come and go, there could be a number of styles in use. For
2463 this reason, @ccmode{} makes it convenient for you to set up logical
2464 groupings of customizations called @dfn{styles}, associate a single name
2465 for any particular style, and pretty easily start editing new or
2466 existing code using these styles.
2470 * Choosing a Style::
2476 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2477 @node Built-in Styles, Choosing a Style, Styles, Styles
2478 @comment node-name, next, previous, up
2479 @subsection Built-in Styles
2480 @cindex styles, built-in
2481 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2483 If you're lucky, one of @ccmode{}'s built-in styles might be just
2484 what you're looking for. These are:
2489 Coding style blessed by the Free Software Foundation
2490 for C code in GNU programs.
2494 The classic Kernighan and Ritchie style for C code.
2498 Also known as ``Allman style'' after Eric Allman.
2501 @cindex Whitesmith style
2502 Popularized by the examples that came with Whitesmiths C, an early
2503 commercial C compiler.
2506 @cindex Stroustrup style
2507 The classic Stroustrup style for C++ code.
2510 @cindex Ellemtel style
2511 Popular C++ coding standards as defined by ``Programming in C++, Rules
2512 and Recommendations,'' Erik Nyquist and Mats Henricson,
2513 Ellemtel@footnote{This document is available at
2514 @uref{http://www.doc.ic.ac.uk/lab/cplus/c++.rules/} among other
2516 @c N.B. This URL was still valid at 2005/8/28 (ACM).
2520 C coding standard for Linux (the kernel).
2523 @cindex Python style
2524 C coding standard for Python extension modules@footnote{Python is a
2525 high level scripting language with a C/C++ foreign function interface.
2526 For more information, see @uref{http://www.python.org/}.}.
2530 The style for editing Java code. Note that the default
2531 value for @code{c-default-style} installs this style when you enter
2536 The style for editing AWK code. Note that the default value for
2537 @code{c-default-style} installs this style when you enter
2542 This is a special style created by you. It consists of the factory
2543 defaults for all the style variables as modified by the customizations
2544 you do either with the Customization interface or by writing
2545 @code{setq}s and @code{c-set-offset}s at the top level of your
2546 @file{.emacs} file (@pxref{Config Basics}). The style system creates
2547 this style as part of its initialization and doesn't modify it
2552 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2553 @node Choosing a Style, Adding Styles, Built-in Styles, Styles
2554 @comment node-name, next, previous, up
2555 @subsection Choosing a Style
2556 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2558 Use @kbd{C-c .} to choose a style interactively:
2560 @deffn Command c-set-style style-name
2561 @findex set-style (c-)
2563 Switch to the specified style in the current buffer. Use
2564 interactively like this:
2567 @kbd{C-c . @var{style-name} @key{RET}}
2570 You can use the @key{TAB} in the normal way to do completion on the
2571 style name. Note that all style names are case insensitive, even the
2572 ones you define yourself.
2574 Setting a style in this way does @emph{not} automatically reindent your
2575 file. For commands that you can use to view the effect of your changes,
2576 see @ref{Indentation Commands} and @ref{Filling and Breaking}.
2579 The default style in all newly created buffers is @code{gnu}, except
2580 in Java and AWK modes where it's @code{java} and @code{awk}.
2582 Remember that if you set a style variable with the Customization
2583 interface or at the top level of your @file{.emacs} file before the
2584 style system is initialised (@pxref{Config Basics}), this setting will
2585 override the one that the style system would have given the variable.
2587 @defopt c-default-style
2588 @vindex default-style (c-)
2589 This variable specifies which style to install by default in new
2590 buffers. It takes either a style name string, or an association list
2591 of major mode symbols to style names:
2595 When @code{c-default-style} is a string, it must be an existing style
2596 name. This style is then used for all modes.
2599 When @code{c-default-style} is an association list, the mode language
2600 is looked up to find a style name string.
2603 If @code{c-default-style} is an association list where the mode
2604 language mode isn't found then the special symbol @samp{other} is
2605 looked up. If it's found then the associated style is used.
2608 If @samp{other} is not found then the @samp{gnu} style is used.
2611 In all cases, the style described in @code{c-default-style} is installed
2612 @emph{before} the language hooks are run, so you can always override
2613 this setting by including an explicit call to @code{c-set-style} in your
2614 language mode hook, or in @code{c-mode-common-hook}.
2616 The standard value of @code{c-default-style} is @w{@code{((java-mode
2617 . "java") (awk-mode . "awk") (other . "gnu"))}}.
2620 @defvar c-indentation-style
2621 @vindex indentation-style (c-)
2622 This variable always contains the buffer's current style name, as a
2627 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2628 @node Adding Styles, File Styles, Choosing a Style, Styles
2629 @comment node-name, next, previous, up
2630 @subsection Adding and Amending Styles
2631 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2633 If none of the built-in styles is appropriate, you'll probably want to
2634 create a new @dfn{style definition}, possibly based on an existing
2635 style. To do this, put the new style's settings into a list with the
2636 following format - the list can then be passed as an argument to the
2637 function @code{c-add-style}. You can see an example of a style
2638 definition in @ref{Sample .emacs File}.
2640 @cindex style definition
2641 @c @defvr {List} style definition
2643 @item Structure of a Style Definition List
2644 ([@var{base-style}] [(@var{variable} . @var{value}) @dots{}])
2646 Optional @var{base-style}, if present, must be a string which is the
2647 name of the @dfn{base style} from which this style inherits. At most
2648 one @var{base-style} is allowed in a style definition. If
2649 @var{base-style} is not specified, the style inherits from the table
2650 of factory default values@footnote{This table is stored internally in
2651 the variable c-fallback-style.} instead. All styles eventually
2652 inherit from this internal table. Style loops generate errors. The
2653 list of pre-existing styles can be seen in @ref{Built-in Styles}.
2655 The dotted pairs (@var{variable} . @var{value}) each consist of a
2656 variable and the value it is to be set to when the style is later
2657 activated.@footnote{Note that if the variable has been given a value
2658 by the Customization interface or a @code{setq} at the top level of
2659 your @file{.emacs}, this value will override the one the style system
2660 tries to give it. @xref{Config Basics}.} The variable can be either a
2661 @ccmode{} style variable or an arbitrary Emacs variable. In the
2662 latter case, it is @emph{not} made buffer-local by the @ccmode{} style
2666 Two variables are treated specially in the dotted pair list:
2669 @item c-offsets-alist
2670 The value is in turn a list of dotted pairs of the form
2673 (@r{@var{syntactic-symbol}} . @r{@var{offset}})
2676 as described in @ref{c-offsets-alist}. These are passed to
2677 @code{c-set-offset} so there is no need to set every syntactic symbol
2678 in your style, only those that are different from the inherited style.
2680 @item c-special-indent-hook
2681 The value is added to @code{c-special-indent-hook} using
2682 @code{add-hook}, so any functions already on it are kept. If the value
2683 is a list, each element of the list is added with @code{add-hook}.
2687 Styles are kept in the @code{c-style-alist} variable, but you
2688 should never modify this variable directly. Instead, @ccmode{}
2689 provides the function @code{c-add-style} for this purpose.
2691 @defun c-add-style stylename description &optional set-p
2692 @findex add-style (c-)
2693 Add or update a style called @var{stylename}, a string.
2694 @var{description} is the new style definition in the form described
2695 above. If @var{stylename} already exists in @code{c-style-alist} then
2696 it is replaced by @var{description}. (Note, this replacement is
2697 total. The old style is @emph{not} merged into the new one.)
2698 Otherwise, a new style is added.
2700 If the optional @var{set-p} is non-@code{nil} then the new style is
2701 applied to the current buffer as well. The use of this facility is
2702 deprecated and it might be removed from @ccmode{} in a future release.
2703 You should use @code{c-set-style} instead.
2705 The sample @file{.emacs} file provides a concrete example of how a new
2706 style can be added and automatically set. @xref{Sample .emacs File}.
2709 @defvar c-style-alist
2710 @vindex style-alist (c-)
2711 This is the variable that holds the definitions for the styles. It
2712 should not be changed directly; use @code{c-add-style} instead.
2716 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2717 @node File Styles, , Adding Styles, Styles
2718 @comment node-name, next, previous, up
2719 @subsection File Styles
2720 @cindex styles, file local
2721 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2723 @cindex file local variables
2725 The Emacs manual describes how you can customize certain variables on a
2726 per-file basis by including a @dfn{file local variable} block at the end
2727 of the file (@pxref{File Variables,, Local Variables in Files, @emacsman{},
2730 So far, you've only seen a functional interface for setting styles in
2731 @ccmode{}, and this can't be used here. @ccmode{} fills the gap by
2732 providing two variables for use in a file's local variable list.
2733 Don't use them anywhere else! These allow you to customize the style
2734 on a per-file basis:
2736 @defvar c-file-style
2737 @vindex file-style (c-)
2738 Set this variable to a style name string in the Local Variables list.
2739 From now on, when you visit the file, @ccmode{} will automatically set
2740 the file's style to this one using @code{c-set-style}.
2743 @defvar c-file-offsets
2744 @vindex file-offsets (c-)
2745 Set this variable (in the Local Variables list) to an association list
2746 of the same format as @code{c-offsets-alist}. From now on, when you
2747 visit the file, @ccmode{} will automatically institute these offsets
2748 using @code{c-set-offset}.
2751 Note that file style settings (i.e. @code{c-file-style}) are applied
2752 before file offset settings
2753 (i.e. @code{c-file-offsets})@footnote{Also, if either of these are set
2754 in a file's local variable section, all the style variable values are
2755 made local to that buffer, even if
2756 @code{c-style-variables-are-local-p} is @code{nil}. Since this
2757 variable is virtually always non-@code{nil} anyhow, you're unlikely to
2758 notice this effect.}.
2760 If you set any variables, including style variables, by the file local
2761 variables mechanism, these settings take priority over all other
2762 settings, even those in your mode hooks (@pxref{CC Hooks}). If you
2763 use @code{c-file-style} or @code{c-file-offsets} and also explicitly
2764 set a style variable in a local variable block, the explicit setting
2767 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2768 @node Custom Filling and Breaking, Custom Auto-newlines, Config Basics, Top
2769 @comment node-name, next, previous, up
2770 @chapter Customizing Filling and Line Breaking
2771 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2773 Since there's a lot of normal text in comments and string literals,
2774 @ccmode{} provides features to edit these like in text mode. It does
2775 this by hooking in on the different line breaking functions and tuning
2776 relevant variables as necessary.
2778 @vindex c-comment-prefix-regexp
2779 @vindex comment-prefix-regexp (c-)
2780 @cindex comment line prefix
2781 @vindex comment-start
2783 @vindex comment-start-skip
2784 @vindex paragraph-start
2785 @vindex paragraph-separate
2786 @vindex paragraph-ignore-fill-prefix
2787 @vindex adaptive-fill-mode
2788 @vindex adaptive-fill-regexp
2789 @vindex adaptive-fill-first-line-regexp
2790 To make Emacs recognize comments and treat text in them as normal
2791 paragraphs, @ccmode{} makes several standard
2792 variables@footnote{@code{comment-start}, @code{comment-end},
2793 @code{comment-start-skip}, @code{paragraph-start},
2794 @code{paragraph-separate}, @code{paragraph-ignore-fill-prefix},
2795 @code{adaptive-fill-mode}, @code{adaptive-fill-regexp}, and
2796 @code{adaptive-fill-first-line-regexp}.} buffer-local and modifies them
2797 according to the language syntax and the comment line prefix.
2799 @defopt c-comment-prefix-regexp
2800 @vindex comment-prefix-regexp (c-)
2801 This style variable contains the regexp used to recognize the
2802 @dfn{comment line prefix}, which is the line decoration that starts
2803 every line in a comment. The variable is either the comment line
2804 prefix itself, or (more usually) an association list with different
2805 values for different languages. The symbol for the major mode is
2806 looked up in the alist to get the regexp for the language, and if it
2807 isn't found then the special symbol @samp{other} is looked up instead.
2809 When a comment line gets divided by @kbd{M-j} or the like, @ccmode{}
2810 inserts the comment line prefix from a neighbouring line at the start
2811 of the new line. The default value of c-comment-prefix-regexp is
2812 @samp{//+\\|\\**}, which matches C++ style line comments like
2819 with two or more slashes in front of them, and the second and
2820 subsequent lines of C style block comments like
2831 with zero or more stars at the beginning of every line. If you change
2832 this variable, please make sure it still matches the comment starter
2833 (i.e. @code{//}) of line comments @emph{and} the line prefix inside
2836 @findex c-setup-paragraph-variables
2837 @findex setup-paragraph-variables (c-)
2838 Also note that since @ccmode{} uses the value of
2839 @code{c-comment-prefix-regexp} to set up several other variables at
2840 mode initialization, there won't be any effect if you just change it
2841 inside a @ccmode{} buffer. You need to call the command
2842 @code{c-setup-paragraph-variables} too, to update those other
2843 variables. That's also the case if you modify
2844 @code{c-comment-prefix-regexp} in a mode hook, since @ccmode{} will
2845 already have set up these variables before calling the hook.
2848 In comments, @ccmode{} uses @code{c-comment-prefix-regexp} to adapt
2849 the line prefix from the other lines in the comment.
2851 @vindex adaptive-fill-mode
2852 @cindex Adaptive Fill mode
2853 @ccmode{} uses adaptive fill mode (@pxref{Adaptive Fill,,, emacs, GNU
2854 Emacs Manual}) to make Emacs correctly keep the line prefix when
2855 filling paragraphs. That also makes Emacs preserve the text
2856 indentation @emph{inside} the comment line prefix. E.g. in the
2857 following comment, both paragraphs will be filled with the left
2858 margins of the texts kept intact:
2862 /* Make a balanced b-tree of the nodes in the incoming
2863 * stream. But, to quote the famous words of Donald E.
2866 * Beware of bugs in the above code; I have only
2867 * proved it correct, not tried it.
2872 @findex c-setup-filladapt
2873 @findex setup-filladapt (c-)
2874 @findex filladapt-mode
2875 @vindex filladapt-mode
2876 @cindex Filladapt mode
2877 It's also possible to use other adaptive filling packages, notably Kyle
2878 E. Jones' Filladapt package@footnote{It's available from
2879 @uref{http://www.wonderworks.com/}. As of version 2.12, it does however
2880 lack a feature that makes it work suboptimally when
2881 @code{c-comment-prefix-regexp} matches the empty string (which it does
2882 by default). A patch for that is available from
2883 @uref{http://cc-mode.sourceforge.net/,, the CC Mode web site}.},
2884 @c 2005/11/22: The above is still believed to be the case.
2885 which handles things like bulleted lists nicely. There's a convenience
2886 function @code{c-setup-filladapt} that tunes the relevant variables in
2887 Filladapt for use in @ccmode{}. Call it from a mode hook, e.g. with
2888 something like this in your @file{.emacs}:
2891 (defun my-c-mode-common-hook ()
2894 (add-hook 'c-mode-common-hook 'my-c-mode-common-hook)
2897 @defopt c-block-comment-prefix
2898 @vindex block-comment-prefix (c-)
2899 @vindex c-comment-continuation-stars
2900 @vindex comment-continuation-stars (c-)
2901 Normally the comment line prefix inserted for a new line inside a
2902 comment is deduced from other lines in it. However there's one
2903 situation when there's no hint about what the prefix should look like,
2904 namely when a block comment is broken for the first time. This style
2905 variable@footnote{In versions before 5.26, this variable was called
2906 @code{c-comment-continuation-stars}. As a compatibility measure,
2907 @ccmode{} still uses the value on that variable if it's set.} is used
2908 then as the comment prefix. It defaults to @samp{*
2909 }@footnote{Actually, this default setting of
2910 @code{c-block-comment-prefix} typically gets overriden by the default
2911 style @code{gnu}, which sets it to blank. You can see the line
2912 splitting effect described here by setting a different style,
2913 e.g. @code{k&r} @xref{Choosing a Style}.}, which makes a comment
2916 /* Got O(n^2) here, which is a Bad Thing. */
2924 /* Got O(n^2) here, which
2925 * is a Bad Thing. */
2929 Note that it won't work to adjust the indentation by putting leading
2930 spaces in @code{c-block-comment-prefix}, since @ccmode{} still uses the
2931 normal indentation engine to indent the line. Thus, the right way to
2932 fix the indentation is by customizing the @code{c} syntactic symbol. It
2933 defaults to @code{c-lineup-C-comments}, which handles the indentation of
2934 most common comment styles, see @ref{Line-Up Functions}.
2937 @defopt c-ignore-auto-fill
2938 @vindex ignore-auto-fill (c-)
2939 When auto fill mode is enabled, @ccmode{} can selectively ignore it
2940 depending on the context the line break would occur in, e.g. to never
2941 break a line automatically inside a string literal. This variable
2942 takes a list of symbols for the different contexts where auto-filling
2947 Inside a string or character literal.
2949 Inside a C style block comment.
2951 Inside a C++ style line comment.
2953 Inside a preprocessor directive.
2955 Anywhere else, i.e. in normal code.
2958 By default, @code{c-ignore-auto-fill} is set to @code{(string cpp
2959 code)}, which means that when auto-fill mode is activated,
2960 auto-filling only occurs in comments. In literals, it's often
2961 desirable to have explicit control over newlines. In preprocessor
2962 directives, the necessary @samp{\} escape character before the newline
2963 is not automatically inserted, so an automatic line break would
2964 produce invalid code. In normal code, line breaks are normally
2965 dictated by some logical structure in the code rather than the last
2966 whitespace character, so automatic line breaks there will produce poor
2967 results in the current implementation.
2970 @vindex comment-multi-line
2971 If inside a comment and @code{comment-multi-line} (@pxref{Auto Fill,,,
2972 @emacsman{}, @emacsmantitle{}} is non-@code{nil}, the indentation and
2973 line prefix are preserved. If inside a comment and
2974 @code{comment-multi-line} is @code{nil}, a new comment of the same
2975 type is started on the next line and indented as appropriate for
2978 Note that @ccmode{} sets @code{comment-multi-line} to @code{t} at
2979 startup. The reason is that @kbd{M-j} could otherwise produce sequences
2980 of single line block comments for texts that should logically be treated
2981 as one comment, and the rest of the paragraph handling code
2982 (e.g. @kbd{M-q} and @kbd{M-a}) can't cope with that, which would lead to
2983 inconsistent behavior.
2985 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2986 @node Custom Auto-newlines, Clean-ups, Custom Filling and Breaking, Top
2987 @comment node-name, next, previous, up
2988 @chapter Customizing Auto-newlines
2989 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2991 @ccmode{} determines whether to insert auto-newlines in two basically
2992 different ways, depending on the character just typed:
2995 @item Braces and Colons
2996 @ccmode{} first determines the syntactic context of the brace or colon
2997 (@pxref{Syntactic Symbols}), then looks for a corresponding element in
2998 an alist. This element specifies where to put newlines - this is any
2999 combination of before and after the brace or colon. If no alist
3000 element is found, newlines are inserted both before and after a brace,
3001 but none are inserted around a colon. See @ref{Hanging Braces} and
3002 @ref{Hanging Colons}.
3004 @item Semicolons and Commas
3005 The variable @code{c-hanging-semi&comma-criteria} contains a list of
3006 functions which determine whether to insert a newline after a newly
3007 typed semicolon or comma. @xref{Hanging Semicolons and Commas}.
3010 The names of these configuration variables contain @samp{hanging}
3011 because they let you @dfn{hang} the pertinent characters. A character
3012 which introduces a C construct is said to @dfn{hang on the right} when
3013 it appears at the end of a line after other code, being separated by a
3014 line break from the construct it introduces, like the opening brace in:
3026 A character @dfn{hangs on the left} when it appears at the start of
3027 the line after the construct it closes off, like the above closing
3030 The next chapter, ``Clean-ups'', describes how to configure @ccmode{}
3031 to remove these automatically added newlines in certain specific
3032 circumstances. @xref{Clean-ups}.
3037 * Hanging Semicolons and Commas::
3041 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3042 @node Hanging Braces, Hanging Colons, Custom Auto-newlines, Custom Auto-newlines
3043 @comment node-name, next, previous, up
3044 @section Hanging Braces
3045 @cindex hanging braces
3046 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3048 To specify which kinds of braces you want auto-newlines put around,
3049 you set the style variable @code{c-hanging-braces-alist}. Its
3050 structure and semantics are described in this section. Details of how
3051 to set it up, and its relationship to CC Mode's style system are given
3052 in @ref{Style Variables}.
3054 Say you wanted an auto-newline after (but not before) the following
3062 First you need to find the @dfn{syntactic context} of the brace---type
3063 a @key{RET} before the brace to get it on a line of its
3064 own@footnote{Also insert a @samp{\} at the end of the previous line if
3065 you're in AWK Mode.}, then type @kbd{C-c C-s}. That will tell you
3069 ((substatement-open 1061))
3073 So here you need to put the entry @code{(substatement-open . (after))}
3074 into @code{c-hanging-braces-alist}.
3076 If you don't want any auto-newlines for a particular syntactic symbol,
3077 put this into @code{c-hanging-braces-alist}:
3083 If some brace syntactic symbol is not in @code{c-hanging-brace-alist},
3084 its entry is taken by default as @code{(before after)}---insert a
3085 newline both before and after the brace. In place of a
3086 ``before/after'' list you can specify a function in this alist---this
3087 is useful when the auto newlines depend on the code around the brace.
3089 @defopt c-hanging-braces-alist
3090 @vindex hanging-braces-alist (c-)
3092 This variable is an association list which maps syntactic symbols to
3093 lists of places to insert a newline. @xref{Association
3094 Lists,,,@lispref{}, @lispreftitle{}}. The key of each element is the
3095 syntactic symbol, the associated value is either @code{nil}, a list,
3099 @item The Key - the syntactic symbol
3100 The syntactic symbols that are useful as keys in this list are
3101 @code{brace-list-intro}, @code{statement-cont},
3102 @code{inexpr-class-open}, @code{inexpr-class-close}, and all the
3103 @code{*-open} and @code{*-close} symbols. @xref{Syntactic Symbols},
3104 for a more detailed description of these syntactic symbols, except for
3105 @code{inexpr-class-open} and @code{inexpr-class-close}, which aren't
3106 actual syntactic symbols. Elements with any other value as a key get
3109 The braces of anonymous inner classes in Java are given the special
3110 symbols @code{inexpr-class-open} and @code{inexpr-class-close}, so that
3111 they can be distinguished from the braces of normal classes@footnote{The
3112 braces of anonymous classes produce a combination of
3113 @code{inexpr-class}, and @code{class-open} or @code{class-close} in
3114 normal indentation analysis.}.
3116 Note that the aggregate constructs in Pike mode, @samp{(@{}, @samp{@})},
3117 @samp{([}, @samp{])}, and @samp{(<}, @samp{>)}, do not count as brace
3118 lists in this regard, even though they do for normal indentation
3119 purposes. It's currently not possible to set automatic newlines on
3122 @item The associated value - the ``ACTION'' list or function
3123 The value associated with each syntactic symbol in this association
3124 list is called an @var{action}, which can be either a list or a
3125 function which returns a list. @xref{Custom Braces}, for how to use
3126 a function as a brace hanging @var{action}.
3128 The list @var{action} (or the list returned by @var{action} when it's
3129 a function) contains some combination of the symbols @code{before} and
3130 @code{after}, directing @ccmode{} where to put newlines in
3131 relationship to the brace being inserted. Thus, if the list contains
3132 only the symbol @code{after}, then the brace hangs on the right side
3136 // here, open braces always `hang'
3137 void spam( int i ) @{
3144 When the list contains both @code{after} and @code{before}, the braces
3145 will appear on a line by themselves, as shown by the close braces in
3146 the above example. The list can also be empty, in which case newlines
3147 are added neither before nor after the brace.
3150 If a syntactic symbol is missing entirely from
3151 @code{c-hanging-braces-alist}, it's treated in the same way as an
3152 @var{action} with a list containing @code{before} and @code{after}, so
3153 that braces by default end up on their own line.
3155 For example, the default value of @code{c-hanging-braces-alist} is:
3161 (substatement-open after)
3162 (block-close . c-snug-do-while)
3163 (extern-lang-open after)
3164 (namespace-open after)
3166 (composition-open after)
3167 (inexpr-class-open after)
3168 (inexpr-class-close before))
3171 @noindent which says that @code{brace-list-open},
3172 @code{brace-entry-open} and @code{statement-cont}@footnote{Brace lists
3173 inside statements, such as initializers for static array variables
3174 inside functions in C, are recognized as @code{statement-cont}. All
3175 normal substatement blocks are recognized with other symbols.} braces
3176 should both hang on the right side and allow subsequent text to follow
3177 on the same line as the brace. Also, @code{substatement-open},
3178 @code{extern-lang-open}, and @code{inexpr-class-open} braces should hang
3179 on the right side, but subsequent text should follow on the next line.
3180 The opposite holds for @code{inexpr-class-close} braces; they won't
3181 hang, but the following text continues on the same line. Here, in the
3182 @code{block-close} entry, you also see an example of using a function as
3183 an @var{action}. In all other cases, braces are put on a line by
3191 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3192 @node Custom Braces, , Hanging Braces, Hanging Braces
3193 @comment node-name, next, previous, up
3194 @subsection Custom Brace Hanging
3195 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3197 @vindex c-hanging-braces-alist
3198 @vindex hanging-braces-alist (c-)
3199 @cindex action functions
3200 Syntactic symbols aren't the only place where you can customize
3201 @ccmode{} with the lisp equivalent of callback functions. Remember
3202 that @var{action}s are usually a list containing some combination of
3203 the symbols @code{before} and @code{after} (@pxref{Hanging Braces}).
3204 For more flexibility, you can instead specify brace ``hanginess'' by
3205 giving a synctactic symbol an @dfn{action function} in
3206 @code{c-hanging-braces-alist}; this function determines the
3207 ``hanginess'' of a brace, usually by looking at the code near it.
3209 @cindex customization, brace hanging
3210 An action function is called with two arguments: the syntactic symbol
3211 for the brace (e.g. @code{substatement-open}), and the buffer position
3212 where the brace has been inserted. Point is undefined on entry to an
3213 action function, but the function must preserve it (e.g. by using
3214 @code{save-excursion}). The return value should be a list containing
3215 some combination of @code{before} and @code{after}, including neither
3216 of them (i.e. @code{nil}).
3218 @defvar c-syntactic-context
3219 @vindex syntactic-context (c-)
3220 During the call to the indentation or brace hanging @var{action}
3221 function, this variable is bound to the full syntactic analysis list.
3222 This might be, for example, @samp{((block-close 73))}. Don't ever
3223 give @code{c-syntactic-context} a value yourself---this would disrupt
3224 the proper functioning of @ccmode{}.
3226 This variable is also bound in three other circumstances:
3227 (i)@tie{}when calling a c-hanging-semi&comma-criteria function
3228 (@pxref{Hanging Semicolons and Commas}; (ii)@tie{}when calling a
3229 line-up function (@pxref{Custom Line-Up}; (iii)@tie{}when calling a
3230 c-special-indent-hook function (@pxref{Other Indentation}).
3233 As an example, @ccmode{} itself uses this feature to dynamically
3234 determine the hanginess of braces which close ``do-while''
3238 void do_list( int count, char** atleast_one_string )
3242 handle_string( atleast_one_string[i] );
3244 @} while( i < count );
3248 @ccmode{} assigns the @code{block-close} syntactic symbol to the
3249 brace that closes the @code{do} construct, and normally we'd like the
3250 line that follows a @code{block-close} brace to begin on a separate
3251 line. However, with ``do-while'' constructs, we want the
3252 @code{while} clause to follow the closing brace. To do this, we
3253 associate the @code{block-close} symbol with the @var{action} function
3254 @code{c-snug-do-while}:
3257 (defun c-snug-do-while (syntax pos)
3258 "Dynamically calculate brace hanginess for do-while statements."
3261 (if (and (eq syntax 'block-close)
3262 (setq langelem (assq 'block-close c-syntactic-context))
3263 (progn (goto-char (cdr langelem))
3264 (if (= (following-char) ?@{)
3266 (looking-at "\\<do\\>[^_]")))
3271 @findex c-snug-do-while
3272 @findex snug-do-while (c-)
3273 This function simply looks to see if the brace closes a ``do-while''
3274 clause and if so, returns the list @samp{(before)} indicating
3275 that a newline should be inserted before the brace, but not after it.
3276 In all other cases, it returns the list @samp{(before after)} so
3277 that the brace appears on a line by itself.
3279 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3280 @node Hanging Colons, Hanging Semicolons and Commas, Hanging Braces, Custom Auto-newlines
3281 @comment node-name, next, previous, up
3282 @section Hanging Colons
3283 @cindex hanging colons
3284 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3286 @cindex customization, colon hanging
3287 @vindex c-hanging-colons-alist
3288 @vindex hanging-colons-alist (c-)
3290 Using a mechanism similar to brace hanging (@pxref{Hanging Braces}),
3291 colons can also be made to hang using the style variable
3292 @code{c-hanging-colons-alist} - When a colon is typed, @ccmode
3293 determines its syntactic context, looks this up in the alist
3294 @code{c-changing-colons-alist} and inserts up to two newlines
3295 accordingly. Here, however, If @ccmode fails to find an entry for a
3296 syntactic symbol in the alist, no newlines are inserted around the
3299 @defopt c-hanging-colons-alist
3300 @vindex hanging-colons-alist (c-)
3303 @item The Key - the syntactic symbol
3304 The syntactic symbols appropriate as keys in this association list
3305 are: @code{case-label}, @code{label}, @code{access-label},
3306 @code{member-init-intro}, and @code{inher-intro}. @xref{Syntactic
3307 Symbols}. Elements with any other value as a key get ignored.
3309 @item The associate value - the ``ACTION'' list
3310 The @var{action} here is simply a list containing a combination of the
3311 symbols @code{before} and @code{after}. Unlike in
3312 @code{c-hanging-braces-alist}, functions as @var{actions} are not
3313 supported - there doesn't seem to be any need for them.
3317 In C++, double-colons are used as a scope operator but because these
3318 colons always appear right next to each other, newlines before and after
3319 them are controlled by a different mechanism, called @dfn{clean-ups} in
3320 @ccmode{}. @xref{Clean-ups}, for details.
3322 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3323 @node Hanging Semicolons and Commas, , Hanging Colons, Custom Auto-newlines
3324 @comment node-name, next, previous, up
3325 @section Hanging Semicolons and Commas
3326 @cindex hanging semicolons
3327 @cindex hanging commas
3328 @cindex customization, semicolon newlines
3329 @cindex customization, comma newlines
3330 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3332 @defopt c-hanging-semi&comma-criteria
3333 @vindex hanging-semi&comma-criteria (c-)
3334 This style variable takes a list of functions; these get called when
3335 you type a semicolon or comma. The functions are called in order
3336 without arguments. When these functions are entered, point is just
3337 after the newly inserted @samp{;} or @samp{,} and they must preserve
3338 point (e.g., by using @code{save-excursion}). During the call, the
3339 variable @code{c-syntactic-context} is bound to the syntactic context
3340 of the current line@footnote{This was first introduced in @ccmode{}
3341 5.31.} @pxref{Custom Braces}. These functions don't insert newlines
3342 themselves, rather they direct @ccmode{} whether or not to do so.
3343 They should return one of the following values:
3347 A newline is to be inserted after the @samp{;} or @samp{,}, and no
3348 more functions from the list are to be called.
3350 No more functions from the list are to be called, and no newline is to
3353 No determination has been made, and the next function in the list is
3357 Note that auto-newlines are never inserted @emph{before} a semicolon
3358 or comma. If every function in the list is called without a
3359 determination being made, then no newline is added.
3361 In AWK mode, this variable is set by default to @code{nil}. In the
3362 other modes, the default value is a list containing a single function,
3363 @code{c-semi&comma-inside-parenlist}. This inserts newlines after all
3364 semicolons, apart from those separating @code{for}-clause statements.
3367 @defun c-semi&comma-no-newlines-before-nonblanks
3368 @findex semi&comma-no-newlines-before-nonblanks (c-)
3369 This is an example of a criteria function, provided by @ccmode{}. It
3370 prevents newlines from being inserted after semicolons when there is a
3371 non-blank following line. Otherwise, it makes no determination. To
3372 use, add this function to the front of the
3373 @code{c-hanging-semi&comma-criteria} list.
3376 (defun c-semi&comma-no-newlines-before-nonblanks ()
3378 (if (and (eq last-command-char ?\;)
3379 (zerop (forward-line 1))
3380 (not (looking-at "^[ \t]*$")))
3386 @defun c-semi&comma-inside-parenlist
3387 @findex semi&comma-inside-parenlist (c-)
3388 @defunx c-semi&comma-no-newlines-for-oneline-inliners
3389 @findex semi&comma-no-newlines-for-oneline-inliners (c-)
3390 The function @code{c-semi&comma-inside-parenlist} is what prevents
3391 newlines from being inserted inside the parenthesis list of @code{for}
3392 statements. In addition to
3393 @code{c-semi&comma-no-newlines-before-nonblanks} described above,
3394 @ccmode{} also comes with the criteria function
3395 @code{c-semi&comma-no-newlines-for-oneline-inliners}, which suppresses
3396 newlines after semicolons inside one-line inline method definitions
3397 (e.g. in C++ or Java).
3401 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3402 @node Clean-ups, Indentation Engine Basics, Custom Auto-newlines, Top
3403 @comment node-name, next, previous, up
3406 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3408 @dfn{Clean-ups} are mechanisms which remove (or exceptionally, add)
3409 whitespace in specific circumstances and are complementary to colon
3410 and brace hanging. You enable a clean-up by adding its symbol into
3411 @code{c-cleanup-list}.
3413 On the surface, it would seem that clean-ups overlap the functionality
3414 provided by the @code{c-hanging-*-alist} variables. Clean-ups,
3415 however, are used to adjust code ``after-the-fact'', i.e. to adjust
3416 the whitespace in constructs later than when they were typed.
3418 Most of the clean-ups remove automatically inserted newlines, and are
3419 only active when auto-newline minor mode is turned on. Others will
3420 work all the time. Note that clean-ups are only performed when there
3421 is nothing but whitespace appearing between the individual components
3422 of the construct, and (apart from @code{comment-close-slash}) when the
3423 construct does not occur within a literal (@pxref{Auto-newlines}).
3425 @defopt c-cleanup-list
3426 @vindex cleanup-list (c-)
3429 You configure @ccmode{}'s clean-ups by setting the style variable
3430 @code{c-cleanup-list}, which is a list of clean-up symbols. By
3431 default, @ccmode{} cleans up only the @code{scope-operator} construct,
3432 which is necessary for proper C++ support.
3435 These are the clean-ups that are only active when electric and
3436 auto-newline minor modes are enabled:
3438 @c TBD: Would like to use some sort of @deffoo here; @table indents a
3439 @c bit too much in dvi output.
3441 @item brace-else-brace
3442 Clean up @samp{@} else @{} constructs by placing the entire construct on
3443 a single line. Clean up occurs when the open brace after the
3444 @samp{else} is typed. So for example, this:
3459 appears like this after the last open brace is typed:
3471 @item brace-elseif-brace
3472 Similar to the @code{brace-else-brace} clean-up, but this cleans up
3473 @samp{@} else if (...) @{} constructs. For example:
3488 appears like this after the last open parenthesis is typed:
3501 and like this after the last open brace is typed:
3509 @} else if( i==3 ) @{
3513 @item brace-catch-brace
3514 Analogous to @code{brace-elseif-brace}, but cleans up @samp{@} catch
3515 (...) @{} in C++ and Java mode.
3517 @item empty-defun-braces
3518 Clean up braces following a top-level function or class definition that
3519 contains no body. Clean up occurs when the closing brace is typed.
3531 is transformed into this when the close brace is typed:
3540 @item defun-close-semi
3541 Clean up the terminating semicolon on top-level function or class
3542 definitions when they follow a close brace. Clean up occurs when the
3543 semicolon is typed. So for example, the following:
3556 is transformed into this when the semicolon is typed:
3567 @item list-close-comma
3568 Clean up commas following braces in array and aggregate initializers.
3569 Clean up occurs when the comma is typed. The space before the comma
3570 is zapped just like the space before the semicolon in
3571 @code{defun-close-semi}.
3573 @item scope-operator
3574 Clean up double colons which might designate a C++ scope operator split
3575 across multiple lines@footnote{Certain C++ constructs introduce
3576 ambiguous situations, so @code{scope-operator} clean-ups might not
3577 always be correct. This usually only occurs when scoped identifiers
3578 appear in switch label tags.}. Clean up occurs when the second colon is
3579 typed. You will always want @code{scope-operator} in the
3580 @code{c-cleanup-list} when you are editing C++ code.
3582 @item one-liner-defun
3583 Clean up a single line of code enclosed by defun braces by removing
3584 the whitespace before and after the code. The clean-up happens when
3585 the closing brace is typed. If the variable
3586 @code{c-max-one-liner-length} is set, the cleanup is only done if the
3587 resulting line would be no longer than the value of that variable.
3589 For example, consider this AWK code:
3594 FS = "\t" # use <TAB> as a field separator
3600 It gets compacted to the following when the closing brace is typed:
3604 BEGIN @{FS = "\t"@} # use <TAB> as a field separator
3608 @defopt c-max-one-liner-length
3609 @vindex max-one-liner-length (c-)
3610 The maximum length of the resulting line for which the clean-up
3611 @code{one-liner-defun} will be triggered. This length is that of the entire
3612 line, including any leading whitespace and any trailing comment. Its
3613 default value is 80. If the value is zero or @code{nil}, no limit
3618 The following clean-ups are always active when they occur on
3619 @code{c-cleanup-list}, regardless of whether Electric minor mode or
3620 Auto-newline minor mode are enabled:
3623 @item space-before-funcall
3624 Insert a space between the function name and the opening parenthesis
3625 of a function call. This produces function calls in the style
3626 mandated by the GNU coding standards, e.g. @samp{signal@tie{}(SIGINT,
3627 SIG_IGN)} and @samp{abort@tie{}()}. Clean up occurs when the opening
3628 parenthesis is typed. This clean-up should never be active in AWK
3629 Mode, since such a space is syntactically invalid for user defined
3632 @item compact-empty-funcall
3633 Clean up any space between the function name and the opening parenthesis
3634 of a function call that has no arguments. This is typically used
3635 together with @code{space-before-funcall} if you prefer the GNU function
3636 call style for functions with arguments but think it looks ugly when
3637 it's only an empty parenthesis pair. I.e. you will get @samp{signal
3638 (SIGINT, SIG_IGN)}, but @samp{abort()}. Clean up occurs when the
3639 closing parenthesis is typed.
3641 @item comment-close-slash
3642 When inside a block comment, terminate the comment when you type a
3643 slash at the beginning of a line (i.e. immediately after the comment
3644 prefix). This clean-up removes whitespace preceding the slash and if
3645 needed, inserts a star to complete the token @samp{*/}.
3649 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3650 @node Indentation Engine Basics, Customizing Indentation, Clean-ups, Top
3651 @comment node-name, next, previous, up
3652 @chapter Indentation Engine Basics
3653 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3655 This chapter will briefly cover how @ccmode{} indents lines of code.
3656 It is helpful to understand the indentation model being used so that
3657 you will know how to customize @ccmode{} for your personal coding
3658 style. All the details are in @ref{Customizing Indentation}.
3660 @ccmode{} has an indentation engine that provides a flexible and
3661 general mechanism for customizing indentation. When @ccmode{} indents
3662 a line of code, it separates its calculations into two steps:
3666 @cindex syntactic symbol
3667 @cindex anchor position
3668 It analyzes the line to determine its @dfn{syntactic symbol(s)} (the
3669 kind of language construct it's looking at) and its @dfn{anchor
3670 position} (the position earlier in the file that @ccmode{} will indent
3671 the line relative to). The anchor position might be the location of
3672 an opening brace in the previous line, for example. @xref{Syntactic
3676 @cindex indentation offset specifications
3677 It looks up the syntactic symbol(s) in the configuration to get the
3678 corresponding @dfn{offset(s)}. The symbol @code{+}, which means
3679 ``indent this line one more level'' is a typical offset. @ccmode{}
3680 then applies these offset(s) to the anchor position, giving the
3681 indentation for the line. The different sorts of offsets are
3682 described in @ref{c-offsets-alist}.
3685 In exceptional circumstances, the syntax directed indentation
3686 described here may be a nuisance rather than a help. You can disable
3687 it by setting @code{c-syntactic-indentation} to @code{nil}. (To set
3688 the variable interactively, @ref{Minor Modes}).
3690 @defopt c-syntactic-indentation
3691 @vindex syntactic-indentation (c-)
3692 When this is non-@code{nil} (which it is by default), the indentation
3693 of code is done according to its syntactic structure. When it's
3694 @code{nil}, every line is just indented to the same level as the
3695 previous one, and @kbd{TAB} (@code{c-indent-command}) adjusts the
3696 indentation in steps of @code{c-basic-offset}. The current style
3697 (@pxref{Config Basics}) then has no effect on indentation, nor do any
3698 of the variables associated with indentation, not even
3699 @code{c-special-indent-hook}.
3703 * Syntactic Analysis::
3704 * Syntactic Symbols::
3705 * Indentation Calculation::
3709 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3710 @node Syntactic Analysis, Syntactic Symbols, Indentation Engine Basics, Indentation Engine Basics
3711 @comment node-name, next, previous, up
3712 @section Syntactic Analysis
3713 @cindex syntactic analysis
3714 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3716 @cindex syntactic element
3717 @cindex syntactic context
3718 The first thing @ccmode{} does when indenting a line of code, is to
3719 analyze the line, determining the @dfn{syntactic context} of the
3720 (first) construct on that line. It's a list of @dfn{syntactic
3721 elements}, where each syntactic element in turn is a list@footnote{In
3722 @ccmode 5.28 and earlier, a syntactic element was a dotted pair; the
3723 cons was the syntactic symbol and the cdr was the anchor position.
3724 For compatibility's sake, the parameter passed to a line-up function
3725 still has this dotted pair form (@pxref{Custom Line-Up}).} Here is a
3726 brief and typical example:
3729 ((defun-block-intro 1959))
3732 @cindex syntactic symbol
3734 The first thing inside each syntactic element is always a
3735 @dfn{syntactic symbol}. It describes the kind of construct that was
3736 recognized, e.g. @code{statement}, @code{substatement},
3737 @code{class-open}, @code{class-close}, etc. @xref{Syntactic Symbols},
3738 for a complete list of currently recognized syntactic symbols and
3739 their semantics. The remaining entries are various data associated
3740 with the recognized construct - there might be zero or more.
3742 @cindex anchor position
3743 Conceptually, a line of code is always indented relative to some
3744 position higher up in the buffer (typically the indentation of the
3745 previous line). That position is the @dfn{anchor position} in the
3746 syntactic element. If there is an entry after the syntactic symbol in
3747 the syntactic element list then it's either nil or that anchor position.
3749 Here is an example. Suppose we had the following code as the only thing
3750 in a C++ buffer @footnote{The line numbers in this and future examples
3751 don't actually appear in the buffer, of course!}:
3754 1: void swap( int& a, int& b )
3763 We can use @kbd{C-c C-s} (@code{c-show-syntactic-information}) to
3764 report what the syntactic analysis is for the current line:
3767 @item @kbd{C-c C-s} (@code{c-show-syntactic-information})
3769 @findex c-show-syntactic-information
3770 @findex show-syntactic-information (c-)
3771 This command calculates the syntactic analysis of the current line and
3772 displays it in the minibuffer. The command also highlights the anchor
3776 Running this command on line 4 of this example, we'd see in the echo
3777 area@footnote{With a universal argument (i.e. @kbd{C-u C-c C-s}) the
3778 analysis is inserted into the buffer as a comment on the current
3786 and the @samp{i} of @code{int} on line 3 would be highlighted. This
3787 tells us that the line is a statement and it is indented relative to
3788 buffer position 35, the highlighted position. If you were to move
3789 point to line 3 and hit @kbd{C-c C-s}, you would see:
3792 ((defun-block-intro 29))
3796 This indicates that the @samp{int} line is the first statement in a top
3797 level function block, and is indented relative to buffer position 29,
3798 which is the brace just after the function header.
3800 Here's another example:
3803 1: int add( int val, int incr, int doit )
3807 5: return( val + incr );
3814 Hitting @kbd{C-c C-s} on line 4 gives us:
3817 ((substatement-open 46))
3820 @cindex substatement
3821 @cindex substatement block
3823 which tells us that this is a brace that @emph{opens} a substatement
3824 block. @footnote{A @dfn{substatement} is the line after a
3825 conditional statement, such as @code{if}, @code{else}, @code{while},
3826 @code{do}, @code{switch}, etc. A @dfn{substatement
3827 block} is a brace block following one of these conditional statements.}
3829 @cindex comment-only line
3830 Syntactic contexts can contain more than one element, and syntactic
3831 elements need not have anchor positions. The most common example of
3832 this is a @dfn{comment-only line}:
3835 1: void draw_list( List<Drawables>& drawables )
3837 3: // call the virtual draw() method on each element in list
3838 4: for( int i=0; i < drawables.count(), ++i )
3840 6: drawables[i].draw();
3846 Hitting @kbd{C-c C-s} on line 3 of this example gives:
3849 ((comment-intro) (defun-block-intro 46))
3853 and you can see that the syntactic context contains two syntactic
3854 elements. Notice that the first element, @samp{(comment-intro)}, has no
3858 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3859 @node Syntactic Symbols, Indentation Calculation, Syntactic Analysis, Indentation Engine Basics
3860 @comment node-name, next, previous, up
3861 @section Syntactic Symbols
3862 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
3864 @cindex syntactic symbols, brief list
3865 @vindex c-offsets-alist
3866 @vindex offsets-alist (c-)
3867 This section is a complete list of the syntactic symbols which appear
3868 in the @code{c-offsets-alist} style variable, along with brief
3869 descriptions. The previous section (@pxref{Syntactic Analysis})
3870 states what syntactic symbols are and how the indentation engine uses
3873 More detailed descriptions of these symbols, together with snippets of
3874 source code to which they apply, appear in the examples in the
3875 subsections below. Note that, in the interests of brevity, the anchor
3876 position associated with most syntactic symbols is @emph{not}
3877 specified. In cases of doubt, type @kbd{C-c C-s} on a pertinent
3878 line---this highlights the anchor position.
3880 @ssindex -open symbols
3881 @ssindex -close symbols
3882 @ssindex -block-intro symbols
3883 The syntactic symbols which indicate brace constructs follow a general
3884 naming convention. When a line begins with an open or close brace,
3885 its syntactic symbol will contain the suffix @code{-open} or
3886 @code{-close} respectively. The first line within the brace block
3887 construct will contain the suffix @code{-block-intro}.
3889 @ssindex -intro symbols
3890 @ssindex -cont symbols
3891 In constructs which can span several lines, a distinction is usually
3892 made between the first line that introduces the construct and the
3893 lines that continue it. The syntactic symbols that indicate these
3894 lines will contain the suffixes @code{-intro} or @code{-cont}
3897 The best way to understand how all this works is by looking at some
3898 examples. Remember that you can see the syntax of any source code
3899 line by using @kbd{C-c C-s}.
3903 Inside a multiline string. @ref{Literal Symbols}.
3905 Inside a multiline C style block comment. @ref{Literal Symbols}.
3907 Brace that opens a top-level function definition. @ref{Function
3910 Brace that closes a top-level function definition. @ref{Function
3912 @item defun-block-intro
3913 The first line in a top-level defun. @ref{Function Symbols}.
3915 Brace that opens a class definition. @ref{Class Symbols}.
3917 Brace that closes a class definition. @ref{Class Symbols}.
3919 Brace that opens an in-class inline method. @ref{Class Symbols}.
3921 Brace that closes an in-class inline method. @ref{Class Symbols}.
3922 @item func-decl-cont
3923 The region between a function definition's argument list and the
3924 function opening brace (excluding K&R argument declarations). In C,
3925 you cannot put anything but whitespace and comments in this region,
3926 however in C++ and Java, @code{throws} declarations and other things
3927 can appear here. @ref{Literal Symbols}. @c @emph{FIXME!!! Can it not
3928 @c go somewhere better?}
3929 @item knr-argdecl-intro
3930 First line of a K&R C argument declaration. @ref{K&R Symbols}.
3932 Subsequent lines in a K&R C argument declaration. @ref{K&R Symbols}.
3934 The first line in a ``topmost'' definition. @ref{Function Symbols}.
3935 @item topmost-intro-cont
3936 Topmost definition continuation lines. This is only used in the parts
3937 that aren't covered by other symbols such as @code{func-decl-cont} and
3938 @code{knr-argdecl}. @ref{Function Symbols}.
3939 @item member-init-intro
3940 First line in a member initialization list. @ref{Class Symbols}.
3941 @item member-init-cont
3942 Subsequent member initialization list lines. @ref{Class Symbols}.
3944 First line of a multiple inheritance list. @ref{Class Symbols}.
3946 Subsequent multiple inheritance lines. @ref{Class Symbols}.
3948 Statement block open brace. @ref{Literal Symbols}.
3950 Statement block close brace. @ref{Conditional Construct Symbols}.
3951 @item brace-list-open
3952 Open brace of an enum or static array list. @ref{Brace List Symbols}.
3953 @item brace-list-close
3954 Close brace of an enum or static array list. @ref{Brace List Symbols}.
3955 @item brace-list-intro
3956 First line in an enum or static array list. @ref{Brace List Symbols}.
3957 @item brace-list-entry
3958 Subsequent lines in an enum or static array list. @ref{Brace List
3960 @item brace-entry-open
3961 Subsequent lines in an enum or static array list where the line begins
3962 with an open brace. @ref{Brace List Symbols}.
3964 A statement. @ref{Function Symbols}.
3965 @item statement-cont
3966 A continuation of a statement. @ref{Function Symbols}.
3967 @item statement-block-intro
3968 The first line in a new statement block. @ref{Conditional Construct
3970 @item statement-case-intro
3971 The first line in a case block. @ref{Switch Statement Symbols}.
3972 @item statement-case-open
3973 The first line in a case block that starts with a brace. @ref{Switch
3976 The first line after a conditional or loop construct.
3977 @ref{Conditional Construct Symbols}.
3978 @item substatement-open
3979 The brace that opens a substatement block. @ref{Conditional Construct
3981 @item substatement-label
3982 The first line after a conditional or loop construct if it's a label.
3983 @ref{Conditional Construct Symbols}.
3985 A label in a @code{switch} block. @ref{Switch Statement Symbols}.
3987 C++ access control label. @ref{Class Symbols}.
3989 Any other label. @ref{Literal Symbols}.
3990 @item do-while-closure
3991 The @code{while} line that ends a @code{do}-@code{while} construct.
3992 @ref{Conditional Construct Symbols}.
3994 The @code{else} line of an @code{if}-@code{else} construct.
3995 @ref{Conditional Construct Symbols}.
3997 The @code{catch} or @code{finally} (in Java) line of a
3998 @code{try}-@code{catch} construct. @ref{Conditional Construct
4001 A line containing only a comment introduction. @ref{Literal Symbols}.
4003 The first line in an argument list. @ref{Paren List Symbols}.
4005 Subsequent argument list lines when no arguments follow on the same
4006 line as the arglist opening paren. @ref{Paren List Symbols}.
4007 @item arglist-cont-nonempty
4008 Subsequent argument list lines when at least one argument follows on
4009 the same line as the arglist opening paren. @ref{Paren List Symbols}.
4011 The solo close paren of an argument list. @ref{Paren List Symbols}.
4013 Lines continuing a stream operator (C++ only). @ref{Literal
4014 Symbols}. @c @emph{FIXME!!! Can this not be moved somewhere better?}
4016 The line is nested inside a class definition. @ref{Class Symbols}.
4018 The start of a preprocessor macro definition. @ref{Literal Symbols}.
4019 @item cpp-define-intro
4020 The first line inside a multiline preproprocessor macro if
4021 @code{c-syntactic-indentation-in-macros} is set. @ref{Multiline Macro
4023 @item cpp-macro-cont
4024 All lines inside multiline preprocessor macros if
4025 @code{c-syntactic-indentation-in-macros} is @code{nil}.
4026 @ref{Multiline Macro Symbols}.
4028 A C++ friend declaration. @ref{Class Symbols}.
4029 @item objc-method-intro
4030 The first line of an Objective-C method definition. @ref{Objective-C
4032 @item objc-method-args-cont
4033 Lines continuing an Objective-C method definition. @ref{Objective-C
4035 @item objc-method-call-cont
4036 Lines continuing an Objective-C method call. @ref{Objective-C Method
4038 @item extern-lang-open
4039 Brace that opens an @code{extern} block (e.g. @code{extern "C"
4040 @{...@}}). @ref{External Scope Symbols}.
4041 @item extern-lang-close
4042 Brace that closes an @code{extern} block. @ref{External Scope
4045 Analogous to @code{inclass} syntactic symbol, but used inside
4046 @code{extern} blocks. @ref{External Scope Symbols}.
4047 @item namespace-open
4048 @itemx namespace-close
4050 These are analogous to the three @code{extern-lang} symbols above, but
4051 are returned for C++ namespace blocks. @ref{External Scope Symbols}.
4055 Analogous to the above, but for CORBA IDL @code{module} blocks.
4056 @ref{External Scope Symbols}.
4057 @item composition-open
4058 @itemx composition-close
4059 @itemx incomposition
4060 Analogous to the above, but for CORBA CIDL @code{composition} blocks.
4061 @ref{External Scope Symbols}.
4062 @item template-args-cont
4063 C++ template argument list continuations. @ref{Class Symbols}.
4065 Analogous to @code{inclass} syntactic symbol, but used inside lambda
4066 (i.e. anonymous) functions. Only used in Pike mode. @ref{Statement
4068 @item lambda-intro-cont
4069 Lines continuing the header of a lambda function, i.e. between the
4070 @code{lambda} keyword and the function body. Only used in Pike mode.
4071 @ref{Statement Block Symbols}.
4072 @item inexpr-statement
4073 A statement block inside an expression. The gcc C and C++ extension
4074 for this is recognized. It's also used for the special functions that
4075 take a statement block as an argument in Pike. @ref{Statement Block
4078 A class definition inside an expression. This is used for anonymous
4079 classes in Java. It's also used for anonymous array initializers in
4080 Java. @ref{Anonymous Class Symbol}.
4084 * Function Symbols::
4086 * Conditional Construct Symbols::
4087 * Switch Statement Symbols::
4088 * Brace List Symbols::
4089 * External Scope Symbols::
4090 * Paren List Symbols::
4092 * Multiline Macro Symbols::
4093 * Objective-C Method Symbols::
4094 * Anonymous Class Symbol::
4095 * Statement Block Symbols::
4099 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4100 @node Function Symbols, Class Symbols, Syntactic Symbols, Syntactic Symbols
4101 @comment node-name, next, previous, up
4102 @subsection Function Symbols
4103 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4105 This example shows a typical function declaration.
4109 2: swap( int& a, int& b )
4119 @ssindex topmost-intro
4120 @ssindex topmost-intro-cont
4122 @ssindex defun-close
4123 @ssindex defun-block-intro
4124 Line 1 shows a @code{topmost-intro} since it is the first line that
4125 introduces a top-level construct. Line 2 is a continuation of the
4126 top-level construct introduction so it has the syntax
4127 @code{topmost-intro-cont}. Line 3 shows a @code{defun-open} since it is
4128 the brace that opens a top-level function definition. Line 9 is the
4130 @code{defun-close} since it contains the brace that closes the top-level
4131 function definition. Line 4 is a @code{defun-block-intro}, i.e. it is
4132 the first line of a brace-block, enclosed in a
4133 top-level function definition.
4136 @ssindex statement-cont
4137 Lines 5, 6, and 7 are all given @code{statement} syntax since there
4138 isn't much special about them. Note however that line 8 is given
4139 @code{statement-cont} syntax since it continues the statement begun
4140 on the previous line.
4142 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4143 @node Class Symbols, Conditional Construct Symbols, Function Symbols, Syntactic Symbols
4144 @comment node-name, next, previous, up
4145 @subsection Class related Symbols
4146 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4148 Here's an example which illustrates some C++ class syntactic symbols:
4153 3: public Amplifiable
4157 7: : eString( new BassString( 0.105 )),
4158 8: aString( new BassString( 0.085 )),
4159 9: dString( new BassString( 0.065 )),
4160 10: gString( new BassString( 0.045 ))
4162 12: eString.tune( 'E' );
4163 13: aString.tune( 'A' );
4164 14: dString.tune( 'D' );
4165 15: gString.tune( 'G' );
4167 17: friend class Luthier;
4172 @ssindex class-close
4173 As in the previous example, line 1 has the @code{topmost-intro} syntax.
4174 Here however, the brace that opens a C++ class definition on line 4 is
4175 assigned the @code{class-open} syntax. Note that in C++, classes,
4176 structs, and unions are essentially equivalent syntactically (and are
4177 very similar semantically), so replacing the @code{class} keyword in the
4178 example above with @code{struct} or @code{union} would still result in a
4179 syntax of @code{class-open} for line 4 @footnote{This is the case even
4180 for C and Objective-C. For consistency, structs in all supported
4181 languages are syntactically equivalent to classes. Note however that
4182 the keyword @code{class} is meaningless in C and Objective-C.}.
4183 Similarly, line 18 is assigned @code{class-close} syntax.
4185 @ssindex inher-intro
4187 Line 2 introduces the inheritance list for the class so it is assigned
4188 the @code{inher-intro} syntax, and line 3, which continues the
4189 inheritance list is given @code{inher-cont} syntax.
4191 @ssindex access-label
4193 Hitting @kbd{C-c C-s} on line 5 shows the following analysis:
4196 ((inclass 58) (access-label 58))
4200 The primary syntactic symbol for this line is @code{access-label} as
4201 this a label keyword that specifies access protection in C++. However,
4202 because this line is also a top-level construct inside a class
4203 definition, the analysis actually shows two syntactic symbols. The
4204 other syntactic symbol assigned to this line is @code{inclass}.
4205 Similarly, line 6 is given both @code{inclass} and @code{topmost-intro}
4209 ((inclass 58) (topmost-intro 60))
4212 @ssindex member-init-intro
4213 @ssindex member-init-cont
4214 Line 7 introduces a C++ member initialization list and as such is given
4215 @code{member-init-intro} syntax. Note that in this case it is
4216 @emph{not} assigned @code{inclass} since this is not considered a
4217 top-level construct. Lines 8 through 10 are all assigned
4218 @code{member-init-cont} since they continue the member initialization
4219 list started on line 7.
4221 @cindex in-class inline methods
4222 @ssindex inline-open
4223 @ssindex inline-close
4224 Line 11's analysis is a bit more complicated:
4227 ((inclass 58) (inline-open))
4230 This line is assigned a syntax of both @code{inline-open} and
4231 @code{inclass} because it opens an @dfn{in-class} C++ inline method
4232 definition. This is distinct from, but related to, the C++ notion of an
4233 inline function in that its definition occurs inside an enclosing class
4234 definition, which in C++ implies that the function should be inlined.
4235 However, if the definition of the @code{Bass} constructor appeared
4236 outside the class definition, the construct would be given the
4237 @code{defun-open} syntax, even if the keyword @code{inline} appeared
4238 before the method name, as in:
4243 3: public Amplifiable
4251 11: : eString( new BassString( 0.105 )),
4252 12: aString( new BassString( 0.085 )),
4253 13: dString( new BassString( 0.065 )),
4254 14: gString( new BassString( 0.045 ))
4256 16: eString.tune( 'E' );
4257 17: aString.tune( 'A' );
4258 18: dString.tune( 'D' );
4259 19: gString.tune( 'G' );
4264 Returning to the previous example, line 16 is given @code{inline-close}
4265 syntax, while line 12 is given @code{defun-block-open} syntax, and lines
4266 13 through 15 are all given @code{statement} syntax. Line 17 is
4267 interesting in that its syntactic analysis list contains three
4271 ((inclass 58) (topmost-intro 380) (friend))
4274 The @code{friend} and @code{inline-open} syntactic symbols are
4275 modifiers that do not have anchor positions.
4277 @ssindex template-args-cont
4278 Template definitions introduce yet another syntactic symbol:
4281 1: ThingManager <int,
4282 2: Framework::Callback *,
4283 3: Mutex> framework_callbacks;
4286 Here, line 1 is analyzed as a @code{topmost-intro}, but lines 2 and 3
4287 are both analyzed as @code{template-args-cont} lines.
4289 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4290 @node Conditional Construct Symbols, Switch Statement Symbols, Class Symbols, Syntactic Symbols
4291 @comment node-name, next, previous, up
4292 @subsection Conditional Construct Symbols
4293 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4295 Here is a (totally contrived) example which illustrates how syntax is
4296 assigned to various conditional constructs:
4299 1: void spam( int index )
4301 3: for( int i=0; i<index; i++ )
4304 6: do_something_special();
4307 9: do_something( i );
4310 12: another_thing( i-- );
4316 Only the lines that illustrate new syntactic symbols will be discussed.
4318 @ssindex substatement-open
4319 @ssindex statement-block-intro
4320 @ssindex block-close
4321 Line 4 has a brace which opens a conditional's substatement block. It
4322 is thus assigned @code{substatement-open} syntax, and since line 5 is
4323 the first line in the substatement block, it is assigned
4324 @code{statement-block-intro} syntax. Line 10 contains the brace
4325 that closes the inner substatement block, and is therefore given the
4326 syntax @code{block-close}@footnote{@code{block-open} is used only for
4327 ``free-standing'' blocks, and is somewhat rare (@pxref{Literal
4328 Symbols} for an example.)}. Line 13 is treated the same way.
4330 @ssindex substatement
4331 Lines 6 and 9 are also substatements of conditionals, but since they
4332 don't start blocks they are given @code{substatement} syntax
4333 instead of @code{substatement-open}.
4335 @ssindex substatement-label
4336 Line 8 contains a label, which is normally given @code{label} syntax.
4337 This one is however a bit special since it's between a conditional and
4338 its substatement. It's analyzed as @code{substatement-label} to let you
4339 handle this rather odd case differently from normal labels.
4341 @ssindex else-clause
4342 @ssindex catch-clause
4343 Line 7 start with an @code{else} that matches the @code{if} statement on
4344 line 5. It is therefore given the @code{else-clause} syntax and is
4345 anchored on the matching @code{if}. The @code{try}-@code{catch}
4346 constructs in C++ and Java are treated this way too, except that
4347 @code{catch} and (in Java) @code{finally}, are marked with
4348 @code{catch-clause}.
4350 @ssindex do-while-closure
4351 The @code{while} construct on line 14 that closes a @code{do}
4352 conditional is given the special syntax @code{do-while-closure} if it
4353 appears on a line by itself. Note that if the @code{while} appeared on
4354 the same line as the preceding close brace, that line would still have
4355 @code{block-close} syntax.
4357 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4358 @node Switch Statement Symbols, Brace List Symbols, Conditional Construct Symbols, Syntactic Symbols
4359 @comment node-name, next, previous, up
4360 @subsection Switch Statement Symbols
4361 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4363 Switch statements have their own set of syntactic symbols. Here's an
4367 1: void spam( enum Ingredient i )
4374 8: drink_some_water();
4386 @ssindex statement-case-intro
4387 @ssindex statement-case-open
4388 Here, lines 4, 7, and 10 are all assigned @code{case-label} syntax,
4389 while lines 5 and 8 are assigned @code{statement-case-intro}. Line 11
4390 is treated slightly differently since it contains a brace that opens a
4391 block --- it is given @code{statement-case-open} syntax.
4393 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4394 @node Brace List Symbols, External Scope Symbols, Switch Statement Symbols, Syntactic Symbols
4395 @comment node-name, next, previous, up
4396 @subsection Brace List Symbols
4397 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4400 There are a set of syntactic symbols that are used to recognize
4401 constructs inside of brace lists. A brace list is defined as an
4402 @code{enum} or aggregate initializer list, such as might statically
4403 initialize an array of structs. The three special aggregate constructs
4404 in Pike, @code{(@{ @})}, @code{([ ])} and @code{(< >)}, are treated as
4405 brace lists too. An example:
4408 1: static char* ingredients[] =
4416 @ssindex brace-list-open
4417 @ssindex brace-list-intro
4418 @ssindex brace-list-close
4419 @ssindex brace-list-entry
4420 Following convention, line 2 in this example is assigned
4421 @code{brace-list-open} syntax, and line 3 is assigned
4422 @code{brace-list-intro} syntax. Likewise, line 6 is assigned
4423 @code{brace-list-close} syntax. Lines 4 and 5 however, are assigned
4424 @code{brace-list-entry} syntax, as would all subsequent lines in this
4427 @ssindex brace-entry-open
4428 Your static initializer might be initializing nested structures, for
4432 1: struct intpairs[] =
4445 Here, you've already seen the analysis of lines 1, 2, 3, and 11. On
4446 line 4, things get interesting; this line is assigned
4447 @code{brace-entry-open} syntactic symbol because it's a bracelist entry
4448 line that starts with an open brace. Lines 5 and 6 (and line 9) are
4449 pretty standard, and line 7 is a @code{brace-list-close} as you'd
4450 expect. Once again, line 8 is assigned as @code{brace-entry-open} as is
4453 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4454 @node External Scope Symbols, Paren List Symbols, Brace List Symbols, Syntactic Symbols
4455 @comment node-name, next, previous, up
4456 @subsection External Scope Symbols
4457 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4459 External language definition blocks also have their own syntactic
4460 symbols. In this example:
4465 3: int thing_one( int );
4466 4: int thing_two( double );
4470 @ssindex extern-lang-open
4471 @ssindex extern-lang-close
4472 @ssindex inextern-lang
4475 line 2 is given the @code{extern-lang-open} syntax, while line 5 is given
4476 the @code{extern-lang-close} syntax. The analysis for line 3 yields:
4479 ((inextern-lang) (topmost-intro 14))
4483 where @code{inextern-lang} is a modifier similar in purpose to
4486 There are various other top level blocks like @code{extern}, and they
4487 are all treated in the same way except that the symbols are named after
4488 the keyword that introduces the block. E.g. C++ namespace blocks get
4489 the three symbols @code{namespace-open}, @code{namespace-close} and
4490 @code{innamespace}. The currently recognized top level blocks are:
4493 @item @code{extern-lang-open}, @code{extern-lang-close}, @code{inextern-lang}
4494 @code{extern} blocks in C and C++.@footnote{These should logically be
4495 named @code{extern-open}, @code{extern-close} and @code{inextern}, but
4496 that isn't the case for historical reasons.}
4498 @item @code{namespace-open}, @code{namespace-close}, @code{innamespace}
4499 @ssindex namespace-open
4500 @ssindex namespace-close
4501 @ssindex innamespace
4502 @code{namespace} blocks in C++.
4504 @item @code{module-open}, @code{module-close}, @code{inmodule}
4505 @ssindex module-open
4506 @ssindex module-close
4508 @code{module} blocks in CORBA IDL.
4510 @item @code{composition-open}, @code{composition-close}, @code{incomposition}
4511 @ssindex composition-open
4512 @ssindex composition-close
4513 @ssindex incomposition
4514 @code{composition} blocks in CORBA CIDL.
4517 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4518 @node Paren List Symbols, Literal Symbols, External Scope Symbols, Syntactic Symbols
4519 @comment node-name, next, previous, up
4520 @subsection Parenthesis (Argument) List Symbols
4521 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4523 A number of syntactic symbols are associated with parenthesis lists,
4524 a.k.a argument lists, as found in function declarations and function
4525 calls. This example illustrates these:
4528 1: void a_function( int line1,
4531 4: void a_longer_function(
4536 9: void call_them( int line1, int line2 )
4543 16: a_longer_function( line1,
4548 @ssindex arglist-intro
4549 @ssindex arglist-close
4550 Lines 5 and 12 are assigned @code{arglist-intro} syntax since they are
4551 the first line following the open parenthesis, and lines 7 and 14 are
4552 assigned @code{arglist-close} syntax since they contain the parenthesis
4553 that closes the argument list.
4555 @ssindex arglist-cont-nonempty
4556 @ssindex arglist-cont
4557 Lines that continue argument lists can be assigned one of two syntactic
4558 symbols. For example, Lines 2 and 17
4559 are assigned @code{arglist-cont-nonempty} syntax. What this means
4560 is that they continue an argument list, but that the line containing the
4561 parenthesis that opens the list is @emph{not empty} following the open
4562 parenthesis. Contrast this against lines 6 and 13 which are assigned
4563 @code{arglist-cont} syntax. This is because the parenthesis that opens
4564 their argument lists is the last character on that line.
4566 Syntactic elements with @code{arglist-intro},
4567 @code{arglist-cont-nonempty}, and @code{arglist-close} contain two
4568 buffer positions: the anchor position (the beginning of the
4569 declaration or statement) and the position of the open parenthesis.
4570 The latter position can be used in a line-up function (@pxref{Line-Up
4573 Note that there is no @code{arglist-open} syntax. This is because any
4574 parenthesis that opens an argument list, appearing on a separate line,
4575 is assigned the @code{statement-cont} syntax instead.
4577 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4578 @node Literal Symbols, Multiline Macro Symbols, Paren List Symbols, Syntactic Symbols
4579 @comment node-name, next, previous, up
4580 @subsection Comment String Label and Macro Symbols
4581 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4583 A few miscellaneous syntactic symbols that haven't been previously
4584 covered are illustrated by this C++ example:
4587 1: void Bass::play( int volume )
4590 4: /* this line starts a multiline
4591 5: * comment. This line should get `c' syntax */
4593 7: char* a_multiline_string = "This line starts a multiline \
4594 8: string. This line should get `string' syntax.";
4602 16: cout << "I played "
4608 The lines to note in this example include:
4612 @ssindex func-decl-cont
4613 Line 2 is assigned the @code{func-decl-cont} syntax.
4616 @ssindex comment-intro
4617 Line 4 is assigned both @code{defun-block-intro} @emph{and}
4618 @code{comment-intro} syntax. A syntactic element with
4619 @code{comment-intro} has no anchor point --- It is always accompanied
4620 by another syntactic element which does have one.
4624 Line 5 is assigned @code{c} syntax.
4627 @cindex syntactic whitespace
4628 Line 6 which, even though it contains nothing but whitespace, is
4629 assigned @code{defun-block-intro}. Note that the appearance of the
4630 comment on lines 4 and 5 do not cause line 6 to be assigned
4631 @code{statement} syntax because comments are considered to be
4632 @dfn{syntactic whitespace}, which are ignored when analyzing
4637 Line 8 is assigned @code{string} syntax.
4641 Line 10 is assigned @code{label} syntax.
4645 Line 11 is assigned @code{block-open} as well as @code{statement}
4646 syntax. A @code{block-open} syntactic element doesn't have an anchor
4647 position, since it always appears with another syntactic element which
4652 Lines 12 and 14 are assigned @code{cpp-macro} syntax in addition to the
4653 normal syntactic symbols (@code{statement-block-intro} and
4654 @code{statement}, respectively). Normally @code{cpp-macro} is
4655 configured to cancel out the normal syntactic context to make all
4656 preprocessor directives stick to the first column, but that's easily
4657 changed if you want preprocessor directives to be indented like the rest
4658 of the code. Like @code{comment-intro}, a syntactic element with
4659 @code{cpp-macro} doesn't contain an anchor position.
4663 Line 17 is assigned @code{stream-op} syntax.
4666 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4667 @node Multiline Macro Symbols, Objective-C Method Symbols, Literal Symbols, Syntactic Symbols
4668 @comment node-name, next, previous, up
4669 @subsection Multiline Macro Symbols
4670 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4672 @cindex multiline macros
4673 @cindex syntactic whitespace
4674 @ssindex cpp-define-intro
4675 @ssindex cpp-macro-cont
4676 Multiline preprocessor macro definitions are normally handled just like
4677 other code, i.e. the lines inside them are indented according to the
4678 syntactic analysis of the preceding lines inside the macro. The first
4679 line inside a macro definition (i.e. the line after the starting line of
4680 the cpp directive itself) gets @code{cpp-define-intro}. In this example:
4683 1: #define LIST_LOOP(cons, listp) \
4684 2: for (cons = listp; !NILP (cons); cons = XCDR (cons)) \
4685 3: if (!CONSP (cons)) \
4686 4: signal_error ("Invalid list format", listp); \
4691 line 1 is given the syntactic symbol @code{cpp-macro}. The first line
4692 of a cpp directive is always given that symbol. Line 2 is given
4693 @code{cpp-define-intro}, so that you can give the macro body as a whole
4694 some extra indentation. Lines 3 through 5 are then analyzed as normal
4695 code, i.e. @code{substatement} on lines 3 and 4, and @code{else-clause}
4698 The syntactic analysis inside macros can be turned off with
4699 @code{c-syntactic-indentation-in-macros} (@pxref{Custom Macros}). In
4700 that case, lines 2 through 5 would all be given @code{cpp-macro-cont}
4701 with an anchor position pointing to the @code{#} which starts the cpp
4702 directive@footnote{This is how @ccmode{} 5.28 and earlier analyzed
4705 @xref{Custom Macros}, for more info about the treatment of macros.
4707 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4708 @node Objective-C Method Symbols, Anonymous Class Symbol, Multiline Macro Symbols, Syntactic Symbols
4709 @comment node-name, next, previous, up
4710 @subsection Objective-C Method Symbols
4711 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4713 In Objective-C buffers, there are three additional syntactic symbols
4714 assigned to various message calling constructs. Here's an example
4718 1: - (void)setDelegate:anObject
4721 4: [delegate masterWillRebind:self
4722 5: toDelegate:anObject
4723 6: withExtraStuff:stuff];
4727 @ssindex objc-method-intro
4728 @ssindex objc-method-args-cont
4729 @ssindex objc-method-call-cont
4730 Here, line 1 is assigned @code{objc-method-intro} syntax, and line 2 is
4731 assigned @code{objc-method-args-cont} syntax. Lines 5 and 6 are both
4732 assigned @code{objc-method-call-cont} syntax.
4734 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4735 @node Anonymous Class Symbol, Statement Block Symbols, Objective-C Method Symbols, Syntactic Symbols
4736 @comment node-name, next, previous, up
4737 @subsection Anonymous Class Symbol (Java)
4738 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4740 Java has a concept of anonymous classes which can look something like
4744 1: public void watch(Observable o) @{
4745 2: o.addObserver(new Observer() @{
4746 3: public void update(Observable o, Object arg) @{
4747 4: history.addElement(arg);
4753 @ssindex inexpr-class
4754 The brace following the @code{new} operator opens the anonymous class.
4755 Lines 3 and 6 are assigned the @code{inexpr-class} syntax, besides the
4756 @code{inclass} symbol used in normal classes. Thus, the class will be
4757 indented just like a normal class, with the added indentation given to
4758 @code{inexpr-class}. An @code{inexpr-class} syntactic element doesn't
4759 have an anchor position.
4761 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4762 @node Statement Block Symbols, K&R Symbols, Anonymous Class Symbol, Syntactic Symbols
4763 @comment node-name, next, previous, up
4764 @subsection Statement Block Symbols
4765 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4767 There are a few occasions where a statement block might be used inside
4768 an expression. One is in C or C++ code using the gcc extension for
4773 2: int y = foo (); int z;
4774 3: if (y > 0) z = y; else z = - y;
4779 @ssindex inexpr-statement
4780 Lines 2 and 5 get the @code{inexpr-statement} syntax, besides the
4781 symbols they'd get in a normal block. Therefore, the indentation put on
4782 @code{inexpr-statement} is added to the normal statement block
4783 indentation. An @code{inexpr-statement} syntactic element doesn't
4784 contain an anchor position.
4786 In Pike code, there are a few other situations where blocks occur inside
4787 statements, as illustrated here:
4792 3: string s = map (backtrace()[-2][3..],
4796 7: return sprintf ("%t", arg);
4797 8: @}) * ", " + "\n";
4799 10: write (s + "\n");
4805 @ssindex lambda-intro-cont
4806 Lines 4 through 8 contain a lambda function, which @ccmode{} recognizes
4807 by the @code{lambda} keyword. If the function argument list is put
4808 on a line of its own, as in line 5, it gets the @code{lambda-intro-cont}
4809 syntax. The function body is handled as an inline method body, with the
4810 addition of the @code{inlambda} syntactic symbol. This means that line
4811 6 gets @code{inlambda} and @code{inline-open}, and line 8 gets
4812 @code{inline-close}@footnote{You might wonder why it doesn't get
4813 @code{inlambda} too. It's because the closing brace is relative to the
4814 opening brace, which stands on its own line in this example. If the
4815 opening brace was hanging on the previous line, then the closing brace
4816 would get the @code{inlambda} syntax too to be indented correctly.}.
4818 @ssindex inexpr-statement
4819 On line 9, @code{catch} is a special function taking a statement block
4820 as its argument. The block is handled as an in-expression statement
4821 with the @code{inexpr-statement} syntax, just like the gcc extended C
4822 example above. The other similar special function, @code{gauge}, is
4823 handled like this too.
4825 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4826 @node K&R Symbols, , Statement Block Symbols, Syntactic Symbols
4827 @comment node-name, next, previous, up
4828 @subsection K&R Symbols
4829 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4831 @ssindex knr-argdecl-intro
4832 @ssindex knr-argdecl
4833 Two other syntactic symbols can appear in old style, non-prototyped C
4834 code @footnote{a.k.a. K&R C, or Kernighan & Ritchie C}:
4837 1: int add_three_integers(a, b, c)
4842 6: return a + b + c;
4846 Here, line 2 is the first line in an argument declaration list and so is
4847 given the @code{knr-argdecl-intro} syntactic symbol. Subsequent lines
4848 (i.e. lines 3 and 4 in this example), are given @code{knr-argdecl}
4852 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4853 @node Indentation Calculation, , Syntactic Symbols, Indentation Engine Basics
4854 @comment node-name, next, previous, up
4855 @section Indentation Calculation
4857 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4859 Indentation for a line is calculated from the syntactic context
4860 (@pxref{Syntactic Analysis}).
4862 First, a buffer position is found whose column will be the base for the
4863 indentation calculation. It's the anchor position in the first
4864 syntactic element that provides one that is used. If no syntactic
4865 element has an anchor position then column zero is used.
4867 Second, the syntactic symbols in each syntactic element are looked up
4868 in the @code{c-offsets-alist} style variable
4869 (@pxref{c-offsets-alist}), which is an association list of syntactic
4870 symbols and the offsets to apply for those symbols. These offsets are
4871 added together with the base column to produce the new indentation
4874 Let's use our two code examples above to see how this works. Here is
4875 our first example again:
4878 1: void swap( int& a, int& b )
4886 Let's say point is on line 3 and we hit the @key{TAB} key to reindent
4887 the line. The syntactic context for that line is:
4890 ((defun-block-intro 29))
4894 Since buffer position 29 is the first and only anchor position in the
4895 list, @ccmode{} goes there and asks for the current column. This brace
4896 is in column zero, so @ccmode{} uses @samp{0} as the base column.
4898 Next, @ccmode{} looks up @code{defun-block-intro} in the
4899 @code{c-offsets-alist} style variable. Let's say it finds the value
4900 @samp{4}; it adds this to the base column @samp{0}, yielding a running
4901 total indentation of 4 spaces.
4903 Since there is only one syntactic element on the list for this line,
4904 indentation calculation is complete, and the total indentation for the
4907 Here's another example:
4910 1: int add( int val, int incr, int doit )
4914 5: return( val + incr );
4920 If we were to hit @kbd{TAB} on line 4 in the above example, the same
4921 basic process is performed, despite the differences in the syntactic
4922 context. The context for this line is:
4925 ((substatement-open 46))
4928 Here, @ccmode{} goes to buffer position 46, which is the @samp{i} in
4929 @code{if} on line 3. This character is in the fourth column on that
4930 line so the base column is @samp{4}. Then @ccmode{} looks up the
4931 @code{substatement-open} symbol in @code{c-offsets-alist}. Let's say it
4932 finds the value @samp{4}. It's added with the base column and yields an
4933 indentation for the line of 8 spaces.
4937 Actually, it's a bit more complicated than that since the entries on
4938 @code{c-offsets-alist} can be much more than plain offsets.
4939 @xref{c-offsets-alist}, for the full story.
4941 Anyway, the mode usually just does The Right Thing without you having to
4942 think about it in this much detail. But when customizing indentation,
4943 it's helpful to understand the general indentation model being used.
4945 As you configure @ccmode{}, you might want to set the variable
4946 @code{c-echo-syntactic-information-p} to non-@code{nil} so that the
4947 syntactic context and calculated offset always is echoed in the
4948 minibuffer when you hit @kbd{TAB}.
4951 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4952 @node Customizing Indentation, Custom Macros, Indentation Engine Basics, Top
4953 @comment node-name, next, previous, up
4954 @chapter Customizing Indentation
4955 @cindex customization, indentation
4957 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4959 The principal variable for customizing indentation is the style
4960 variable @code{c-offsets-alist}, which gives an @dfn{offset} (an
4961 indentation rule) for each syntactic symbol. Its structure and
4962 semantics are completely described in @ref{c-offsets-alist}. The
4963 various ways you can set the variable, including the use of the
4964 @ccmode{} style system, are described in @ref{Config Basics} and its
4965 sections, in particular @ref{Style Variables}.
4967 The simplest and most used kind of ``offset'' setting in
4968 @code{c-offsets-alist} is in terms of multiples of
4969 @code{c-basic-offset}:
4971 @defopt c-basic-offset
4972 @vindex basic-offset (c-)
4973 This style variable holds the basic offset between indentation levels.
4974 It's factory default is 4, but all the built-in styles set it
4975 themselves, to some value between 2 (for @code{gnu} style) and 8 (for
4976 @code{bsd}, @code{linux}, and @code{python} styles).
4979 The most flexible ``offset'' setting you can make in
4980 @code{c-offsets-alist} is a line-up function (or even a list of them),
4981 either one supplied by @ccmode{} (@pxref{Line-Up Functions}) or one
4982 you write yourself (@pxref{Custom Line-Up}).
4984 Finally, in @ref{Other Indentation} you'll find the tool of last
4985 resort: a hook which is called after a line has been indented. You
4986 can install functions here to make ad-hoc adjustments to any line's
4991 * Interactive Customization::
4992 * Line-Up Functions::
4994 * Other Indentation::
4998 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4999 @node c-offsets-alist, Interactive Customization, Customizing Indentation, Customizing Indentation
5000 @comment node-name, next, previous, up
5001 @section c-offsets-alist
5002 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5004 This section explains the structure and semantics of the style
5005 variable @code{c-offset-alist}, the principal variable for configuring
5006 indentation. Details of how to set it up, and its relationship to
5007 @ccmode{}'s style system are given in @ref{Style Variables}.
5009 @defopt c-offsets-alist
5010 @vindex offsets-alist (c-)
5011 This is an alist which associates an offset with each syntactic
5012 symbol. This @dfn{offset} is a rule specifying how to indent a line
5013 whose syntactic context matches the symbol. @xref{Syntactic
5016 Note that the buffer-local binding of this alist in a @ccmode{} buffer
5017 contains an entry for @emph{every} syntactic symbol. Its global
5018 binding and its settings within style specifications usually contain
5019 only a few entries. @xref{Style Variables}.
5021 The offset specification associated with any particular syntactic
5022 symbol can be an integer, a variable name, a vector, a function or
5023 lambda expression, a list, or one of the following special symbols:
5024 @code{+}, @code{-}, @code{++}, @code{--}, @code{*}, or @code{/}. The
5025 meanings of these values are described in detail below.
5027 Here is an example fragment of a @code{c-offsets-alist}, showing some
5028 of these kinds of offsets:
5034 (topmost-intro-cont . c-lineup-topmost-intro-cont)
5035 (statement-block-intro . (add c-lineup-whitesmith-in-block
5036 c-indent-multi-line-block))
5042 @deffn Command c-set-offset (@kbd{C-c C-o})
5043 @findex set-offset (c-)
5045 This command changes the entry for a syntactic symbol in the current
5046 binding of @code{c-offsets-alist}, or it inserts a new entry if there
5047 isn't already one for that syntactic symbol.
5049 You can use @code{c-set-offsets} interactively within a @ccmode{}
5050 buffer to make experimental changes to your indentation settings.
5051 @kbd{C-c C-o} prompts you for the syntactic symbol to change
5052 (defaulting to that of the current line) and the new offset
5053 (defaulting to the current offset).
5055 @code{c-set-offsets} takes two arguments when used programmatically:
5056 @var{symbol}, the syntactic element symbol to change and @var{offset},
5057 the new offset for that syntactic element. You can call the command
5058 in your @file{.emacs} to change the global binding of
5059 @code{c-offsets-alist} (@pxref{Style Variables}); you can use it in a
5060 hook function to make changes from the current style. @ccmode{}
5061 itself uses this function when initializing styles.
5064 @cindex offset specification
5065 The ``offset specifications'' in @code{c-offsets-alist} can be any of
5070 The integer specifies a relative offset. All relative
5071 offsets@footnote{The syntactic context @code{@w{((defun-block-intro
5072 2724) (comment-intro))}} would likely have two relative offsets.} will
5073 be added together and used to calculate the indentation relative to an
5074 anchor position earlier in the buffer. @xref{Indentation
5075 Calculation}, for details. Most of the time, it's probably better to
5076 use one of the special symbols like @code{+} than an integer (apart
5079 @item One of the symbols @code{+}, @code{-}, @code{++}, @code{--}, @code{*}, or @code{/}
5080 These special symbols describe a relative offset in multiples of
5081 @code{c-basic-offset}:
5083 By defining a style's indentation in terms of @code{c-basic-offset},
5084 you can change the amount of whitespace given to an indentation level
5085 while maintaining the same basic shape of your code. Here are the
5086 values that the special symbols correspond to:
5090 @code{c-basic-offset} times 1
5092 @code{c-basic-offset} times -1
5094 @code{c-basic-offset} times 2
5096 @code{c-basic-offset} times -2
5098 @code{c-basic-offset} times 0.5
5100 @code{c-basic-offset} times -0.5
5104 The first element of the vector, an integer, sets the absolute
5105 indentation column. This will override any previously calculated
5106 indentation, but won't override relative indentation calculated from
5107 syntactic elements later on in the syntactic context of the line being
5108 indented. @xref{Indentation Calculation}. Any elements in the vector
5109 beyond the first will be ignored.
5111 @item A function or lambda expression
5112 The function will be called and its return value will in turn be
5113 evaluated as an offset specification. Functions are useful when more
5114 context than just the syntactic symbol is needed to get the desired
5115 indentation. @xref{Line-Up Functions}, and @ref{Custom Line-Up}, for
5118 @item A symbol with a variable binding
5119 If the symbol also has a function binding, the function takes
5120 precedence over the variable. Otherwise the value of the variable is
5121 used. It must be an integer (which is used as relative offset) or a
5122 vector (an absolute offset).
5125 The offset can also be a list containing several offset
5126 specifications; these are evaluated recursively and combined. A list
5127 is typically only useful when some of the offsets are line-up
5128 functions. A common strategy is calling a sequence of functions in
5129 turn until one of them recognizes that it is appropriate for the
5130 source line and returns a non-@code{nil} value.
5132 @code{nil} values are always ignored when the offsets are combined.
5133 The first element of the list specifies the method of combining the
5134 non-@code{nil} offsets from the remaining elements:
5138 Use the first offset that doesn't evaluate to @code{nil}. Subsequent
5139 elements of the list don't get evaluated.
5141 Use the minimum of all the offsets. All must be either relative or
5142 absolute - they can't be mixed.
5144 Use the maximum of all the offsets. All must be either relative or
5145 absolute - they can't be mixed.
5147 Add all the evaluated offsets together. Exactly one of them may be
5148 absolute, in which case the result is absolute. Any relative offsets
5149 that preceded the absolute one in the list will be ignored in that case.
5152 As a compatibility measure, if the first element is none of the above
5153 then it too will be taken as an offset specification and the whole list
5154 will be combined according to the method @code{first}.
5157 @vindex c-strict-syntax-p
5158 @vindex strict-syntax-p (c-)
5159 If an offset specification evaluates to @code{nil}, then a relative
5160 offset of 0 (zero) is used@footnote{There is however a variable
5161 @code{c-strict-syntax-p} that when set to non-@code{nil} will cause an
5162 error to be signaled in that case. It's now considered obsolete since
5163 it doesn't work well with some of the alignment functions that returns
5164 @code{nil} instead of zero. You should therefore leave
5165 @code{c-strict-syntax-p} set to @code{nil}.}.
5167 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5168 @node Interactive Customization, Line-Up Functions, c-offsets-alist, Customizing Indentation
5169 @comment node-name, next, previous, up
5170 @section Interactive Customization
5171 @cindex customization, interactive
5172 @cindex interactive customization
5173 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5175 As an example of how to customize indentation, let's change the
5176 style of this example@footnote{In this and subsequent examples, the
5177 original code is formatted using the @samp{gnu} style unless otherwise
5178 indicated. @xref{Styles}.}:
5182 1: int add( int val, int incr, int doit )
5186 5: return( val + incr );
5198 1: int add( int val, int incr, int doit )
5202 5: return( val + incr );
5209 In other words, we want to change the indentation of braces that open a
5210 block following a condition so that the braces line up under the
5211 conditional, instead of being indented. Notice that the construct we
5212 want to change starts on line 4. To change the indentation of a line,
5213 we need to see which syntactic symbols affect the offset calculations
5214 for that line. Hitting @kbd{C-c C-s} on line 4 yields:
5217 ((substatement-open 44))
5221 so we know that to change the offset of the open brace, we need to
5222 change the indentation for the @code{substatement-open} syntactic
5225 To do this interactively, just hit @kbd{C-c C-o}. This prompts
5226 you for the syntactic symbol to change, providing a reasonable default.
5227 In this case, the default is @code{substatement-open}, which is just the
5228 syntactic symbol we want to change!
5230 After you hit return, @ccmode{} will then prompt you for the new
5231 offset value, with the old value as the default. The default in this
5232 case is @samp{+}, but we want no extra indentation so enter
5233 @samp{0} and @kbd{RET}. This will associate the offset 0 with the
5234 syntactic symbol @code{substatement-open}.
5236 To check your changes quickly, just hit @kbd{C-c C-q}
5237 (@code{c-indent-defun}) to reindent the entire function. The example
5238 should now look like:
5242 1: int add( int val, int incr, int doit )
5246 5: return( val + incr );
5253 Notice how just changing the open brace offset on line 4 is all we
5254 needed to do. Since the other affected lines are indented relative to
5255 line 4, they are automatically indented the way you'd expect. For more
5256 complicated examples, this might not always work. The general approach
5257 to take is to always start adjusting offsets for lines higher up in the
5258 file, then reindent and see if any following lines need further
5261 @c Move this bit to "Styles" (2005/10/7)
5262 @deffn Command c-set-offset symbol offset
5263 @findex set-offset (c-)
5265 This is the command bound to @kbd{C-c C-o}. It provides a convenient
5266 way to set offsets on @code{c-offsets-alist} both interactively (see
5267 the example above) and from your mode hook.
5269 It takes two arguments when used programmatically: @var{symbol} is the
5270 syntactic element symbol to change and @var{offset} is the new offset
5271 for that syntactic element.
5273 @c End of MOVE THIS BIT.
5275 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5276 @node Line-Up Functions, Custom Line-Up, Interactive Customization, Customizing Indentation
5277 @comment node-name, next, previous, up
5278 @section Line-Up Functions
5279 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5281 @cindex line-up function
5282 @cindex indentation function
5283 Often there are cases when a simple offset setting on a syntactic
5284 symbol isn't enough to get the desired indentation---for example, you
5285 might want to line up a closing parenthesis with the matching opening
5286 one rather than indenting relative to its ``anchor point''. @ccmode{}
5287 provides this flexibility with @dfn{line-up functions}.
5289 The way you associate a line-up function with a syntactic symbol is
5290 described in @ref{c-offsets-alist}. @ccmode{} comes with many
5291 predefined line-up functions for common situations. If none of these
5292 does what you want, you can write your own. @xref{Custom Line-Up}.
5293 Sometimes, it is easier to tweak the standard indentation by adding a
5294 function to @code{c-special-indent-hook} (@pxref{Other Indentation}).
5296 The line-up functions haven't been adapted for AWK buffers or tested
5297 with them. Some of them might work serendipitously. There shouldn't be
5298 any problems writing custom line-up functions for AWK mode.
5300 The calling convention for line-up functions is described fully in
5301 @ref{Custom Line-Up}. Roughly speaking, the return value is either an
5302 offset itself (such as @code{+} or @code{[0]}) or it's @code{nil},
5303 meaning ``this function is inappropriate in this case - try a
5304 different one''. @xref{c-offsets-alist}.
5306 The subsections below describe all the standard line-up functions,
5307 categorized by the sort of token the lining-up centres around. For
5308 each of these functions there is a ``works with'' list that indicates
5309 which syntactic symbols the function is intended to be used with.
5312 @emph{Works with:@ }
5321 @macro sssTBasicOffset
5322 <--> @i{c-basic-offset}@c
5325 @macro sssTsssTBasicOffset
5326 <--><--> @i{c-basic-offset}@c
5333 @c The TeX backend seems to insert extra spaces around the argument. :P
5342 * Brace/Paren Line-Up::
5344 * Operator Line-Up::
5349 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5350 @node Brace/Paren Line-Up, List Line-Up, Line-Up Functions, Line-Up Functions
5351 @comment node-name, next, previous, up
5352 @subsection Brace and Parenthesis Line-Up Functions
5353 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5355 The line-up functions here calculate the indentation for braces,
5356 parentheses and statements within brace blocks.
5358 @defun c-lineup-close-paren
5359 @findex lineup-close-paren (c-)
5360 Line up the closing paren under its corresponding open paren if the
5361 open paren is followed by code. If the open paren ends its line, no
5362 indentation is added. E.g:
5368 ) @hereFn{c-lineup-close-paren}
5379 ) @hereFn{c-lineup-close-paren}
5383 As a special case, if a brace block is opened at the same line as the
5384 open parenthesis of the argument list, the indentation is
5385 @code{c-basic-offset} instead of the open paren column. See
5386 @code{c-lineup-arglist} for further discussion of this ``DWIM'' measure.
5388 @workswith All @code{*-close} symbols.
5391 @comment ------------------------------------------------------------
5393 @anchor{c-lineup-arglist-close-under-paren}
5394 @defun c-lineup-arglist-close-under-paren
5395 @findex lineup-arglist-close-under-paren (c-)
5396 Set your @code{arglist-close} syntactic symbol to this line-up function
5397 so that parentheses that close argument lists will line up under the
5398 parenthesis that opened the argument list. It can also be used with
5399 @code{arglist-cont} and @code{arglist-cont-nonempty} to line up all
5400 lines inside a parenthesis under the open paren.
5402 As a special case, if a brace block is opened at the same line as the
5403 open parenthesis of the argument list, the indentation is
5404 @code{c-basic-offset} only. See @code{c-lineup-arglist} for further
5405 discussion of this ``DWIM'' measure.
5407 @workswith Almost all symbols, but are typically most useful on
5408 @code{arglist-close}, @code{brace-list-close}, @code{arglist-cont} and
5409 @code{arglist-cont-nonempty}.
5412 @comment ------------------------------------------------------------
5414 @defun c-indent-one-line-block
5415 @findex indent-one-line-block (c-)
5416 Indent a one line block @code{c-basic-offset} extra. E.g:
5421 @{m+=n; n=0;@} @hereFn{c-indent-one-line-block}
5432 @{ @hereFn{c-indent-one-line-block}
5438 The block may be surrounded by any kind of parenthesis characters.
5439 @code{nil} is returned if the line doesn't start with a one line block,
5440 which makes the function usable in list expressions.
5442 @workswith Almost all syntactic symbols, but most useful on the
5443 @code{-open} symbols.
5446 @comment ------------------------------------------------------------
5448 @defun c-indent-multi-line-block
5449 @findex indent-multi-line-block (c-)
5450 Indent a multiline block @code{c-basic-offset} extra. E.g:
5456 @{17@}, @hereFn{c-indent-multi-line-block}
5467 @{ @hereFn{c-indent-multi-line-block}
5474 The block may be surrounded by any kind of parenthesis characters.
5475 @code{nil} is returned if the line doesn't start with a multiline
5476 block, which makes the function usable in list expressions.
5478 @workswith Almost all syntactic symbols, but most useful on the
5479 @code{-open} symbols.
5482 @comment ------------------------------------------------------------
5484 @defun c-lineup-runin-statements
5485 @findex lineup-runin-statements (c-)
5486 Line up statements for coding standards which place the first statement
5487 in a block on the same line as the block opening brace@footnote{Run-in
5488 style doesn't really work too well. You might need to write your own
5489 custom line-up functions to better support this style.}. E.g:
5495 return 0; @hereFn{c-lineup-runin-statements}
5500 If there is no statement after the opening brace to align with,
5501 @code{nil} is returned. This makes the function usable in list
5504 @workswith The @code{statement} syntactic symbol.
5507 @comment ------------------------------------------------------------
5509 @defun c-lineup-inexpr-block
5510 @findex lineup-inexpr-block (c-)
5511 This can be used with the in-expression block symbols to indent the
5512 whole block to the column where the construct is started. E.g. for Java
5513 anonymous classes, this lines up the class under the @samp{new} keyword,
5514 and in Pike it lines up the lambda function body under the @samp{lambda}
5515 keyword. Returns @code{nil} if the block isn't part of such a
5518 @workswith @code{inlambda}, @code{inexpr-statement},
5519 @code{inexpr-class}.
5522 @comment ------------------------------------------------------------
5524 @defun c-lineup-after-whitesmith-blocks
5525 @findex lineup-after-whitesmith-blocks (c-)
5526 Compensate for Whitesmith style indentation of blocks. Due to the way
5527 @ccmode{} calculates anchor positions for normal lines inside blocks,
5528 this function is necessary for those lines to get correct Whitesmith
5529 style indentation. Consider the following examples:
5536 x; @hereFn{c-lineup-after-whitesmith-blocks}
5547 x; @hereFn{c-lineup-after-whitesmith-blocks}
5551 The fact that the line with @code{x} is preceded by a Whitesmith style
5552 indented block in the latter case and not the first should not affect
5553 its indentation. But since CC Mode in cases like this uses the
5554 indentation of the preceding statement as anchor position, the @code{x}
5555 would in the second case be indented too much if the offset for
5556 @code{statement} was set simply to zero.
5558 This lineup function corrects for this situation by detecting if the
5559 anchor position is at an open paren character. In that case, it instead
5560 indents relative to the surrounding block just like
5561 @code{c-lineup-whitesmith-in-block}.
5563 @workswith @code{brace-list-entry}, @code{brace-entry-open},
5564 @code{statement}, @code{arglist-cont}.
5567 @comment ------------------------------------------------------------
5569 @defun c-lineup-whitesmith-in-block
5570 @findex lineup-whitesmith-in-block (c-)
5571 Line up lines inside a block in Whitesmith style. It's done in a way
5572 that works both when the opening brace hangs and when it doesn't. E.g:
5578 foo; @hereFn{c-lineup-whitesmith-in-block}
5589 foo; @hereFn{c-lineup-whitesmith-in-block}
5595 In the first case the indentation is kept unchanged, in the second
5596 @code{c-basic-offset} is added.
5598 @workswith @code{defun-close}, @code{defun-block-intro},
5599 @code{inline-close}, @code{block-close}, @code{brace-list-close},
5600 @code{brace-list-intro}, @code{statement-block-intro},
5601 @code{arglist-intro}, @code{arglist-cont-nonempty},
5602 @code{arglist-close}, and all @code{in*} symbols, e.g. @code{inclass}
5603 and @code{inextern-lang}.
5606 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5607 @node List Line-Up, Operator Line-Up, Brace/Paren Line-Up, Line-Up Functions
5608 @comment node-name, next, previous, up
5609 @subsection List Line-Up Functions
5610 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5612 The line-up functions here calculate the indentation for lines which
5613 form lists of items, usually separated by commas.
5615 The function @ref{c-lineup-arglist-close-under-paren}, which is mainly
5616 for indenting a close parenthesis, is also useful for the lines
5617 contained within parentheses.
5619 @defun c-lineup-arglist
5620 @findex lineup-arglist (c-)
5621 Line up the current argument line under the first argument.
5623 As a special case, if an argument on the same line as the open
5624 parenthesis starts with a brace block opener, the indentation is
5625 @code{c-basic-offset} only. This is intended as a ``DWIM'' measure in
5626 cases like macros that contain statement blocks, e.g:
5630 A_VERY_LONG_MACRO_NAME (@{
5631 some (code, with + long, lines * in[it]);
5637 This is motivated partly because it's more in line with how code
5638 blocks are handled, and partly since it approximates the behavior of
5639 earlier CC Mode versions, which due to inaccurate analysis tended to
5640 indent such cases this way.
5642 @workswith @code{arglist-cont-nonempty}, @code{arglist-close}.
5645 @comment ------------------------------------------------------------
5647 @defun c-lineup-arglist-intro-after-paren
5648 @findex lineup-arglist-intro-after-paren (c-)
5649 Line up a line to just after the open paren of the surrounding paren or
5652 @workswith @code{defun-block-intro}, @code{brace-list-intro},
5653 @code{statement-block-intro}, @code{statement-case-intro},
5654 @code{arglist-intro}.
5657 @comment ------------------------------------------------------------
5659 @defun c-lineup-multi-inher
5660 @findex lineup-multi-inher (c-)
5661 Line up the classes in C++ multiple inheritance clauses and member
5662 initializers under each other. E.g:
5666 Foo::Foo (int a, int b):
5668 Bar (b) @hereFn{c-lineup-multi-inher}
5679 public Bar @hereFn{c-lineup-multi-inher}
5688 Foo::Foo (int a, int b)
5690 , Bar (b) @hereFn{c-lineup-multi-inher}
5694 @workswith @code{inher-cont}, @code{member-init-cont}.
5697 @comment ------------------------------------------------------------
5699 @defun c-lineup-java-inher
5700 @findex lineup-java-inher (c-)
5701 Line up Java implements and extends declarations. If class names
5702 follow on the same line as the @samp{implements}/@samp{extends}
5703 keyword, they are lined up under each other. Otherwise, they are
5704 indented by adding @code{c-basic-offset} to the column of the keyword.
5711 Bar @hereFn{c-lineup-java-inher}
5723 Bar @hereFn{c-lineup-java-inher}
5727 @workswith @code{inher-cont}.
5730 @comment ------------------------------------------------------------
5732 @defun c-lineup-java-throws
5733 @findex lineup-java-throws (c-)
5734 Line up Java throws declarations. If exception names follow on the
5735 same line as the throws keyword, they are lined up under each other.
5736 Otherwise, they are indented by adding @code{c-basic-offset} to the
5737 column of the @samp{throws} keyword. The @samp{throws} keyword itself
5738 is also indented by @code{c-basic-offset} from the function declaration
5739 start if it doesn't hang. E.g:
5744 throws @hereFn{c-lineup-java-throws}
5745 Bar @hereFn{c-lineup-java-throws}
5746 @sssTsssTBasicOffset{}
5755 int foo() throws Cyphr,
5756 Bar, @hereFn{c-lineup-java-throws}
5757 Vlod @hereFn{c-lineup-java-throws}
5761 @workswith @code{func-decl-cont}.
5764 @comment ------------------------------------------------------------
5766 @defun c-lineup-template-args
5767 @findex lineup-template-args (c-)
5768 Line up the arguments of a template argument list under each other, but
5769 only in the case where the first argument is on the same line as the
5772 To allow this function to be used in a list expression, @code{nil} is
5773 returned if there's no template argument on the first line.
5775 @workswith @code{template-args-cont}.
5778 @comment ------------------------------------------------------------
5780 @defun c-lineup-ObjC-method-call
5781 @findex lineup-ObjC-method-call (c-)
5782 For Objective-C code, line up selector args as Emacs Lisp mode does
5783 with function args: go to the position right after the message receiver,
5784 and if you are at the end of the line, indent the current line
5785 c-basic-offset columns from the opening bracket; otherwise you are
5786 looking at the first character of the first method call argument, so
5787 lineup the current line with it.
5789 @workswith @code{objc-method-call-cont}.
5792 @comment ------------------------------------------------------------
5794 @defun c-lineup-ObjC-method-args
5795 @findex lineup-ObjC-method-args (c-)
5796 For Objective-C code, line up the colons that separate args. The colon
5797 on the current line is aligned with the one on the first line.
5799 @workswith @code{objc-method-args-cont}.
5802 @comment ------------------------------------------------------------
5804 @defun c-lineup-ObjC-method-args-2
5805 @findex lineup-ObjC-method-args-2 (c-)
5806 Similar to @code{c-lineup-ObjC-method-args} but lines up the colon on
5807 the current line with the colon on the previous line.
5809 @workswith @code{objc-method-args-cont}.
5812 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5813 @node Operator Line-Up, Comment Line-Up, List Line-Up, Line-Up Functions
5814 @comment node-name, next, previous, up
5815 @subsection Operator Line-Up Functions
5816 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5818 The line-up functions here calculate the indentation for lines which
5819 start with an operator, by lining it up with something on the previous
5822 @defun c-lineup-argcont
5823 @findex lineup-argcont (c-)
5824 Line up a continued argument. E.g:
5828 foo (xyz, aaa + bbb + ccc
5829 + ddd + eee + fff); @hereFn{c-lineup-argcont}
5833 Only continuation lines like this are touched, @code{nil} is returned on
5834 lines which are the start of an argument.
5836 Within a gcc @code{asm} block, @code{:} is recognised as an argument
5837 separator, but of course only between operand specifications, not in the
5838 expressions for the operands.
5840 @workswith @code{arglist-cont}, @code{arglist-cont-nonempty}.
5843 @comment ------------------------------------------------------------
5845 @defun c-lineup-arglist-operators
5846 @findex lineup-arglist-operators (c-)
5847 Line up lines starting with an infix operator under the open paren.
5848 Return @code{nil} on lines that don't start with an operator, to leave
5849 those cases to other line-up functions. Example:
5854 || at_limit (x, @hereFn{c-lineup-arglist-operators}
5855 list) @hereFn{c-lineup-arglist-operators@r{ returns nil}}
5860 Since this function doesn't do anything for lines without an infix
5861 operator you typically want to use it together with some other lineup
5862 settings, e.g. as follows (the @code{arglist-close} setting is just a
5863 suggestion to get a consistent style):
5866 (c-set-offset 'arglist-cont
5867 '(c-lineup-arglist-operators 0))
5868 (c-set-offset 'arglist-cont-nonempty
5869 '(c-lineup-arglist-operators c-lineup-arglist))
5870 (c-set-offset 'arglist-close
5871 '(c-lineup-arglist-close-under-paren))
5874 @workswith @code{arglist-cont}, @code{arglist-cont-nonempty}.
5877 @comment ------------------------------------------------------------
5879 @defun c-lineup-assignments
5880 @findex lineup-assignments (c-)
5881 Line up the current line after the assignment operator on the first line
5882 in the statement. If there isn't any, return nil to allow stacking with
5883 other line-up functions. If the current line contains an assignment
5884 operator too, try to align it with the first one.
5886 @workswith @code{topmost-intro-cont}, @code{statement-cont},
5887 @code{arglist-cont}, @code{arglist-cont-nonempty}.
5891 @comment ------------------------------------------------------------
5893 @defun c-lineup-math
5894 @findex lineup-math (c-)
5895 Like @code{c-lineup-assignments} but indent with @code{c-basic-offset}
5896 if no assignment operator was found on the first line. I.e. this
5897 function is the same as specifying a list @code{(c-lineup-assignments
5898 +)}. It's provided for compatibility with old configurations.
5900 @workswith @code{topmost-intro-cont}, @code{statement-cont},
5901 @code{arglist-cont}, @code{arglist-cont-nonempty}.
5904 @comment ------------------------------------------------------------
5906 @defun c-lineup-cascaded-calls
5907 @findex lineup-cascaded-calls (c-)
5908 Line up ``cascaded calls'' under each other. If the line begins with
5909 @code{->} or @code{.} and the preceding line ends with one or more
5910 function calls preceded by the same token, then the arrow is lined up
5911 with the first of those tokens. E.g:
5915 r = proc->add(17)->add(18)
5916 ->add(19) + @hereFn{c-lineup-cascaded-calls}
5917 offset; @hereFn{c-lineup-cascaded-calls@r{ (inactive)}}
5921 In any other situation @code{nil} is returned to allow use in list
5924 @workswith @code{topmost-intro-cont}, @code{statement-cont},
5925 @code{arglist-cont}, @code{arglist-cont-nonempty}.
5928 @comment ------------------------------------------------------------
5930 @defun c-lineup-streamop
5931 @findex lineup-streamop (c-)
5932 Line up C++ stream operators (i.e. @samp{<<} and @samp{>>}).
5934 @workswith @code{stream-op}.
5937 @comment ------------------------------------------------------------
5939 @defun c-lineup-string-cont
5940 @findex lineup-string-cont (c-)
5941 Line up a continued string under the one it continues. A continued
5942 string in this sense is where a string literal follows directly after
5947 result = prefix + "A message "
5948 "string."; @hereFn{c-lineup-string-cont}
5952 @code{nil} is returned in other situations, to allow stacking with other
5955 @workswith @code{topmost-intro-cont}, @code{statement-cont},
5956 @code{arglist-cont}, @code{arglist-cont-nonempty}.
5960 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5961 @node Comment Line-Up, Misc Line-Up, Operator Line-Up, Line-Up Functions
5962 @comment node-name, next, previous, up
5963 @subsection Comment Line-Up Functions
5964 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
5966 The lineup functions here calculate the indentation for several types
5967 of comment structure.
5969 @defun c-lineup-C-comments
5970 @findex lineup-C-comments (c-)
5971 Line up C block comment continuation lines. Various heuristics are used
5972 to handle most of the common comment styles. Some examples:
5985 text ** text ** text
5992 /**************************************************
5994 *************************************************/
5998 @vindex comment-start-skip
6001 /**************************************************
6002 Free form text comments:
6003 In comments with a long delimiter line at the
6004 start, the indentation is kept unchanged for lines
6005 that start with an empty comment line prefix. The
6006 delimiter line is whatever matches the
6007 @code{comment-start-skip} regexp.
6008 **************************************************/
6012 The style variable @code{c-comment-prefix-regexp} is used to recognize
6013 the comment line prefix, e.g. the @samp{*} that usually starts every
6014 line inside a comment.
6016 @workswith The @code{c} syntactic symbol.
6019 @comment ------------------------------------------------------------
6021 @defun c-lineup-comment
6022 @findex lineup-comment (c-)
6023 Line up a comment-only line according to the style variable
6024 @code{c-comment-only-line-offset}. If the comment is lined up with a
6025 comment starter on the previous line, that alignment is preserved.
6027 @defopt c-comment-only-line-offset
6028 @vindex comment-only-line-offset (c-)
6029 This style variable specifies the extra offset for the line. It can
6030 contain an integer or a cons cell of the form
6033 (@r{@var{non-anchored-offset}} . @r{@var{anchored-offset}})
6037 where @var{non-anchored-offset} is the amount of offset given to
6038 non-column-zero anchored lines, and @var{anchored-offset} is the amount
6039 of offset to give column-zero anchored lines. Just an integer as value
6040 is equivalent to @code{(@r{@var{value}} . -1000)}.
6043 @workswith @code{comment-intro}.
6046 @comment ------------------------------------------------------------
6048 @defun c-lineup-knr-region-comment
6049 @findex lineup-knr-region-comment (c-)
6050 Line up a comment in the ``K&R region'' with the declaration. That is
6051 the region between the function or class header and the beginning of the
6057 /* Called at startup. */ @hereFn{c-lineup-knr-region-comment}
6064 Return @code{nil} if called in any other situation, to be useful in list
6067 @workswith @code{comment-intro}.
6070 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6071 @node Misc Line-Up, , Comment Line-Up, Line-Up Functions
6072 @comment node-name, next, previous, up
6073 @subsection Miscellaneous Line-Up Functions
6074 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6076 The line-up functions here are the odds and ends which didn't fit into
6077 any earlier category.
6079 @defun c-lineup-dont-change
6080 @findex lineup-dont-change (c-)
6081 This lineup function makes the line stay at whatever indentation it
6082 already has; think of it as an identity function for lineups.
6084 @workswith Any syntactic symbol.
6087 @comment ------------------------------------------------------------
6089 @defun c-lineup-cpp-define
6090 @findex lineup-cpp-define (c-)
6091 Line up macro continuation lines according to the indentation of the
6092 construct preceding the macro. E.g:
6096 const char msg[] = @hereFn{@r{The beginning of the preceding construct.}}
6100 do @{ \ @hereFn{c-lineup-cpp-define}
6112 if (!running) @hereFn{@r{The beginning of the preceding construct.}}
6113 error(\"Not running!\");
6116 do @{ \ @hereFn{c-lineup-cpp-define}
6122 If @code{c-syntactic-indentation-in-macros} is non-@code{nil}, the
6123 function returns the relative indentation to the macro start line to
6124 allow accumulation with other offsets. E.g. in the following cases,
6125 @code{cpp-define-intro} is combined with the
6126 @code{statement-block-intro} that comes from the @samp{do @{} that hangs
6127 on the @samp{#define} line:
6134 #define X(A, B) do @{ \
6135 printf (A, B); \ @hereFn{c-lineup-cpp-define}
6137 @} while (0) @hereFn{c-lineup-cpp-define}
6148 error(\"Not running!\");
6150 #define X(A, B) do @{ \
6151 printf (A, B); \ @hereFn{c-lineup-cpp-define}
6153 @} while (0) @hereFn{c-lineup-cpp-define}
6157 The relative indentation returned by @code{c-lineup-cpp-define} is zero
6158 and two, respectively, on the two lines in each of these examples. They
6159 are then added to the two column indentation that
6160 @code{statement-block-intro} gives in both cases here.
6162 If the relative indentation is zero, then @code{nil} is returned
6163 instead. That is useful in a list expression to specify the default
6164 indentation on the top level.
6166 If @code{c-syntactic-indentation-in-macros} is @code{nil} then this
6167 function keeps the current indentation, except for empty lines (ignoring
6168 the ending backslash) where it takes the indentation from the closest
6169 preceding nonempty line in the macro. If there's no such line in the
6170 macro then the indentation is taken from the construct preceding it, as
6173 @workswith @code{cpp-define-intro}.
6176 @comment ------------------------------------------------------------
6178 @defun c-lineup-gcc-asm-reg
6179 @findex lineup-gcc-asm-reg (c-)
6180 Line up a gcc asm register under one on a previous line.
6193 The @samp{x} line is aligned to the text after the @samp{:} on the
6194 @samp{w} line, and similarly @samp{z} under @samp{y}.
6196 This is done only in an @samp{asm} or @samp{__asm__} block, and only to
6197 those lines mentioned. Anywhere else @code{nil} is returned. The usual
6198 arrangement is to have this routine as an extra feature at the start of
6199 arglist lineups, e.g.
6202 (c-lineup-gcc-asm-reg c-lineup-arglist)
6205 @workswith @code{arglist-cont}, @code{arglist-cont-nonempty}.
6208 @comment ------------------------------------------------------------
6210 @defun c-lineup-topmost-intro-cont
6211 @findex lineup-topmost-intro-cont (c-)
6212 Line up declaration continuation lines zero or one indentation
6213 step@footnote{This function is mainly provided to mimic the behavior of
6214 CC Mode 5.28 and earlier where this case wasn't handled consistently so
6215 that those lines could be analyzed as either topmost-intro-cont or
6216 statement-cont. It's used for @code{topmost-intro-cont} by default, but
6217 you might consider using @code{+} instead.}. For lines preceding a
6218 definition, zero is used. For other lines, @code{c-basic-offset} is
6219 added to the indentation. E.g:
6224 neg (int i) @hereFn{c-lineup-topmost-intro-cont}
6237 larch @hereFn{c-lineup-topmost-intro-cont}
6241 the_larch, @hereFn{c-lineup-topmost-intro-cont}
6242 another_larch; @hereFn{c-lineup-topmost-intro-cont}
6253 the_larch, @hereFn{c-lineup-topmost-intro-cont}
6254 another_larch; @hereFn{c-lineup-topmost-intro-cont}
6258 @workswith @code{topmost-intro-cont}.
6261 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6262 @node Custom Line-Up, Other Indentation, Line-Up Functions, Customizing Indentation
6263 @comment node-name, next, previous, up
6264 @section Custom Line-Up Functions
6265 @cindex customization, indentation functions
6266 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6268 The most flexible way to customize indentation is by writing custom
6269 line-up functions, and associating them with specific syntactic
6270 symbols (@pxref{c-offsets-alist}). Depending on the effect you want,
6271 it might be better to write a @code{c-special-indent-hook} function
6272 rather than a line-up function (@pxref{Other Indentation}).
6274 @ccmode{} comes with an extensive set of predefined line-up functions,
6275 not all of which are used by the default styles. So there's a good
6276 chance the function you want already exists. @xref{Line-Up
6277 Functions}, for a list of them. If you write your own line-up
6278 function, it's probably a good idea to start working from one of these
6279 predefined functions, which can be found in the file
6280 @file{cc-align.el}. If you have written a line-up function that you
6281 think is generally useful, you're very welcome to contribute it;
6282 please contact @email{bug-cc-mode@@gnu.org}.
6284 Line-up functions are passed a single argument, the syntactic
6285 element (see below). The return value is a @code{c-offsets-alist}
6286 offset specification: for example, an integer, a symbol such as
6287 @code{+}, a vector, @code{nil}@footnote{Returning @code{nil} is useful
6288 when the offset specification for a syntactic element is a list
6289 containing the line-up function (@pxref{c-offsets-alist}).}, or even
6290 another line-up function. Full details of these are in
6291 @ref{c-offsets-alist}.
6293 Line-up functions must not move point or change the content of the
6294 buffer (except temporarily). They are however allowed to do
6295 @dfn{hidden buffer changes}, i.e. setting text properties for caching
6296 purposes etc. Buffer undo recording is disabled while they run.
6298 The syntactic element passed as the parameter to a line-up function is
6299 a cons cell of the form
6302 (@r{@var{syntactic-symbol}} . @r{@var{anchor-position}})
6306 @c FIXME!!! The following sentence might be better omitted, since the
6307 @c information is in the cross reference "Syntactic Analysis". 2005/10/2.
6308 where @var{syntactic-symbol} is the symbol that the function was
6309 called for, and @var{anchor-position} is the anchor position (if any)
6310 for the construct that triggered the syntactic symbol
6311 (@pxref{Syntactic Analysis}). This cons cell is how the syntactic
6312 element of a line used to be represented in @ccmode{} 5.28 and
6313 earlier. Line-up functions are still passed this cons cell, so as to
6314 preserve compatibility with older configurations. In the future, we
6315 may decide to convert to using the full list format---you can prepare
6316 your setup for this by using the access functions
6317 (@code{c-langelem-sym}, etc.) described below.
6319 @vindex c-syntactic-element
6320 @vindex syntactic-element (c-)
6321 @vindex c-syntactic-context
6322 @vindex syntactic-context (c-)
6323 Some syntactic symbols, e.g. @code{arglist-cont-nonempty}, have more
6324 info in the syntactic element - typically other positions that can be
6325 interesting besides the anchor position. That info can't be accessed
6326 through the passed argument, which is a cons cell. Instead, you can
6327 get this information from the variable @code{c-syntactic-element},
6328 which is dynamically bound to the complete syntactic element. The
6329 variable @code{c-syntactic-context} might also be useful - it gets
6330 dynamically bound to the complete syntactic context. @xref{Custom
6333 @ccmode{} provides a few functions to access parts of syntactic
6334 elements in a more abstract way. Besides making the code easier to
6335 read, they also hide the difference between the old cons cell form
6336 used in the line-up function argument and the new list form used in
6337 @code{c-syntactic-element} and everywhere else. The functions are:
6339 @defun c-langelem-sym langelem
6340 @findex langelem-sym (c-)
6341 Return the syntactic symbol in @var{langelem}.
6344 @defun c-langelem-pos langelem
6345 @findex langelem-pos (c-)
6346 Return the anchor position in @var{langelem}, or nil if there is none.
6349 @defun c-langelem-col langelem &optional preserve-point
6350 @findex langelem-col (c-)
6351 Return the column of the anchor position in @var{langelem}. Also move
6352 the point to that position unless @var{preserve-point} is
6356 @defun c-langelem-2nd-pos langelem
6357 @findex langelem-2nd-pos (c-)
6358 Return the secondary position in @var{langelem}, or @code{nil} if there
6361 Note that the return value of this function is always @code{nil} if
6362 @var{langelem} is in the old cons cell form. Thus this function is
6363 only meaningful when used on syntactic elements taken from
6364 @code{c-syntactic-element} or @code{c-syntactic-context}.
6367 Custom line-up functions can be as simple or as complex as you like, and
6368 any syntactic symbol that appears in @code{c-offsets-alist} can have a
6369 custom line-up function associated with it.
6371 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6372 @node Other Indentation, , Custom Line-Up, Customizing Indentation
6373 @comment node-name, next, previous, up
6374 @section Other Special Indentations
6375 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6377 Here are the remaining odds and ends regarding indentation:
6379 @defopt c-label-minimum-indentation
6380 @vindex label-minimum-indentation (c-)
6381 In @samp{gnu} style (@pxref{Built-in Styles}), a minimum indentation is
6382 imposed on lines inside code blocks. This minimum indentation is
6383 controlled by this style variable. The default value is 1.
6385 @findex c-gnu-impose-minimum
6386 @findex gnu-impose-minimum (c-)
6387 It's the function @code{c-gnu-impose-minimum} that enforces this minimum
6388 indentation. It must be present on @code{c-special-indent-hook} to
6392 @defopt c-special-indent-hook
6393 @vindex special-indent-hook (c-)
6394 This style variable is a standard hook variable that is called after
6395 every line is indented by @ccmode{}. It is called only if
6396 @code{c-syntactic-indentation} is non-@code{nil} (which it is by
6397 default (@pxref{Indentation Engine Basics})). You can put a function
6398 on this hook to do any special indentation or ad hoc line adjustments
6399 your style dictates, such as adding extra indentation to constructors
6400 or destructor declarations in a class definition, etc. Sometimes it
6401 is better to write a custom Line-up Function instead (@pxref{Custom
6404 When the indentation engine calls this hook, the variable
6405 @code{c-syntactic-context} is bound to the current syntactic context
6406 (i.e. what you would get by typing @kbd{C-c C-s} on the source line.
6407 @xref{Custom Braces}.). Note that you should not change point or mark
6408 inside a @code{c-special-indent-hook} function, i.e. you'll probably
6409 want to wrap your function in a @code{save-excursion}@footnote{The
6410 numerical value returned by @code{point} will change if you change the
6411 indentation of the line within a @code{save-excursion} form, but point
6412 itself will still be over the same piece of text.}.
6414 Setting @code{c-special-indent-hook} in style definitions is handled
6415 slightly differently from other variables---A style can only add
6416 functions to this hook, not remove them. @xref{Style Variables}.
6420 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6421 @node Custom Macros, Odds and Ends, Customizing Indentation, Top
6422 @comment node-name, next, previous, up
6423 @chapter Customizing Macros
6425 @cindex preprocessor directives
6426 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6428 Normally, the lines in a multi-line macro are indented relative to
6429 eachother as though they were code. You can suppress this behaviour
6430 by setting the following user option:
6432 @defopt c-syntactic-indentation-in-macros
6433 @vindex syntactic-indentation-in-macros (c-)
6434 Enable syntactic analysis inside macros, which is the default. If this
6435 is @code{nil}, all lines inside macro definitions are analyzed as
6436 @code{cpp-macro-cont}.
6439 @ccmode{} provides some tools to help keep the line continuation
6440 backslashes in macros neat and tidy. Their precise action is
6441 customized with these variables:
6443 @defopt c-backslash-column
6444 @vindex backslash-column (c-)
6445 @defoptx c-backslash-max-column
6446 @vindex backslash-max-column (c-)
6447 These variables control the alignment columns for line continuation
6448 backslashes in multiline macros. They are used by the functions that
6449 automatically insert or align such backslashes,
6450 e.g. @code{c-backslash-region} and @code{c-context-line-break}.
6452 @code{c-backslash-column} specifies the minimum column for the
6453 backslashes. If any line in the macro goes past this column, then the
6454 next tab stop (i.e. next multiple of @code{tab-width}) in that line is
6455 used as the alignment column for all the backslashes, so that they
6456 remain in a single column. However, if any lines go past
6457 @code{c-backslash-max-column} then the backslashes in the rest of the
6458 macro will be kept at that column, so that the lines which are too
6459 long ``stick out'' instead.
6461 Don't ever set these variables to @code{nil}. If you want to disable
6462 the automatic alignment of backslashes, use
6463 @code{c-auto-align-backslashes}.
6466 @defopt c-auto-align-backslashes
6467 @vindex auto-align-backslashes (c-)
6468 Align automatically inserted line continuation backslashes if
6469 non-@code{nil}. When line continuation backslashes are inserted
6470 automatically for line breaks in multiline macros, e.g. by
6471 @code{c-context-line-break}, they are aligned with the other
6472 backslashes in the same macro if this flag is set.
6474 If @code{c-auto-align-backslashes} is @code{nil}, automatically
6475 inserted backslashes are preceded by a single space, and backslashes
6476 get aligned only when you explicitly invoke the command
6477 @code{c-backslash-region} (@kbd{C-c C-\}).
6480 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6481 @node Odds and Ends, Sample .emacs File, Custom Macros, Top
6482 @comment node-name, next, previous, up
6483 @chapter Odds and Ends
6484 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6486 The stuff that didn't fit in anywhere else is documented here.
6488 @defopt c-require-final-newline
6489 @vindex require-final-newline (c-)
6490 Controls whether a final newline is enforced when the file is saved.
6491 The value is an association list that for each language mode specifies
6492 the value to give to @code{require-final-newline} (@pxref{Saving
6493 Buffers,,, @lispref{}, @lispreftitle{}}) at mode initialization. If a
6494 language isn't present on the association list, CC Mode won't touch
6495 @code{require-final-newline} in buffers for that language.
6497 The default is to set @code{require-final-newline} to @code{t} in the
6498 languages that mandate that source files should end with newlines.
6499 These are C, C++ and Objective-C.
6502 @defopt c-echo-syntactic-information-p
6503 @vindex echo-syntactic-information-p (c-)
6504 If non-@code{nil}, the syntactic analysis for the current line is shown
6505 in the echo area when it's indented (unless
6506 @code{c-syntactic-indentation} is @code{nil}). That's useful when
6507 finding out which syntactic symbols to modify to get the indentation you
6511 @defopt c-report-syntactic-errors
6512 @vindex report-syntactic-errors (c-)
6513 If non-@code{nil}, certain syntactic errors are reported with a ding and
6514 a message, for example when an @code{else} is indented for which there
6515 is no corresponding @code{if}.
6517 Note however that @ccmode{} doesn't make any special effort to check for
6518 syntactic errors; that's the job of the compiler. The reason it can
6519 report cases like the one above is that it can't find the correct
6520 anchoring position to indent the line in that case.
6524 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6525 @node Sample .emacs File, Performance Issues, Odds and Ends, Top
6526 @comment node-name, next, previous, up
6527 @appendix Sample .emacs File
6528 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6531 ;; Here's a sample .emacs file fragment that might help you along the
6532 ;; way. Just copy this region and paste it into your .emacs file.
6533 ;; You might want to change some of the actual values.
6535 ;; Make some non-standard key bindings. We can put these in
6536 ;; c-mode-base-map because c-mode-map, c++-mode-map, and so on,
6538 (defun my-c-initialization-hook ()
6539 (define-key c-mode-base-map "\C-m" 'c-context-line-break)
6540 (define-key c-mode-base-map [?\C-\M-a] 'c-beginning-of-defun)
6541 (define-key c-mode-base-map [?\C-\M-e] 'c-end-of-defun)
6542 (add-hook 'c-initialization-hook 'my-c-initialization-hook)
6544 ;; offset customizations not in my-c-style
6545 ;; This will take precedence over any setting of the syntactic symbol
6547 (setq c-offsets-alist '((member-init-intro . ++)))
6549 ;; Create my personal style.
6550 (defconst my-c-style
6551 '((c-tab-always-indent . t)
6552 (c-comment-only-line-offset . 4)
6553 (c-hanging-braces-alist . ((substatement-open after)
6555 (c-hanging-colons-alist . ((member-init-intro before)
6559 (access-label after)))
6560 (c-cleanup-list . (scope-operator
6563 (c-offsets-alist . ((arglist-close . c-lineup-arglist)
6564 (substatement-open . 0)
6567 (knr-argdecl-intro . -)))
6568 (c-echo-syntactic-information-p . t))
6569 "My C Programming Style")
6570 (c-add-style "PERSONAL" my-c-style)
6572 ;; Customizations for all modes in CC Mode.
6573 (defun my-c-mode-common-hook ()
6574 ;; set my personal style for the current buffer
6575 (c-set-style "PERSONAL")
6576 ;; other customizations
6578 ;; this will make sure spaces are used instead of tabs
6579 indent-tabs-mode nil)
6580 ;; we like auto-newline, but not hungry-delete
6581 (c-toggle-auto-newline 1))
6582 (add-hook 'c-mode-common-hook 'my-c-mode-common-hook)
6585 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6586 @node Performance Issues, Limitations and Known Bugs, Sample .emacs File, Top
6587 @comment node-name, next, previous, up
6588 @chapter Performance Issues
6590 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6592 @comment FIXME: (ACM, 2003/5/24). Check whether AWK needs mentioning here.
6594 C and its derivative languages are highly complex creatures. Often,
6595 ambiguous code situations arise that require @ccmode{} to scan large
6596 portions of the buffer to determine syntactic context. Such
6597 pathological code can cause @ccmode{} to perform fairly badly. This
6598 section gives some insight in how @ccmode{} operates, how that interacts
6599 with some coding styles, and what you can use to improve performance.
6601 The overall goal is that @ccmode{} shouldn't be overly slow (i.e. take
6602 more than a fraction of a second) in any interactive operation.
6603 I.e. it's tuned to limit the maximum response time in single operations,
6604 which is sometimes at the expense of batch-like operations like
6605 reindenting whole blocks. If you find that @ccmode{} gradually gets
6606 slower and slower in certain situations, perhaps as the file grows in
6607 size or as the macro or comment you're editing gets bigger, then chances
6608 are that something isn't working right. You should consider reporting
6609 it, unless it's something that's mentioned in this section.
6611 Because @ccmode{} has to scan the buffer backwards from the current
6612 insertion point, and because C's syntax is fairly difficult to parse in
6613 the backwards direction, @ccmode{} often tries to find the nearest
6614 position higher up in the buffer from which to begin a forward scan
6615 (it's typically an opening or closing parenthesis of some kind). The
6616 farther this position is from the current insertion point, the slower it
6619 @findex beginning-of-defun
6620 In earlier versions of @ccmode{}, we used to recommend putting the
6621 opening brace of a top-level construct@footnote{E.g. a function in C,
6622 or outermost class definition in C++ or Java.} into the leftmost
6623 column. Earlier still, this used to be a rigid Emacs constraint, as
6624 embodied in the @code{beginning-of-defun} function. @ccmode now
6625 caches syntactic information much better, so that the delay caused by
6626 searching for such a brace when it's not in column 0 is minimal,
6627 except perhaps when you've just moved a long way inside the file.
6628 Don't forget to rebind @kbd{C-M-a} and @kbd{C-M-e} to the @ccmode{}
6629 functions @code{beginning-of-defun} and @code{end-of-defun} if you're
6630 going to be hanging your braces! @xref{Sample .emacs File}.
6632 @findex defun-prompt-regexp
6633 @vindex c-Java-defun-prompt-regexp
6634 @vindex Java-defun-prompt-regexp (c-)
6635 A special note about @code{defun-prompt-regexp} in Java mode: The common
6636 style is to hang the opening braces of functions and classes on the
6637 right side of the line, and that doesn't work well with the Emacs
6638 approach. @ccmode{} comes with a constant
6639 @code{c-Java-defun-prompt-regexp} which tries to define a regular
6640 expression usable for this style, but there are problems with it. In
6641 some cases it can cause @code{beginning-of-defun} to hang@footnote{This
6642 has been observed in Emacs 19.34 and XEmacs 19.15.}. For this reason,
6643 it is not used by default, but if you feel adventurous, you can set
6644 @code{defun-prompt-regexp} to it in your mode hook. In any event,
6645 setting and relying on @code{defun-prompt-regexp} will definitely slow
6646 things down because (X)Emacs will be doing regular expression searches a
6647 lot, so you'll probably be taking a hit either way!
6649 @ccmode{} maintains a cache of the opening parentheses of the blocks
6650 surrounding the point, and it adapts that cache as the point is moved
6651 around. That means that in bad cases it can take noticeable time to
6652 indent a line in a new surrounding, but after that it gets fast as long
6653 as the point isn't moved far off. The farther the point is moved, the
6654 less useful is the cache. Since editing typically is done in ``chunks''
6655 rather than on single lines far apart from each other, the cache
6656 typically gives good performance even when the code doesn't fit the
6657 Emacs approach to finding the defun starts.
6659 @vindex c-enable-xemacs-performance-kludge-p
6660 @vindex enable-xemacs-performance-kludge-p (c-)
6661 XEmacs users can set the variable
6662 @code{c-enable-xemacs-performance-kludge-p} to non-@code{nil}. This
6663 tells @ccmode{} to use XEmacs-specific built-in functions which, in some
6664 circumstances, can locate the top-most opening brace much more quickly than
6665 @code{beginning-of-defun}. Preliminary testing has shown that for
6666 styles where these braces are hung (e.g. most JDK-derived Java styles),
6667 this hack can improve performance of the core syntax parsing routines
6668 from 3 to 60 times. However, for styles which @emph{do} conform to
6669 Emacs' recommended style of putting top-level braces in column zero,
6670 this hack can degrade performance by about as much. Thus this variable
6671 is set to @code{nil} by default, since the Emacs-friendly styles should
6672 be more common (and encouraged!). Note that this variable has no effect
6673 in Emacs since the necessary built-in functions don't exist (in Emacs
6674 21.3 as of this writing in May 2003).
6676 Text properties are used to speed up skipping over syntactic whitespace,
6677 i.e. comments and preprocessor directives. Indenting a line after a
6678 huge macro definition can be slow the first time, but after that the
6679 text properties are in place and it should be fast (even after you've
6680 edited other parts of the file and then moved back).
6682 Font locking can be a CPU hog, especially the font locking done on
6683 decoration level 3 which tries to be very accurate. Note that that
6684 level is designed to be used with a font lock support mode that only
6685 fontifies the text that's actually shown, i.e. Lazy Lock or Just-in-time
6686 Lock mode, so make sure you use one of them. Fontification of a whole
6687 buffer with some thousand lines can often take over a minute. That is
6688 a known weakness; the idea is that it never should happen.
6690 The most effective way to speed up font locking is to reduce the
6691 decoration level to 2 by setting @code{font-lock-maximum-decoration}
6692 appropriately. That level is designed to be as pretty as possible
6693 without sacrificing performance. @xref{Font Locking Preliminaries}, for
6697 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6698 @node Limitations and Known Bugs, FAQ, Performance Issues, Top
6699 @comment node-name, next, previous, up
6700 @chapter Limitations and Known Bugs
6703 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6707 There is no way to apply auto newline settings (@pxref{Auto-newlines})
6708 on already typed lines. That's only a feature to ease interactive
6711 To generalize this issue a bit: @ccmode{} is not intended to be used as
6712 a reformatter for old code in some more or less batch-like way. With
6713 the exception of some functions like @code{c-indent-region}, it's only
6714 geared to be used interactively to edit new code. There's currently no
6715 intention to change this goal.
6717 If you want to reformat old code, you're probably better off using some
6718 other tool instead, e.g. @ref{Top, , GNU indent, indent, The `indent'
6719 Manual}, which has more powerful reformatting capabilities than
6723 The support for C++ templates (in angle brackets) is not yet complete.
6724 When a non-nested template is used in a declaration, @ccmode{} indents
6725 it and font-locks it OK. Templates used in expressions, and nested
6726 templates do not fare so well. Sometimes a workaround is to refontify
6727 the expression after typing the closing @samp{>}.
6730 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6731 @node FAQ, Updating CC Mode, Limitations and Known Bugs, Top
6732 @comment node-name, next, previous, up
6733 @appendix Frequently Asked Questions
6734 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6738 @emph{How can I change the indent level from 4 spaces to 2 spaces?}
6740 Set the variable @code{c-basic-offset}. @xref{Getting Started}.
6745 @emph{Why doesn't the @kbd{RET} key indent the new line?}
6747 Emacs' convention is that @kbd{RET} just adds a newline, and that
6748 @kbd{C-j} adds a newline and indents it. You can make @kbd{RET} do this
6749 too by adding this to your @code{c-initialization-hook}:
6752 (define-key c-mode-base-map "\C-m" 'c-context-line-break)
6755 @xref{Getting Started}. This is a very common question. If you want
6756 this to be the default behavior, don't lobby us, lobby RMS! @t{:-)}
6759 @emph{How do I stop my code jumping all over the place when I type?}
6761 Deactivate ``electric minor mode'' with @kbd{C-c C-l}. @xref{Getting
6767 @emph{How do I reindent the whole file?}
6769 Visit the file and hit @kbd{C-x h} to mark the whole buffer. Then hit
6770 @kbd{C-M-\}. @xref{Indentation Commands}.
6775 @emph{How do I reindent the current block?}
6777 First move to the brace which opens the block with @kbd{C-M-u}, then
6778 reindent that expression with @kbd{C-M-q}. @xref{Indentation
6782 @emph{I put @code{(c-set-offset 'substatement-open 0)} in my
6783 @file{.emacs} file but I get an error saying that @code{c-set-offset}'s
6784 function definition is void. What's wrong?}
6786 This means that @ccmode{} hasn't yet been loaded into your Emacs
6787 session by the time the @code{c-set-offset} call is reached, most
6788 likely because @ccmode{} is being autoloaded. Instead of putting the
6789 @code{c-set-offset} line in your top-level @file{.emacs} file, put it
6790 in your @code{c-initialization-hook} (@pxref{CC Hooks}), or simply
6791 modify @code{c-offsets-alist} directly:
6794 (setq c-offsets-alist '((substatement-open . 0)))
6798 @cindex open paren in column zero
6799 @emph{I have an open paren character at column zero inside a comment or
6800 multiline string literal, and it causes the fontification and/or
6801 indentation to go haywire. What gives?}
6803 It's due to the ad-hoc rule in (X)Emacs that such open parens always
6804 start defuns (which translates to functions, classes, namespaces or any
6805 other top-level block constructs in the @ccmode{} languages).
6807 @xref{Defuns,,, xemacs, XEmacs User's Manual}, for details.
6810 @xref{Left Margin Paren,,, emacs, GNU Emacs Manual}, for details
6811 (@xref{Defuns,,, emacs, GNU Emacs Manual}, in the Emacs 20 manual).
6814 This heuristic is built into the core syntax analysis routines in
6815 (X)Emacs, so it's not really a @ccmode{} issue. However, in Emacs
6816 21.1 it became possible to turn it off@footnote{Using the variable
6817 @code{open-paren-in-column-0-is-defun-start}.} and @ccmode{} does so
6818 there since it's got its own system to keep track of blocks.
6823 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6824 @node Updating CC Mode, Mailing Lists and Bug Reports, FAQ, Top
6825 @comment node-name, next, previous, up
6826 @appendix Getting the Latest CC Mode Release
6827 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6829 @ccmode{} has been standard with all versions of Emacs since 19.34 and
6830 of XEmacs since 19.16.
6833 Due to release schedule skew, it is likely that all of these Emacsen
6834 have old versions of @ccmode{} and so should be upgraded. Access to the
6835 @ccmode{} source code, as well as more detailed information on Emacsen
6836 compatibility, etc. are all available on the web site:
6839 @uref{http://cc-mode.sourceforge.net/}
6843 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6844 @node Mailing Lists and Bug Reports, Command and Function Index, Updating CC Mode, Top
6845 @comment node-name, next, previous, up
6846 @appendix Mailing Lists and Submitting Bug Reports
6847 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6850 @findex c-submit-bug-report
6851 @findex submit-bug-report (c-)
6852 To report bugs, use the @kbd{C-c C-b} (bound to
6853 @code{c-submit-bug-report}) command. This provides vital information
6854 we need to reproduce your problem. Make sure you include a concise,
6855 but complete code example. Please try to boil your example down to
6856 just the essential code needed to reproduce the problem, and include
6857 an exact recipe of steps needed to expose the bug. Be especially sure
6858 to include any code that appears @emph{before} your bug example, if
6859 you think it might affect our ability to reproduce it.
6861 Please try to produce the problem in an Emacs instance without any
6862 customizations loaded (i.e. start it with the @samp{-q -no-site-file}
6863 arguments). If it works correctly there, the problem might be caused
6864 by faulty customizations in either your own or your site
6865 configuration. In that case, we'd appreciate if you isolate the Emacs
6866 Lisp code that triggers the bug and include it in your report.
6868 @cindex bug report mailing list
6869 Bug reports should be sent to @email{bug-cc-mode@@gnu.org}. You can
6870 also send other questions and suggestions (kudos? @t{;-)} to that
6871 address. It's a mailing list which you can join or browse an archive
6872 of; see the web site at @uref{http://cc-mode.sourceforge.net/} for
6875 @cindex announcement mailing list
6876 If you want to get announcements of new @ccmode{} releases, send the
6877 word @emph{subscribe} in the body of a message to
6878 @email{cc-mode-announce-request@@lists.sourceforge.net}. It's possible
6879 to subscribe from the web site too. Announcements will also be posted
6880 to the Usenet newsgroups @code{gnu.emacs.sources}, @code{comp.emacs},
6881 @code{comp.emacs.xemacs}, @code{comp.lang.c}, @code{comp.lang.c++},
6882 @code{comp.lang.objective-c}, @code{comp.lang.java.softwaretools},
6883 @code{comp.lang.idl}, and @code{comp.lang.awk}.
6884 @c There is no newsgroup for Pike. :-(
6886 @c Removed the tentative node "Mode Initialization" from here, 2005/8/27.
6887 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6888 @node Command and Function Index, Variable Index, Mailing Lists and Bug Reports, Top
6889 @comment node-name, next, previous, up
6890 @unnumbered Command and Function Index
6891 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6893 Since most @ccmode{} commands are prepended with the string
6894 @samp{c-}, each appears under its @code{c-@var{thing}} name and its
6895 @code{@var{thing} (c-)} name.
6902 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6903 @node Variable Index, Concept and Key Index, Command and Function Index, Top
6904 @comment node-name, next, previous, up
6905 @unnumbered Variable Index
6906 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6908 Since most @ccmode{} variables are prepended with the string
6909 @samp{c-}, each appears under its @code{c-@var{thing}} name and its
6910 @code{@var{thing} (c-)} name.
6917 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6918 @node Concept and Key Index, , Variable Index, Top
6919 @comment node-name, next, previous, up
6920 @unnumbered Concept and Key Index
6921 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6926 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6928 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
6939 arch-tag: c4cab162-5e57-4366-bdce-4a9db2fc97f0