@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@comment Define an index for syntactic symbols.
-@ifnottex @c In texi2dvi, the @defindex would create an empty cc-mode.ss
- @c For Info, unlike tex, @syncodeindex needs a matching @defindex.
@defindex ss
-@end ifnottex
@comment Combine key, syntactic symbol and concept indices into one.
@syncodeindex ss cp
@copying
This manual is for CC Mode in Emacs.
-Copyright @copyright{} 1995-2011 Free Software Foundation, Inc.
+Copyright @copyright{} 1995-2012 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
@titlepage
@sp 10
-@center @titlefont{CC Mode 5.31}
+@center @titlefont{CC Mode 5.32}
@sp 2
@center @subtitlefont{A GNU Emacs mode for editing C and C-like languages}
@sp 2
Styles
-* Built-in Styles::
-* Choosing a Style::
-* Adding Styles::
-* Guessing the Style::
-* File Styles::
+* Built-in Styles::
+* Choosing a Style::
+* Adding Styles::
+* Guessing the Style::
+* File Styles::
Customizing Auto-newlines
Syntactic Symbols
-* Function Symbols::
-* Class Symbols::
-* Conditional Construct Symbols::
-* Switch Statement Symbols::
-* Brace List Symbols::
-* External Scope Symbols::
-* Paren List Symbols::
-* Literal Symbols::
-* Multiline Macro Symbols::
-* Objective-C Method Symbols::
+* Function Symbols::
+* Class Symbols::
+* Conditional Construct Symbols::
+* Switch Statement Symbols::
+* Brace List Symbols::
+* External Scope Symbols::
+* Paren List Symbols::
+* Literal Symbols::
+* Multiline Macro Symbols::
+* Objective-C Method Symbols::
* Java Symbols::
-* Statement Block Symbols::
-* K&R Symbols::
+* Statement Block Symbols::
+* K&R Symbols::
Customizing Indentation
* Comment Line-Up::
* Misc Line-Up::
+Customizing Macros
+
+* Macro Backslashes::
+* Macros with ;::
+
@end detailmenu
@end menu
This manual describes @ccmode{}
@comment The following line must appear on its own, so that the
-version 5.31.
+version 5.32.
@comment Release.py script can update the version number automatically
@ccmode{} supports the editing of K&R and ANSI C, C++, Objective-C,
syntactic recognition can be wrong. @ccmode{} manages to figure it
out correctly most of the time, though.
+Some macros, when invoked, ''have their own semicolon''. To get the
+next line indented correctly, rather than as a continuation line,
+@xref{Macros with ;}.
+
Reindenting large sections of code can take a long time. When
@ccmode{} reindents a region of code, it is essentially equivalent to
hitting @key{TAB} on every line of the region.
precisely what sort of ``whitespace'' this will be. Set the standard
Emacs variable @code{indent-tabs-mode} to @code{t} if you want real
@samp{tab} characters to be used in the indentation, to @code{nil} if
-you want only spaces. @xref{Just Spaces,,, @emacsman{},
+you want only spaces. @xref{Just Spaces,,,@emacsman{},
@emacsmantitle{}}.
@defopt c-tab-always-indent
@itemx @kbd{C-M-e} (@code{c-end-of-defun})
@findex c-beginning-of-defun
@findex c-end-of-defun
+@vindex c-defun-tactic
+@vindex defun-tactic (c-)
Move to the beginning or end of the current or next function. Other
constructs (such as a structs or classes) which have a brace block
start or end of the function. This occasionally causes point not to
move at all.
+By default, these commands will recognize functions contained within a
+@dfn{declaration scope} such as a C++ @code{class} or @code{namespace}
+construct, should the point start inside it. If @ccmode fails to find
+function beginnings or ends inside the current declaration scope, it
+will search the enclosing scopes. If you want @ccmode to recognize
+functions only at the top level@footnote{this was @ccmode{}'s
+behavior prior to version 5.32.}, set @code{c-defun-tactic} to
+@code{t}.
+
These functions are analogous to the Emacs built-in commands
@code{beginning-of-defun} and @code{end-of-defun}, except they
eliminate the constraint that the top-level opening brace of the defun
@cindex Auto Fill mode
@cindex paragraph filling
Line breaks are by default handled (almost) the same regardless of
-whether they are made by auto fill mode (@pxref{Auto Fill,,,
-@emacsman{}, @emacsmantitle{}}), by paragraph filling (e.g. with
+whether they are made by auto fill mode (@pxref{Auto
+Fill,,,@emacsman{}, @emacsmantitle{}}), by paragraph filling (e.g. with
@kbd{M-q}), or explicitly with @kbd{M-j} or similar methods. In
string literals, the new line gets the same indentation as the
previous nonempty line.@footnote{You can change this default by
and @ref{Indentation Engine Basics}.
You can toggle each of these minor modes on and off, and you can
-configure @ccmode{} so that it starts up with your favourite
+configure @ccmode{} so that it starts up with your favorite
combination of them (@pxref{Sample .emacs File}). By default, when
you initialize a buffer, electric mode and syntactic-indentation mode
are enabled but the other two modes are disabled.
@vindex abbrev-mode
@findex abbrev-mode
@cindex Abbrev mode
-@ccmode{} uses Abbrev mode (@pxref{Abbrevs,,, @emacsman{}, @emacsmantitle{}})
+@ccmode{} uses Abbrev mode (@pxref{Abbrevs,,,@emacsman{}, @emacsmantitle{}})
to accomplish this. It's therefore turned on by default in all language
modes except IDL mode, since CORBA IDL doesn't have any statements.
@end deffn
a user function. The last character of the function name and the
opening parenthesis are highlighted. This font-locking rule will
spuriously highlight a valid concatenation expression where an
-identifier precedes a parenthesised expression. Unfortunately.
+identifier precedes a parenthesized expression. Unfortunately.
@item
Whitespace following the @samp{\} in what otherwise looks like an
If you make conflicting settings in several of these ways, the way
that takes precedence is the one that appears latest in this list:
-@itemize @asis
+@itemize @w{}
@item
@table @asis
@item Style
A @dfn{file local variable setting} is a setting which applies to an
individual source file. You put this in a @dfn{local variables list},
a special block at the end of the source file (@pxref{Specifying File
-Variables,,, @emacsman{}}).
+Variables,,,@emacsman{}}).
@item File Styles
A @dfn{file style} is a rarely used variant of the ``style'' mechanism
described above, which applies to an individual source file.
@xref{File Styles}. You use this by setting certain special variables
-in a local variables list (@pxref{Specifying File Variables,,,
-@emacsman{}}).
+in a local variables list (@pxref{Specifying File
+Variables,,,@emacsman{}}).
@item Hooks with Styles
For ultimate flexibility, you can use hooks and styles together. For
already formatted piece of your code, @ref{Guessing the Style}.
@menu
-* Built-in Styles::
-* Choosing a Style::
-* Adding Styles::
-* Guessing the Style::
-* File Styles::
+* Built-in Styles::
+* Choosing a Style::
+* Adding Styles::
+* Guessing the Style::
+* File Styles::
@end menu
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
The Emacs manual describes how you can customize certain variables on a
per-file basis by including a @dfn{file local variable} block at the end
-of the file (@pxref{File Variables,, Local Variables in Files, @emacsman{},
+of the file (@pxref{File Variables,, Local Variables in Files,@emacsman{},
@emacsmantitle{}}).
So far, you've only seen a functional interface for setting styles in
@end defopt
@vindex comment-multi-line
-If inside a comment and @code{comment-multi-line} (@pxref{Auto Fill,,,
-@emacsman{}, @emacsmantitle{}} is non-@code{nil}, the indentation and
+If inside a comment and @code{comment-multi-line} (@pxref{Auto
+Fill,,,@emacsman{}, @emacsmantitle{}} is non-@code{nil}, the
+indentation and
line prefix are preserved. If inside a comment and
@code{comment-multi-line} is @code{nil}, a new comment of the same
type is started on the next line and indented as appropriate for
@end table
@menu
-* Function Symbols::
-* Class Symbols::
-* Conditional Construct Symbols::
-* Switch Statement Symbols::
-* Brace List Symbols::
-* External Scope Symbols::
-* Paren List Symbols::
-* Literal Symbols::
-* Multiline Macro Symbols::
-* Objective-C Method Symbols::
+* Function Symbols::
+* Class Symbols::
+* Conditional Construct Symbols::
+* Switch Statement Symbols::
+* Brace List Symbols::
+* External Scope Symbols::
+* Paren List Symbols::
+* Literal Symbols::
+* Multiline Macro Symbols::
+* Objective-C Method Symbols::
* Java Symbols::
-* Statement Block Symbols::
-* K&R Symbols::
+* Statement Block Symbols::
+* K&R Symbols::
@end menu
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
This section explains the structure and semantics of the style
-variable @code{c-offset-alist}, the principal variable for configuring
+variable @code{c-offsets-alist}, the principal variable for configuring
indentation. Details of how to set it up, and its relationship to
@ccmode{}'s style system are given in @ref{Style Variables}.
@section Other Special Indentations
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+To configure macros which you invoke without a terminating @samp{;},
+see @xref{Macros with ;}.
+
Here are the remaining odds and ends regarding indentation:
@defopt c-label-minimum-indentation
@cindex preprocessor directives
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+Preprocessor macros in C, C++, and Objective C (introduced by
+@code{#define}) have a syntax different from the main language---for
+example, a macro declaration is not terminated by a semicolon, and if
+it is more than a line long, line breaks in it must be escaped with
+backslashes. @ccmode{} has some commands to manipulate these, see
+@ref{Macro Backslashes}.
+
Normally, the lines in a multi-line macro are indented relative to
each other as though they were code. You can suppress this behavior
by setting the following user option:
@code{cpp-macro-cont}.
@end defopt
+Because a macro can expand into anything at all, near where one is
+invoked @ccmode{} can only indent and fontify code heuristically.
+Sometimes it gets it wrong. Usually you should try to design your
+macros so that they ''look like ordinary code'' when you invoke them.
+However, one situation is so common that @ccmode{} handles it
+specially: that is when certain macros needn't (or mustn't) be
+followed by a @samp{;}. You need to configure @ccmode{} to handle
+these macros properly, see @ref{Macros with ;}.
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@menu
+* Macro Backslashes::
+* Macros with ;::
+@end menu
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Macro Backslashes, Macros with ;, Custom Macros, Custom Macros
+@comment node-name, next, previous, up
+@section Customizing Macro Backslashes
+@cindex @code{#define}
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
@ccmode{} provides some tools to help keep the line continuation
backslashes in macros neat and tidy. Their precise action is
customized with these variables:
@code{c-backslash-region} (@kbd{C-c C-\}).
@end defopt
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Macros with ;, , Macro Backslashes, Custom Macros
+@comment node-name, next, previous, up
+@section Macros with semicolons
+@cindex macros with semicolons
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+Macros which needn't (or mustn't) be followed by a semicolon when you
+invoke them, @dfn{macros with semicolons}, are very common. These can
+cause @ccmode{} to parse the next line wrongly as a
+@code{statement-cont} (@pxref{Function Symbols}) and thus mis-indent
+it.
+
+You can prevent this by specifying which macros have semicolons. It
+doesn't matter whether or not such a macro has a parameter list:
+
+@defopt c-macro-names-with-semicolon
+@vindex macro-names-with-semicolon (c-)
+This buffer-local variable specifies which macros have semicolons.
+After setting its value, you need to call
+@code{c-make-macro-with-semi-re} for it to take effect. It should be
+set to one of these values:
+
+@table @asis
+@item nil
+There are no macros with semicolons.
+@item a list of strings
+Each string is the name of a macro with a semicolon. Only valid
+@code{#define} names are allowed here. For example, to set the
+default value, you could write the following into your @file{.emacs}:
+
+@example
+(setq c-macro-names-with-semicolon
+ '("Q_OBJECT" "Q_PROPERTY" "Q_DECLARE" "Q_ENUMS"))
+@end example
+
+@item a regular expression
+This matches each symbol which is a macro with a semicolon. It must
+not match any string which isn't a valid @code{#define} name. For
+example:
+
+@example
+(setq c-macro-names-with-semicolon
+ "\\<\\(CLEAN_UP_AND_RETURN\\|Q_[[:upper:]]+\\)\\>")
+@end example
+@end table
+@end defopt
+
+@defun c-make-macro-with-semi-re
+@findex make-macro-with-semi-re (c-)
+Call this (non-interactive) function, which sets internal variables,
+each time you change the value of
+@code{c-macro-names-with-semicolon}. It takes no arguments, and its
+return value has no meaning. This function is called by @ccmode{}'s
+initialization code.
+@end defun
+
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@node Odds and Ends, Sample .emacs File, Custom Macros, Top
@comment node-name, next, previous, up
Controls whether a final newline is enforced when the file is saved.
The value is an association list that for each language mode specifies
the value to give to @code{require-final-newline} (@pxref{Saving
-Buffers,,, @lispref{}, @lispreftitle{}}) at mode initialization. If a
+Buffers,,,@lispref{}, @lispreftitle{}}) at mode initialization. If a
language isn't present on the association list, CC Mode won't touch
@code{require-final-newline} in buffers for that language.
styles where these braces are hung (e.g. most JDK-derived Java styles),
this hack can improve performance of the core syntax parsing routines
from 3 to 60 times. However, for styles which @emph{do} conform to
-Emacs' recommended style of putting top-level braces in column zero,
+Emacs's recommended style of putting top-level braces in column zero,
this hack can degrade performance by about as much. Thus this variable
is set to @code{nil} by default, since the Emacs-friendly styles should
be more common (and encouraged!). Note that this variable has no effect
@kindex C-j
@emph{Why doesn't the @kbd{RET} key indent the new line?}
-Emacs' convention is that @kbd{RET} just adds a newline, and that
+Emacs's convention is that @kbd{RET} just adds a newline, and that
@kbd{C-j} adds a newline and indents it. You can make @kbd{RET} do this
too by adding this to your @code{c-initialization-hook}: