comparison man/cc-mode.texi @ 75028:0922d91aab88

Changes for CC Mode 5.31.4. They are detailed in the ChangeLog entries for 2007-01-01.

75027:9f636bd65206

If you got this version of @ccmode{} with Emacs or XEmacs, it should
work just fine right out of the box.  Note however that you might not
have the latest @ccmode{} release and might want to upgrade your copy
(see below).

You should probably start by reading the entire chapter
@ref{Commands} to get an overview of @ccmode{}'s capabilities.

After trying out some commands, you may dislike some aspects of
@ccmode{}'s default configuration.  Here is an outline of how to
change some of the settings that newcomers to @ccmode{} most often

that begins at the line's left margin.

@item
When it's @code{nil}, the command indents the line by an extra
@code{c-basic-offset} columns.  A prefix argument acts as a
multiplier.  A bare prefix (@kbd{C-u @key{TAB}} is equivalent to -1,
removing @code{c-basic-offset} columns from the indentation.
@end itemize

The precise behavior is modified by several variables: With
@code{c-tab-always-indent}, you can make @key{TAB} insert whitespace

@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

@ccmode{} contains some useful commands for moving around in C code.

@table @asis
@item @kbd{M-x c-beginning-of-defun}
@itemx @kbd{M-x c-end-of-defun}
@findex c-beginning-of-defun
@findex c-end-of-defun
@findex beginning-of-defun (c-)
@findex end-of-defun (c-)
@findex beginning-of-defun
@findex end-of-defun
Move to the start or end of the current top-level definition.  This is
the outermost brace pair which encloses point, together with the
function header or similar preamble which precedes the opening brace.
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
must be in column zero.  See @ref{Defuns,,,@emacsman{},
@emacsmantitle{}}, for more information.

Depending on the coding style you're using, you might prefer these two
commands to the standard Emacs ones.  If so, consider binding them to
@kbd{C-M-a} and @kbd{C-M-e}.  @xref{Sample .emacs File}.  This
customization won't affect the special bindings for these key
sequences in force in AWK Mode.  For backwards compatibility reasons,
the default bindings for @kbd{C-M-a} and @kbd{C-M-e} remain in effect.

@item @kbd{C-M-a} (AWK Mode) (@code{c-awk-beginning-of-defun})
@itemx @kbd{C-M-e} (AWK Mode) (@code{c-awk-end-of-defun})
@kindex C-M-a (AWK Mode)
@kindex C-M-e (AWK Mode)
@findex c-awk-beginning-of-defun
@findex awk-beginning-of-defun (c-)
@findex c-awk-end-of-defun
@findex awk-end-of-defun (c-)
Move back to the beginning or forward to the end of the current AWK
defun.  These functions are bound to @kbd{C-M-a} and @kbd{C-M-e} by
default in AWK Mode.  They can take prefix-arguments, their
functionality being entirely equivalent to @code{beginning-of-defun}
and @code{end-of-defun}.

AWK Mode @dfn{defuns} are either pattern/action pairs (either of which
might be implicit) or user defined functions.  Having the @samp{@{} and
@samp{@}} (if there are any) in column zero, as is suggested for some
modes, is neither necessary nor helpful in AWK mode.

comment, the new line gets the suitable indentation and comment line
prefix like @code{c-indent-new-comment-line}.  In normal code it's
indented like @code{newline-and-indent} would do.  In macros it acts
like @code{newline-and-indent} but additionally inserts and optionally
aligns the line ending backslash so that the macro remains unbroken.
@xref{Custom Macros}, for details about the backslash alignment.

This function is not bound to a key by default, but it's intended to be
used on the @kbd{RET} key.  If you like the behavior of
@code{newline-and-indent} on @kbd{RET}, you should consider switching to
this function.  @xref{Sample .emacs File}.

@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

Here are the various other commands that didn't fit anywhere else:

@table @asis
@item @kbd{C-c :} (@code{c-scope-operator})
@kindex C-c :
@findex c-scope-operator
@findex scope-operator (c-)
In C++, it is also sometimes desirable to insert the double-colon scope

The language specific mode hooks.  The appropriate one is run as the
last thing when you enter that language mode.
@end defvar

Although these hooks are variables defined in @ccmode{}, you can give
them values before @ccmode{}'s code is loaded - indeed, this is the
only way to use @code{c-initialization-hook}.  Their values aren't
overwritten when @ccmode{} gets loaded.

Here's a simplified example of what you can add to your @file{.emacs}
file to do things whenever any @ccmode{} language is edited.  See the

@comment node-name, next, previous, up
@section Styles
@cindex styles
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

Most people only need to edit code formatted in just a few well-defined
and consistent styles.  For example, their organization might impose a
``blessed'' style that all its programmers must conform to.  Similarly,
people who work on GNU software will have to use the GNU coding style.
Some shops are more lenient, allowing a variety of coding styles, and as

@node    Choosing a Style, Adding Styles, Built-in Styles, Styles
@comment node-name, next, previous, up
@subsection Choosing a Style
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

Use @kbd{C-c .} to choose a style interactively:

@deffn Command c-set-style style-name
@findex set-style (c-)
@kindex C-c .
Switch to the specified style in the current buffer.  Use
interactively like this:

@example
@kbd{C-c . @var{style-name} @key{RET}}
@end example

You can use the @key{TAB} in the normal way to do completion on the
style name.  Note that all style names are case insensitive, even the
ones you define yourself.

Setting a style in this way does @emph{not} automatically reindent your
file.  For commands that you can use to view the effect of your changes,
see @ref{Indentation Commands} and @ref{Filling and Breaking}.
@end deffn

The default style in all newly created buffers is @code{gnu}, except
in Java and AWK modes where it's @code{java} and @code{awk}.

Remember that if you set a style variable with the Customization
interface or at the top level of your @file{.emacs} file before the
style system is initialised (@pxref{Config Basics}), this setting will
override the one that the style system would have given the variable.

@defopt c-default-style
@vindex default-style (c-)
This variable specifies which style to install by default in new
buffers.  It takes either a style name string, or an association list

give @code{c-syntactic-context} a value yourself---this would disrupt
the proper functioning of @ccmode{}.

This variable is also bound in three other circumstances:
(i)@w{ }when calling a c-hanging-semi&comma-criteria function
(@pxref{Hanging Semicolons and Commas}; (ii)@w{ }when calling a
line-up function (@pxref{Custom Line-Up}; (iii)@w{ }when calling a
c-special-indent-hook function (@pxref{Other Indentation}).
@end defvar

As an example, @ccmode{} itself uses this feature to dynamically
determine the hanginess of braces which close ``do-while''

@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

@dfn{Clean-ups} are mechanisms which remove (or exceptionally, add)
whitespace in specific circumstances and are complementary to colon
and brace hanging.  You enable a clean-up by adding its symbol into
@code{c-cleanup-list}.

On the surface, it would seem that clean-ups overlap the functionality
provided by the @code{c-hanging-*-alist} variables.  Clean-ups,
however, are used to adjust code ``after-the-fact'', i.e. to adjust
the whitespace in constructs later than when they were typed.

it's only an empty parenthesis pair.  I.e. you will get @samp{signal
(SIGINT, SIG_IGN)}, but @samp{abort()}.  Clean up occurs when the
closing parenthesis is typed.

@item comment-close-slash
When inside a block comment, terminate the comment when you type a
slash at the beginning of a line (i.e. immediately after the comment
prefix).  This clean-up removes whitespace preceding the slash and if
needed, inserts a star to complete the token @samp{*/}.
@end table


@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@node    Indentation Engine Basics, Customizing Indentation, Clean-ups, Top

@vindex strict-syntax-p (c-)
If an offset specification evaluates to @code{nil}, then a relative
offset of 0 (zero) is used@footnote{There is however a variable
@code{c-strict-syntax-p} that when set to non-@code{nil} will cause an
error to be signaled in that case.  It's now considered obsolete since
it doesn't work well with some of the alignment functions that returns
@code{nil} instead of zero.  You should therefore leave
@code{c-strict-syntax-p} set to @code{nil}.}.

@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@node    Interactive Customization, Line-Up Functions, c-offsets-alist, Customizing Indentation

@node    Sample .emacs File, Performance Issues, Odds and Ends, Top
@comment node-name, next, previous, up
@appendix Sample .emacs File
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

@verbatim
;; Here's a sample .emacs file fragment that might help you along the
;; way.  Just copy this region and paste it into your .emacs file.
;; You might want to change some of the actual values.

;; Make some non-standard key bindings.  We can put these in
;; c-mode-base-map because c-mode-map, c++-mode-map, and so on,
;; inherit from it.
(defun my-c-initialization-hook ()
  (define-key c-mode-base-map "\C-m" 'c-context-line-break)
  (define-key c-mode-base-map [?\C-\M-a] 'c-beginning-of-defun)
  (define-key c-mode-base-map [?\C-\M-e] 'c-end-of-defun))
(add-hook 'c-initialization-hook 'my-c-initialization-hook)

;; offset customizations not in my-c-style
;; This will take precedence over any setting of the syntactic symbol
;; made by a style.

column.  Earlier still, this used to be a rigid Emacs constraint, as
embodied in the @code{beginning-of-defun} function.  @ccmode now
caches syntactic information much better, so that the delay caused by
searching for such a brace when it's not in column 0 is minimal,
except perhaps when you've just moved a long way inside the file.
Don't forget to rebind @kbd{C-M-a} and @kbd{C-M-e} to the @ccmode{}
functions @code{beginning-of-defun} and @code{end-of-defun} if you're
going to be hanging your braces! @xref{Sample .emacs File}.

@findex defun-prompt-regexp
@vindex c-Java-defun-prompt-regexp
@vindex Java-defun-prompt-regexp (c-)
A special note about @code{defun-prompt-regexp} in Java mode: The common

@cindex bugs
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

@itemize @bullet
@item
There is no way to apply auto newline settings (@pxref{Auto-newlines})
on already typed lines.  That's only a feature to ease interactive
editing.

To generalize this issue a bit: @ccmode{} is not intended to be used as

The support for C++ templates (in angle brackets) is not yet complete.
When a non-nested template is used in a declaration, @ccmode{} indents
it and font-locks it OK.  Templates used in expressions, and nested
templates do not fare so well.  Sometimes a workaround is to refontify
the expression after typing the closing @samp{>}.
@end itemize

@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@node    FAQ, Updating CC Mode, Limitations and Known Bugs, Top
@comment node-name, next, previous, up

75028:0922d91aab88

If you got this version of @ccmode{} with Emacs or XEmacs, it should
work just fine right out of the box.  Note however that you might not
have the latest @ccmode{} release and might want to upgrade your copy
(see below).

You should probably start by skimming through the entire chapter
@ref{Commands} to get an overview of @ccmode{}'s capabilities.

After trying out some commands, you may dislike some aspects of
@ccmode{}'s default configuration.  Here is an outline of how to
change some of the settings that newcomers to @ccmode{} most often

that begins at the line's left margin.

@item
When it's @code{nil}, the command indents the line by an extra
@code{c-basic-offset} columns.  A prefix argument acts as a
multiplier.  A bare prefix (@kbd{C-u @key{TAB}}) is equivalent to -1,
removing @code{c-basic-offset} columns from the indentation.
@end itemize

The precise behavior is modified by several variables: With
@code{c-tab-always-indent}, you can make @key{TAB} insert whitespace

@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

@ccmode{} contains some useful commands for moving around in C code.

@table @asis
@item @kbd{C-M-a}
@itemx @kbd{C-M-e}
@findex c-beginning-of-defun
@findex c-end-of-defun

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
also count as ``functions'' here.  To move over several functions, you
can give these commands a repeat count.

The start of a function is at its header.  The end of the function is
after its closing brace, or after the semicolon of a construct (such
as a @code{struct}) which doesn't end at the brace.  These two
commands try to leave point at the beginning of a line near the actual
start or end of the function.  This occasionally causes point not to
move at all.

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
must be in column zero.  See @ref{Defuns,,,@emacsman{},
@emacsmantitle{}}, for more information.

@item @kbd{C-M-a} (AWK Mode) (@code{c-awk-beginning-of-defun})
@itemx @kbd{C-M-e} (AWK Mode) (@code{c-awk-end-of-defun})
@kindex C-M-a (AWK Mode)
@kindex C-M-e (AWK Mode)
@findex c-awk-beginning-of-defun
@findex awk-beginning-of-defun (c-)
@findex c-awk-end-of-defun
@findex awk-end-of-defun (c-)
Move to the beginning or end of the current or next AWK defun.  These
commands can take prefix-arguments, their functionality being entirely
equivalent to @code{beginning-of-defun} and @code{end-of-defun}.

AWK Mode @dfn{defuns} are either pattern/action pairs (either of which
might be implicit) or user defined functions.  Having the @samp{@{} and
@samp{@}} (if there are any) in column zero, as is suggested for some
modes, is neither necessary nor helpful in AWK mode.

comment, the new line gets the suitable indentation and comment line
prefix like @code{c-indent-new-comment-line}.  In normal code it's
indented like @code{newline-and-indent} would do.  In macros it acts
like @code{newline-and-indent} but additionally inserts and optionally
aligns the line ending backslash so that the macro remains unbroken.
@xref{Custom Macros}, for details about the backslash alignment.  In a
string, a backslash is inserted only if the string is within a
macro@footnote{In GCC, unescaped line breaks within strings are
valid.}.

This function is not bound to a key by default, but it's intended to be
used on the @kbd{RET} key.  If you like the behavior of
@code{newline-and-indent} on @kbd{RET}, you should consider switching to
this function.  @xref{Sample .emacs File}.

@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

Here are the various other commands that didn't fit anywhere else:

@table @asis
@item @kbd{C-c .} (@code{c-set-style})
@kindex C-c .
@findex c-set-style
@findex set-style (c-)
Switch to the specified style in the current buffer.  Use like this:

@example
@kbd{C-c . @var{style-name} @key{RET}}
@end example

You can use the @key{TAB} in the normal way to do completion on the
style name.  Note that all style names are case insensitive, even the
ones you define yourself.

Setting a style in this way does @emph{not} automatically reindent your
file.  For commands that you can use to view the effect of your changes,
see @ref{Indentation Commands} and @ref{Filling and Breaking}.

For details of the @ccmode{} style system, see @ref{Styles}.
@item @kbd{C-c :} (@code{c-scope-operator})
@kindex C-c :
@findex c-scope-operator
@findex scope-operator (c-)
In C++, it is also sometimes desirable to insert the double-colon scope

The language specific mode hooks.  The appropriate one is run as the
last thing when you enter that language mode.
@end defvar

Although these hooks are variables defined in @ccmode{}, you can give
them values before @ccmode{}'s code is loaded---indeed, this is the
only way to use @code{c-initialization-hook}.  Their values aren't
overwritten when @ccmode{} gets loaded.

Here's a simplified example of what you can add to your @file{.emacs}
file to do things whenever any @ccmode{} language is edited.  See the

@comment node-name, next, previous, up
@section Styles
@cindex styles
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

By @dfn{style} we mean the layout of the code---things like how many
columns to indent a block of code, whether an opening brace gets
indented to the level of the code it encloses, or of the construct
that introduces it, or ``hangs'' at the end of a line.

Most people only need to edit code formatted in just a few well-defined
and consistent styles.  For example, their organization might impose a
``blessed'' style that all its programmers must conform to.  Similarly,
people who work on GNU software will have to use the GNU coding style.
Some shops are more lenient, allowing a variety of coding styles, and as

@node    Choosing a Style, Adding Styles, Built-in Styles, Styles
@comment node-name, next, previous, up
@subsection Choosing a Style
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

When you create a new buffer, its style will be set from
@code{c-default-style}.  The factory default is the style @code{gnu},
except in Java and AWK modes where it's @code{java} and @code{awk}.

Remember that if you set a style variable with the Customization
interface or at the top level of your @file{.emacs} file before the
style system is initialised (@pxref{Config Basics}), this setting will
override the one that the style system would have given the variable.

To set a buffer's style interactively, use the command @kbd{C-c .}
(@pxref{Other Commands}).  To set it from a file's local variable
list, @ref{File Styles}.

@defopt c-default-style
@vindex default-style (c-)
This variable specifies which style to install by default in new
buffers.  It takes either a style name string, or an association list

give @code{c-syntactic-context} a value yourself---this would disrupt
the proper functioning of @ccmode{}.

This variable is also bound in three other circumstances:
(i)@w{ }when calling a c-hanging-semi&comma-criteria function
(@pxref{Hanging Semicolons and Commas}); (ii)@w{ }when calling a
line-up function (@pxref{Custom Line-Up}); (iii)@w{ }when calling a
c-special-indent-hook function (@pxref{Other Indentation}).
@end defvar

As an example, @ccmode{} itself uses this feature to dynamically
determine the hanginess of braces which close ``do-while''

@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

@dfn{Clean-ups} are mechanisms which remove (or exceptionally, add)
whitespace in specific circumstances and are complementary to colon
and brace hanging.  You enable a clean-up by adding its symbol into
@code{c-cleanup-list}, e.g. like this:

@example
(add-to-list 'c-cleanup-list 'space-before-funcall)
@end example

On the surface, it would seem that clean-ups overlap the functionality
provided by the @code{c-hanging-*-alist} variables.  Clean-ups,
however, are used to adjust code ``after-the-fact'', i.e. to adjust
the whitespace in constructs later than when they were typed.

it's only an empty parenthesis pair.  I.e. you will get @samp{signal
(SIGINT, SIG_IGN)}, but @samp{abort()}.  Clean up occurs when the
closing parenthesis is typed.

@item comment-close-slash
When inside a block comment, terminate the comment when you type a slash
at the beginning of a line (i.e. immediately after the comment prefix).
This clean-up removes whitespace preceding the slash and if needed,
inserts a star to complete the token @samp{*/}.  Type @kbd{C-q /} in this
situation if you just want a literal @samp{/} inserted.
@end table


@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@node    Indentation Engine Basics, Customizing Indentation, Clean-ups, Top

@vindex strict-syntax-p (c-)
If an offset specification evaluates to @code{nil}, then a relative
offset of 0 (zero) is used@footnote{There is however a variable
@code{c-strict-syntax-p} that when set to non-@code{nil} will cause an
error to be signaled in that case.  It's now considered obsolete since
it doesn't work well with some of the alignment functions that return
@code{nil} instead of zero.  You should therefore leave
@code{c-strict-syntax-p} set to @code{nil}.}.

@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@node    Interactive Customization, Line-Up Functions, c-offsets-alist, Customizing Indentation

@node    Sample .emacs File, Performance Issues, Odds and Ends, Top
@comment node-name, next, previous, up
@appendix Sample .emacs File
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

Here's a sample .emacs file fragment that might help you along the way.
Just copy this region and paste it into your .emacs file.  You might want
to change some of the actual values.

@verbatim
;; Make a non-standard key binding.  We can put this in
;; c-mode-base-map because c-mode-map, c++-mode-map, and so on,
;; inherit from it.
(defun my-c-initialization-hook ()
  (define-key c-mode-base-map "\C-m" 'c-context-line-break))
(add-hook 'c-initialization-hook 'my-c-initialization-hook)

;; offset customizations not in my-c-style
;; This will take precedence over any setting of the syntactic symbol
;; made by a style.

column.  Earlier still, this used to be a rigid Emacs constraint, as
embodied in the @code{beginning-of-defun} function.  @ccmode now
caches syntactic information much better, so that the delay caused by
searching for such a brace when it's not in column 0 is minimal,
except perhaps when you've just moved a long way inside the file.

@findex defun-prompt-regexp
@vindex c-Java-defun-prompt-regexp
@vindex Java-defun-prompt-regexp (c-)
A special note about @code{defun-prompt-regexp} in Java mode: The common

@cindex bugs
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

@itemize @bullet
@item
@ccmode{} doesn't support trigraphs.  (These are character sequences
such as @samp{??(}, which represents @samp{[}.  They date from a time
when some character sets didn't have all the characters that C needs,
and are now utterly obsolete.)

@item
There is no way to apply auto newline settings (@pxref{Auto-newlines})
on already typed lines.  That's only a feature to ease interactive
editing.

To generalize this issue a bit: @ccmode{} is not intended to be used as

The support for C++ templates (in angle brackets) is not yet complete.
When a non-nested template is used in a declaration, @ccmode{} indents
it and font-locks it OK.  Templates used in expressions, and nested
templates do not fare so well.  Sometimes a workaround is to refontify
the expression after typing the closing @samp{>}.

@item
On loading @ccmode{}, sometimes this error message appears:

@example
File mode specification error: (void-variable c-font-lock-keywords-3)
@end example

This is due to a bug in the function @code{eval-after-load} in some
versions of (X)Emacs.  It can manifest itself when there is a symbolic
link in the path of the directory which contains (X)Emacs.  As a
workaround, put the following into your @file{.emacs} file, fairly
early on:

@example
(defun my-load-cc-fonts ()
  (require "cc-fonts"))
(add-hook 'c-initialization-hook 'my-load-cc-fonts)
@end example
@end itemize

@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@node    FAQ, Updating CC Mode, Limitations and Known Bugs, Top
@comment node-name, next, previous, up