--- The Detailed Node Listing ---
Commands
Font Locking
Configuration Basics
Styles
Customizing Auto-newlines
Hanging Braces
Indentation Engine Basics
Syntactic Symbols
Customizing Indentation
Line-Up Functions
Welcome to CC Mode, a GNU Emacs mode for editing files containing C, C++, Objective-C, Java, CORBA IDL (and the variants CORBA PSDL and CIDL), Pike and AWK code. This incarnation of the mode is descended from c-mode.el (also called “Boring Old C Mode” or BOCM :-), c++-mode.el version 2, which Barry Warsaw had been maintaining since 1992, and awk-mode.el, a long neglected mode in the (X)Emacs base.
Late in 1997, Martin Stjernholm joined Barry on the CC Mode Maintainers Team, and implemented the Pike support. In 2000 Martin took over as the sole maintainer. In 2001 Alan Mackenzie joined the team, implementing AWK support in version 5.30. CC Mode did not originally contain the font lock support for its languages — that was added in version 5.30.
This manual describes CC Mode version 5.31.
CC Mode supports the editing of K&R and ANSI C, C++, Objective-C, Java, CORBA's Interface Definition Language, Pike1 and AWK files. In this way, you can easily set up consistent font locking and coding styles for use in editing all of these languages, although AWK is not yet as uniformly integrated as the other languages.
Note that the name of this package is “CC Mode”, but there is no top
level cc-mode entry point. All of the variables, commands, and
functions in CC Mode are prefixed with c-thing, and
c-mode, c++-mode, objc-mode, java-mode,
idl-mode, pike-mode, and awk-mode entry points are
provided. This package is intended to be a replacement for
c-mode.el, c++-mode.el and awk-mode.el.
A special word of thanks goes to Krishna Padmasola for his work in converting the original README file to Texinfo format. I'd also like to thank all the CC Mode victims who help enormously during the early beta stages of CC Mode's development.
The manual starts with several introductory chapters (including this one).
The next chunk of the manual describes the day to day use of CC Mode (as contrasted with how to customize it).
The next chunk of the manual describes how to customize CC Mode. Typically, an overview of a topic is given at the chapter level, then the sections and subsections describe the material in increasing detail.
The manual ends with “this and that”, things that don't fit cleanly into any of the previous chunks.
Finally, there are the customary indices.
If you got this version of CC Mode with Emacs or XEmacs, it should work just fine right out of the box. Note however that you might not have the latest CC Mode release and might want to upgrade your copy (see below).
You should probably start by skimming through the entire chapter Commands to get an overview of CC Mode's capabilities.
After trying out some commands, you may dislike some aspects of CC Mode's default configuration. Here is an outline of how to change some of the settings that newcomers to CC Mode most often want to change:
c-basic-offset or put this into your .emacs:
(setq c-basic-offset 6)
gnu style (except for Java and AWK buffers). A list of
the available styles and their descriptions can be found in
Built-in Styles. A complete specification of the CC Mode
style system, including how to create your own style, can be found in
the chapter Styles. To set your style to linux, either
customize c-default-style or put this into your .emacs:
(setq c-default-style '((java-mode . "java")
(awk-mode . "awk")
(other . "linux")))
(setq-default c-electric-flag nil)
Details of this and other similar “Minor Modes” appear in the
section Minor Modes.
(defun my-make-CR-do-indent ()
(define-key c-mode-base-map "\C-m" 'c-context-line-break))
(add-hook 'c-initialization-hook 'my-make-CR-do-indent)
This example demonstrates the use of a very powerful CC Mode (and Emacs) facility, the hook. The use of CC Mode's hooks is described in CC Hooks.
All these settings should occur in your .emacs before
any CC Mode buffers get loaded—in particular, before any call of
desktop-read.
As you get to know the mode better, you may want to make more ambitious changes to your configuration. For this, you should start reading the chapter Config Basics.
If you are upgrading an existing CC Mode installation, please see
the README file for installation details. In particular, if
you are going to be editing AWK files, README describes how to
configure your (X)Emacs so that CC Mode will supersede the obsolete
awk-mode.el which might have been supplied with your (X)Emacs.
CC Mode might not work with older versions of Emacs or XEmacs. See
the CC Mode release notes at http://cc-mode.sourceforge.net
for the latest information on Emacs version and package compatibility
(see Updating CC Mode).
You can find out what version of CC Mode you are using by visiting a C file and entering M-x c-version RET. You should see this message in the echo area:
Using CC Mode version 5.XXwhere `XX' is the minor release number.
This chapter specifies all of CC Mode's commands, and thus contains nearly everything you need to know to use CC Mode (as contrasted with configuring it). Commands here means both control key sequences and electric keys, these being characters such as `;' which, as well as inserting themselves into the buffer, also do other things.
You might well want to review Moving by Parens, which describes commands for moving around brace and parenthesis structures.
The following commands reindent C constructs. Note that when you change your coding style, either interactively or through some other means, your file does not automatically get reindented. You will need to execute one of the following commands to see the effects of your changes.
Also, variables like c-hanging-* and c-cleanup-list
(see Custom Auto-newlines) only affect how on-the-fly code is
formatted. Changing the “hanginess” of a brace and then
reindenting, will not move the brace to a different line. For this,
you're better off getting an external program like GNU indent,
which will rearrange brace location, amongst other things.
Preprocessor directives are handled as syntactic whitespace from other code, i.e. they can be interspersed anywhere without affecting the indentation of the surrounding code, just like comments.
The code inside macro definitions is, by default, still analyzed syntactically so that you get relative indentation there just as you'd get if the same code was outside a macro. However, since there is no hint about the syntactic context, i.e. whether the macro expands to an expression, to some statements, or perhaps to whole functions, the syntactic recognition can be wrong. CC Mode manages to figure it out correctly most of the time, though.
Reindenting large sections of code can take a long time. When CC Mode reindents a region of code, it is essentially equivalent to hitting <TAB> on every line of the region.
These commands indent code:
c-indent-command)c-indent-command does different things, depending on the
setting of c-syntactic-indentation (see Indentation Engine Basics):
nil (which it normally is), the command indents
the line according to its syntactic context. With a prefix argument
(C-u <TAB>), it will re-indent the entire
expression3
that begins at the line's left margin.
nil, the command indents the line by an extra
c-basic-offset columns. A prefix argument acts as a
multiplier. A bare prefix (C-u <TAB>) is equivalent to -1,
removing c-basic-offset columns from the indentation.
The precise behavior is modified by several variables: With
c-tab-always-indent, you can make <TAB> insert whitespace
in some circumstances—c-insert-tab-function then defines
precisely what sort of “whitespace” this will be. Set the standard
Emacs variable indent-tabs-mode to t if you want real
`tab' characters to be used in the indentation, to nil if
you want only spaces. See Just Spaces.
This variable modifies how <TAB> operates.
- When it is
t(the default), <TAB> simply indents the current line.- When it is
nil, <TAB> (re)indents the line only if point is to the left of the first non-whitespace character on the line. Otherwise it inserts some whitespace (a tab or an equivalent number of spaces - see below) at point.- With some other value, the line is reindented. Additionally, if point is within a string or comment, some whitespace is inserted.
When “some whitespace” is inserted as described above, what actually happens is that the function stored in
c-insert-tab-functionis called. Normally, this isinsert-tab, which inserts a real tab character or the equivalent number of spaces (depending onindent-tabs-mode). Some people, however, setc-insert-tab-functiontotab-to-tab-stopso as to get hard tab stops when indenting.
The kind of indentation the next five commands do depends on the
setting of c-syntactic-indentation (see Indentation Engine Basics):
nil (the default), the commands indent lines
according to their syntactic context;
nil, they just indent each line the same amount as
the previous non-blank line. The commands that indent a region aren't
very useful in this case.
newline-and-indent)c-indent-exp)c-indent-defun)indent-region)c-mark-function)c-indent-defun, this command operates on
top-level constructs, and can't be used to mark say, a Java method.
These variables are also useful when indenting code:
This is a standard Emacs variable that controls how line indentation is composed. When it's non-
nil, tabs can be used in a line's indentation, otherwise only spaces are used.
When indenting large regions of code, this variable controls how often a progress message is displayed. Set this variable to
nilto inhibit the progress messages, or set it to an integer which is how often (in seconds) progress messages are to be displayed.
comment-region)comment-region isn't
actually part of CC Mode - it is given a CC Mode binding for
convenience.
comment-dwim or indent-for-comment 4)comment-column
(see Options for Comments)
and the variables below. Finally, position the point after the
comment starter. C-u M-; kills any comment on the current line,
together with any whitespace before it. This is a standard Emacs
command, but CC Mode enhances it a bit with two variables:
This style variable allows you to vary the column that M-; puts the comment at, depending on what sort of code is on the line, and possibly the indentation of any similar comment on the preceding line. It is an association list that maps different types of lines to actions describing how they should be handled. If a certain line type isn't present on the list then the line is indented to the column specified by
comment-column.See the documentation string for a full description of this variable (use C-h v c-indent-comment-alist).
Normally, when this style variable is
nil, M-; will indent comment-only lines according toc-indent-comment-alist, just as it does with lines where other code precede the comments. However, if you want it to act just like <TAB> for comment-only lines you can get that by settingc-indent-comments-syntactically-pto non-nil.If
c-indent-comments-syntactically-pis non-nilthenc-indent-comment-alistwon't be consulted at all for comment-only lines.
CC Mode contains some useful commands for moving around in C code.
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 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
beginning-of-defun and end-of-defun, except they
eliminate the constraint that the top-level opening brace of the defun
must be in column zero. See Defuns, for more information.
c-awk-beginning-of-defun)c-awk-end-of-defun)beginning-of-defun and end-of-defun.
AWK Mode defuns are either pattern/action pairs (either of which
might be implicit) or user defined functions. Having the `{' and
`}' (if there are any) in column zero, as is suggested for some
modes, is neither necessary nor helpful in AWK mode.
c-beginning-of-statement)c-end-of-statement)If point is within or next to a comment or a string which spans more than one line, these commands move by sentences instead of statements.
When called from a program, these functions take three optional
arguments: the repetition count, a buffer position limit which is the
farthest back to search for the syntactic context, and a flag saying
whether to do sentence motion in or near comments and multiline
strings.
c-up-conditional)`#elif' is treated like `#else' followed by `#if', so the function stops at them when going backward, but not when going forward.
This key sequence is not bound in AWK Mode, which doesn't have
preprocessor statements.
c-up-conditional that also stops at `#else'
lines. Normally those lines are ignored.
`#elif' is treated like `#else' followed by `#if', so the
function stops at them when going forward, but not when going backward.
c-down-conditional that also stops at `#else'
lines. Normally those lines are ignored.
c-backward-conditional)c-forward-conditional)These key sequences are not bound in AWK Mode, which doesn't have
preprocessor statements.
These commands move backward or forward to the beginning of the next capitalized word. With prefix argument n, move n times. If n is negative, move in the opposite direction.
Note that these two commands have been superseded by
c-subword-mode, which you should use instead. See Subword Movement. They might be removed from a future release of CC Mode.
Since there's a lot of normal text in comments and string literals, CC Mode provides features to edit these like in text mode. The goal is to do it seamlessly, i.e. you can use auto fill mode, sentence and paragraph movement, paragraph filling, adaptive filling etc. wherever there's a piece of normal text without having to think much about it. CC Mode keeps the indentation, fixes suitable comment line prefixes, and so on.
You can configure the exact way comments get filled and broken, and where Emacs does auto-filling (see see Custom Filling and Breaking). Typically, the style system (see Styles) will have set this up for you, so you probably won't have to bother.
Line breaks are by default handled (almost) the same regardless of whether they are made by auto fill mode (see Auto Fill), by paragraph filling (e.g. with M-q), or explicitly with M-j or similar methods. In string literals, the new line gets the same indentation as the previous nonempty line.5.
c-fill-paragraph)The formatting of the starters (/*) and enders (*/) of
block comments are kept as they were before the filling. I.e., if
either the starter or ender were on a line of its own, then it stays
on its own line; conversely, if the delimiter has comment text on its
line, it keeps at least one word of that text with it on the line.
This command is the replacement for fill-paragraph in CC Mode
buffers.
c-indent-new-comment-line)indent-new-comment-line.
c-indent-new-comment-line. In normal code it's
indented like newline-and-indent would do. In macros it acts
like newline-and-indent but additionally inserts and optionally
aligns the line ending backslash so that the macro remains unbroken.
See Custom Macros, for details about the backslash alignment. In a
string, a backslash is inserted only if the string is within a
macro6.
This function is not bound to a key by default, but it's intended to be
used on the RET key. If you like the behavior of
newline-and-indent on RET, you should consider switching to
this function. See Sample .emacs File.
c-context-line-break is to RET. I.e. it works just like
c-context-line-break but leaves the point before the inserted
line break.
CC Mode contains several minor-mode-like features that you might find useful while writing new code or editing old code:
forward-word) and M-b (backward-word) treat the
parts of sillycapsed symbols as different words.
E.g. `NSGraphicsContext' is treated as three words `NS',
`Graphics', and `Context'.
Full details on how these minor modes work are at Electric Keys, Auto-newlines, Hungry WS Deletion, Subword Movement, and Indentation Engine Basics.
You can toggle each of these minor modes on and off, and you can configure CC Mode so that it starts up with your favourite combination of them (see 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.
CC Mode displays the current state of the first four of these minor modes on the modeline by appending letters to the major mode's name, one letter for each enabled minor mode - `l' for electric mode, `a' for auto-newline mode, `h' for hungry delete mode, and `w' for subword mode. If all these modes were enabled, you'd see `C/lahw'7.
Here are the commands to toggle these modes:
c-toggle-electric-state)c-toggle-auto-newline)M-x c-subword-mode)Common to all the toggle functions above is that if they are called
programmatically, they take an optional numerical argument. A
positive value will turn on the minor mode (or both of them in the
case of c-toggle-auto-hungry-state) and a negative value will
turn it (or them) off.
Most punctuation keys provide electric behavior - as well as
inserting themselves they perform some other action, such as
reindenting the line. This reindentation saves you from having to
reindent a line manually after typing, say, a `}'. A few
keywords, such as else, also trigger electric action.
You can inhibit the electric behaviour described here by disabling electric minor mode (see Minor Modes).
Common to all these keys is that they only behave electrically when
used in normal code (as contrasted with getting typed in a string
literal or comment). Those which cause re-indentation do so only when
c-syntactic-indentation has a non-nil value (which it
does by default).
These keys and keywords are:
c-electric-pound) is electric when typed as the
first non-whitespace character on a line and not within a macro
definition. In this case, the variable c-electric-pound-behavior
is consulted for the electric behavior. This variable takes a list
value, although the only element currently defined is alignleft,
which tells this command to force the `#' character into column
zero. This is useful for entering preprocessor macro definitions.
Pound is not electric in AWK buffers, where `#' starts a comment,
and is bound to self-insert-command like any typical printable
character.
c-electric-star) or a slash
(c-electric-slash) causes reindentation when you type it as the
second component of a C style block comment opener (`/*') or a
C++ line comment opener (`//') respectively, but only if the
comment opener is the first thing on the line (i.e. there's only
whitespace before it).
Additionally, you can configure CC Mode so that typing a slash at the start of a line within a block comment will terminate the comment. You don't need to have electric minor mode enabled to get this behaviour. See Clean-ups.
In AWK mode, `*' and `/' do not delimit comments and are not
electric.
c-electric-lt-gt) is
electric in two circumstances: when it is an angle bracket in a C++
`template' declaration (and similar constructs in other
languages) and when it is the second of two < or >
characters in a C++ style stream operator. In either case, the line
is reindented. Angle brackets in C `#include' directives are not
electric.
c-electric-paren) reindent the current line. This is useful
for getting the closing parenthesis of an argument list aligned
automatically.
You can also configure CC Mode to insert a space automatically
between a function name and the `(' you've just typed, and to
remove it automatically after typing `)', should the argument
list be empty. You don't need to have electric minor mode enabled to
get these actions. See Clean-ups.
c-electric-brace) reindents the
current line. Also, one or more newlines might be inserted if
auto-newline minor mode is enabled. See Auto-newlines.
Additionally, you can configure CC Mode to compact excess whitespace
inserted by auto-newline mode in certain circumstances.
See Clean-ups.
c-electric-colon) reindents the
current line. Additionally, one or more newlines might be inserted if
auto-newline minor mode is enabled. See Auto-newlines. If you
type a second colon immediately after such an auto-newline, by default
the whitespace between the two colons is removed, leaving a C++ scope
operator. See Clean-ups.
If you prefer, you can insert `::' in a single operation,
avoiding all these spurious reindentations, newlines, and clean-ups.
See Other Commands.
c-electric-semi&comma)
reindents the current line. Also, a newline might be inserted if
auto-newline minor mode is enabled. See Auto-newlines.
Additionally, you can configure CC Mode so that when auto-newline
has inserted whitespace after a `}', it will be removed again
when you type a semicolon or comma just after it. See Clean-ups.
Certain keywords are electric, causing reindentation when they are preceded only by whitespace on the line. The keywords are those that continue an earlier statement instead of starting a new one:
else,while,catch(only in C++ and Java) andfinally(only in Java).An example:
for (i = 0; i < 17; i++) if (a[i]) res += a[i]->offset; elseHere, the
elseshould be indented like the precedingif, since it continues that statement. CC Mode will automatically reindent it after theelsehas been typed in full, since only then is it possible to decide whether it's a new statement or a continuation of the precedingif.CC Mode uses Abbrev mode (see Abbrevs) 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.
When you have Auto-newline minor mode enabled (see Minor Modes), CC Mode inserts newlines for you automatically (in certain syntactic contexts) when you type a left or right brace, a colon, a semicolon, or a comma. Sometimes a newline appears before the character you type, sometimes after it, sometimes both.
Auto-newline only triggers when the following conditions hold:
You can configure the precise circumstances in which newlines get inserted (see see Custom Auto-newlines). Typically, the style system (see Styles) will have set this up for you, so you probably won't have to bother.
Sometimes CC Mode inserts an auto-newline where you don't want one, such as after a `}' when you're about to type a `;'. Hungry deletion can help here (see Hungry WS Deletion), or you can activate an appropriate clean-up, which will remove the excess whitespace after you've typed the `;'. See Clean-ups for a full description. See also Electric Keys for a summary of clean-ups listed by key.
If you want to delete an entire block of whitespace at point, you can use hungry deletion. This deletes all the contiguous whitespace either before point or after point in a single operation. “Whitespace” here includes tabs and newlines, but not comments or preprocessor commands. Hungry deletion can markedly cut down on the number of times you have to hit deletion keys when, for example, you've made a mistake on the preceding line and have already pressed C-j.
Hungry deletion is a simple feature that some people find extremely useful. In fact, you might find yourself wanting it in all your editing modes!
Loosely speaking, in what follows, <DEL> means “the backspace key” and <DELETE> means “the forward delete key”. This is discussed in more detail below.
There are two different ways you can use hungry deletion:
c-electric-backspace)c-backspace-function,
passing it the prefix argument, if any.)
c-backspace-functionc-electric-backspace when it doesn't
do an “electric” deletion of the preceding whitespace. The default
value is backward-delete-char-untabify
(see Deletion, the function which
deletes a single character.
c-electric-delete-forward)c-electric-backspace but in the forward direction. When it
doesn't do an “electric” deletion of the following whitespace, it
just does delete-char, more or less. (Strictly speaking, it
calls the function in c-delete-function with the prefix
argument.)
c-delete-functionc-electric-delete-forward when it
doesn't do an “electric” deletion of the following whitespace. The
default value is delete-char.
c-hungry-delete-backwards and
c-hungry-delete-forward directly through their key sequences
rather than using the minor mode toggling.
c-hungry-delete-backwards)12c-hungry-delete-forward)When we talk about <DEL>, and <DELETE> above, we actually do so without connecting them to the physical keys commonly known as <Backspace> and <Delete>. The default bindings to those two keys depends on the flavor of (X)Emacs you are using.
In XEmacs 20.3 and beyond, the <Backspace> key is bound to
c-electric-backspace and the <Delete> key is bound to
c-electric-delete. You control the direction it deletes in by
setting the variable delete-key-deletes-forward, a standard
XEmacs variable.
When this variable is non-nil, c-electric-delete will do
forward deletion with c-electric-delete-forward, otherwise it
does backward deletion with c-electric-backspace. Similarly,
C-c <Delete> and C-c C-<Delete> are bound to
c-hungry-delete which is controlled in the same way by
delete-key-deletes-forward.
Emacs 21 and later automatically binds <Backspace> and
<Delete> to DEL and C-d according to your environment,
and CC Mode extends those bindings to C-c C-<Backspace>
etc. If you need to change the bindings through
normal-erase-is-backspace-mode then CC Mode will also adapt
its extended bindings accordingly.
In earlier (X)Emacs versions, CC Mode doesn't bind either <Backspace> or <Delete> directly. Only the key codes DEL and C-d are bound, and it's up to the default bindings to map the physical keys to them. You might need to modify this yourself if the defaults are unsuitable.
Getting your <Backspace> and <Delete> keys properly set up can sometimes be tricky. The information in DEL Does Not Delete, might be helpful if you're having trouble with this in GNU Emacs.
In spite of the GNU Coding Standards, it is popular to name a symbol by mixing uppercase and lowercase letters, e.g. `GtkWidget', `EmacsFrameClass', or `NSGraphicsContext'. Here we call these mixed case symbols nomenclatures. Also, each capitalized (or completely uppercase) part of a nomenclature is called a subword. Here are some examples:
| Nomenclature | Subwords
|
| ————————————————————————————
| |
| `GtkWindow' | `Gtk' and `Window'
|
| `EmacsFrameClass' | `Emacs', `Frame', and `Class'
|
| `NSGraphicsContext' | `NS', `Graphics', and `Context'
|
The subword minor mode replaces the basic word oriented movement and editing commands with variants that recognize subwords in a nomenclature and treat them as separate words:
| Key | Word oriented command | Subword oriented command
|
| —————————————————————————————————————–
| ||
| M-f | forward-word | c-forward-subword
|
| M-b | backward-word | c-backward-subword
|
| M-@ | mark-word | c-mark-subword
|
| M-d | kill-word | c-kill-subword
|
| M-DEL | backward-kill-word | c-backward-kill-subword
|
| M-t | transpose-words | c-transpose-subwords
|
| M-c | capitalize-word | c-capitalize-subword
|
| M-u | upcase-word | c-upcase-subword
|
| M-l | downcase-word | c-downcase-subword
|
Note that if you have changed the key bindings for the word oriented commands in your .emacs or a similar place, the keys you have configured are also used for the corresponding subword oriented commands.
Type C-c C-w to toggle subword mode on and off. To make the mode turn on automatically, put the following code in your .emacs:
(add-hook 'c-mode-common-hook
(lambda () (c-subword-mode 1)))
As a bonus, you can also use c-subword-mode in non-CC Mode
buffers by typing M-x c-subword-mode.
Here are the various other commands that didn't fit anywhere else:
c-set-style) C-c . style-name <RET>
You can use the <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 not automatically reindent your file. For commands that you can use to view the effect of your changes, see Indentation Commands and Filling and Breaking.
For details of the CC Mode style system, see Styles.
c-scope-operator)c-backslash-region)With no prefix argument, it inserts any missing backslashes and aligns
them according to the c-backslash-column and
c-backslash-max-column variables. With a prefix argument, it
deletes any backslashes.
The function does not modify blank lines at the start of the region. If the region ends at the start of a line, it always deletes the backslash (if any) at the end of the previous line.
To customize the precise workings of this command, Custom Macros.
The recommended line breaking function, c-context-line-break
(see Filling and Breaking), is especially nice if you edit
multiline macros frequently. When used inside a macro, it
automatically inserts and adjusts the mandatory backslash at the end
of the line to keep the macro together, and it leaves the point at the
right indentation column for the code. Thus you can write code inside
macros almost exactly as you can elsewhere, without having to bother
with the trailing backslashes.
c-macro-expand)The command does not work in any of the other modes, and the key sequence is not bound in these other modes.
c-macro-expand isn't actually part of CC Mode, even though it
is bound to a CC Mode key sequence. If you need help setting it up
or have other problems with it, you can either read its source code or
ask for help in the standard (X)Emacs forums.
CC Mode provides font locking for its supported languages by supplying patterns for use with Font Lock mode. This means that you get distinct faces on the various syntactic parts such as comments, strings, keywords and types, which is very helpful in telling them apart at a glance and discovering syntactic errors. See Font Lock, for ways to enable font locking in CC Mode buffers.
Please note: The font locking in AWK mode is currently not integrated with the rest of CC Mode. Only the last section of this chapter, AWK Mode Font Locking, applies to AWK. The other sections apply to the other languages.
The font locking for most of the CC Mode languages were provided directly by the Font Lock package prior to version 5.30 of CC Mode. In the transition to CC Mode the patterns have been reworked completely and are applied uniformly across all the languages except AWK mode, just like the indentation rules (although each language still has some peculiarities of its own, of course). Since the languages previously had completely separate font locking patterns, this means that it's a bit different in most languages now.
The main goal for the font locking in CC Mode is accuracy, to provide
a dependable aid in recognizing the various constructs. Some, like
strings and comments, are easy to recognize while others, like
declarations and types, can be very tricky. CC Mode can go to great
lengths to recognize declarations and casts correctly, especially when
the types aren't recognized by standard patterns. This is a fairly
demanding analysis which can be slow on older hardware, and it can
therefore be disabled by choosing a lower decoration level with the
variable font-lock-maximum-decoration (see Font Lock).
The decoration levels are used as follows:
*-font-lock-extra-types (where `*' is the name of the
language) are used to recognize types (see below). Documentation
comments like Javadoc are fontified according to
c-doc-comment-style (see Doc Comments).
Use this if you think the font locking is too slow. It's the closest corresponding level to level 3 in the old font lock patterns.
*-font-lock-extra-types variables are still used, but user
defined types are recognized correctly anyway in most cases. Therefore
those variables should be fairly restrictive and not contain patterns
that are uncertain.
This level is designed for fairly modern hardware and a font lock support mode like Lazy Lock or Just-in-time Lock mode that only fontifies the parts that are actually shown. Fontifying the whole buffer at once can easily get bothersomely slow even on contemporary hardware. See Font Lock.
Since user defined types are hard to recognize you can provide additional regexps to match those you use:
For each language there's a variable
*-font-lock-extra-types, where `*' stands for the language in question. It contains a list of regexps that matches identifiers that should be recognized as types, e.g. `\\sw+_t' to recognize all identifiers ending with `_t' as is customary in C code. Each regexp should not match more than a single identifier.The default values contain regexps for many types in standard runtime libraries that are otherwise difficult to recognize, and patterns for standard type naming conventions like the `_t' suffix in C and C++. Java, Objective-C and Pike have as a convention to start class names with capitals, so there are patterns for that in those languages.
Despite the names of these variables, they are not only used for fontification but in other places as well where CC Mode needs to recognize types.
CC Mode attempts to use the standard faces for programming languages
in accordance with their intended purposes as far as possible. No extra
faces are currently provided, with the exception of a replacement face
c-invalid-face for emacsen that don't provide
font-lock-warning-face.
font-lock-comment-face.
font-lock-doc-face (Emacs) or
font-lock-doc-string-face (XEmacs) if those faces exist. If
they don't then font-lock-comment-face is used.
font-lock-string-face.
font-lock-keyword-face.
font-lock-function-name-face is used for function names in
declarations and definitions, and classes in those contexts. It's also
used for preprocessor defines with arguments.
font-lock-variable-name-face. It's also
used for preprocessor defines without arguments.
font-lock-constant-face if it
exists, font-lock-reference-face otherwise. As opposed to the
preceding two faces, this is used on the names in expressions, and it's
not used in declarations, even if there happen to be a `const' in
them somewhere.
font-lock-type-face is put on types (both predefined and user
defined) and classes in type contexts.
font-lock-constant-face if it exists,
font-lock-reference-face otherwise.
font-lock-preprocessor-face if it
exists (i.e. XEmacs). In Emacs they get font-lock-builtin-face
or font-lock-reference-face, for lack of a closer equivalent.
font-lock-warning-face in Emacs. In older XEmacs versions
there's no corresponding standard face, so there a special
c-invalid-face is used, which is defined to stand out sharply by
default.
Note that it's not used for `#error' or `#warning' directives, since those aren't syntactic errors in themselves.
There are various tools to supply documentation in the source as specially structured comments, e.g. the standard Javadoc tool in Java. CC Mode provides an extensible mechanism to fontify such comments and the special markup inside them.
This is a style variable that specifies which documentation comment style to recognize, e.g.
javadocfor Javadoc comments.The value may also be a list of styles, in which case all of them are recognized simultaneously (presumably with markup cues that don't conflict).
The value may also be an association list to specify different comment styles for different languages. The symbol for the major mode is then looked up in the alist, and the value of that element is interpreted as above if found. If it isn't found then the symbol `other' is looked up and its value is used instead.
The default value for
c-doc-comment-styleis((java-mode . javadoc) (pike-mode . autodoc) (c-mode . gtkdoc)).Note that CC Mode uses this variable to set other variables that handle fontification etc. That's done at mode initialization or when you switch to a style which sets this variable. Thus, if you change it in some other way, e.g. interactively in a CC Mode buffer, you will need to do M-x java-mode (or whatever mode you're currently using) to reinitialize.
Note also that when CC Mode starts up, the other variables are modified before the mode hooks are run. If you change this variable in a mode hook, you'll have to call
c-setup-doc-comment-styleafterwards to redo that work.
CC Mode currently provides handing of the following doc comment styles:
javadocautodocgtkdocThe above is by no means complete. If you'd like to see support for other doc comment styles, please let us know (see Mailing Lists and Bug Reports).
You can also write your own doc comment fontification support to use
with c-doc-comment-style: Supply a variable or function
*-font-lock-keywords where `*' is the name you want to use
in c-doc-comment-style. If it's a variable, it's prepended to
font-lock-keywords. If it's a function, it's called at mode
initialization and the result is prepended. For an example, see
javadoc-font-lock-keywords in cc-fonts.el.
If you add support for another doc comment style, please consider contributing it - send a note to bug-cc-mode@gnu.org.
The general appearance of font-locking in AWK mode is much like in any other programming mode. See Faces For Font Lock.
The following faces are, however, used in a non-standard fashion in AWK mode:
font-lock-variable-name-faceNF) and “Special File Names” (such as
"/dev/stderr").
font-lock-builtin-face (Emacs)/font-lock-preprocessor-face (XEmacs)match).
font-lock-string-facefont-lock-warning-face (Emacs)/c-invalid-face (XEmacs)font-lock-warning-face. This is most noticeable when typing in a
new string/regular expression into a buffer, when the warning-face
serves as a continual reminder to terminate the construct.
AWK mode fontifies unterminated strings/regular expressions differently from other modes: Only the text up to the end of the line is fontified as a string (escaped newlines being handled correctly), rather than the text up to the next string quote.
You configure CC Mode by setting Lisp variables and calling (and perhaps writing) Lisp functions13, which is usually done by adding code to an Emacs initialization file. This file might be site-start.el or .emacs or init.el or default.el or perhaps some other file. See Init File. For the sake of conciseness, we just call this file “your .emacs” throughout the rest of the manual.
Several of these variables (currently 16), are known collectively as style variables. CC Mode provides a special mechanism, known as styles to make it easier to set these variables as a group, to “inherit” settings from one style into another, and so on. Style variables remain ordinary Lisp variables, whose values can be read and changed independently of the style system. See Style Variables.
There are several ways you can write the code, depending on the precise effect you want—they are described further down on this page. If you are new to CC Mode, we suggest you begin with the simplest method, “Top-level commands or the customization interface”.
If you make conflicting settings in several of these ways, the way that takes precedence is the one that appears latest in this list:
Here is a summary of the different ways of writing your configuration settings:
setq and similar commands at the top
level of your .emacs file. When you load a CC Mode buffer,
it initializes its configuration from these global values (at least,
for those settings you have given values to), so it makes sense to
have these setq commands run before CC Mode is first
initialized—in particular, before any call to desktop-read
(see Saving Emacs Sessions). For
example, you might set c-basic-offset thus:
(setq c-basic-offset 4)
You can use the more user friendly Customization interface instead,
but this manual does not cover in detail how that works. To do this,
start by typing M-x customize-group <RET> c <RET>.
See Easy Customization.
Emacs normally writes the customizations at the end of your
.emacs file. If you use desktop-read, you should edit
your .emacs to place the call to desktop-read after
the customizations.
The first initialization of CC Mode puts a snapshot of the
configuration settings into the special style user.
See Built-in Styles.
For basic use of Emacs, either of these ways of configuring is
adequate. However, the settings are then the same in all CC Mode
buffers and it can be clumsy to communicate them between programmers.
For more flexibility, you'll want to use one (or both) of CC Mode's
more sophisticated facilities, hooks and styles.
c-basic-offset in C
Mode and Java Mode buffers, you could do it like this:
(defun my-c-mode-hook ()
(setq c-basic-offset 3))
(add-hook 'c-mode-hook 'my-c-mode-hook)
(defun my-java-mode-hook ()
(setq c-basic-offset 6))
(add-hook 'java-mode-hook 'my-java-mode-hook)
See CC Hooks for more details on the use of CC Mode hooks.
(setq c-default-style '((java-mode . "java")
(awk-mode . "awk")
(other . "free-group-style")))
See Styles for fuller details on using CC Mode styles and how
to create them.
(defun my-c-mode-hook ()
(c-set-style
(if (and (buffer-file-name)
(string-match "/usr/src/linux" (buffer-file-name)))
"linux"
"free-group-style")))
(add-hook 'c-mode-hook 'my-c-mode-hook)
In a programming team, a hook is a also a good place for each member to put his own personal preferences. For example, you might be the only person in your team who likes Auto-newline minor mode. You could have it enabled by default by placing the following in your .emacs:
(defun my-turn-on-auto-newline ()
(c-toggle-auto-newline 1))
(add-hook 'c-mode-common-hook 'my-turn-on-auto-newline)
CC Mode provides several hooks that you can use to customize the
mode for your coding style. The main hook is
c-mode-common-hook; typically, you'll put the bulk of your
customizations here. In addition, each language mode has its own
hook, allowing you to fine tune your settings individually for the
different CC Mode languages, and there is a package initialization
hook. Finally, there is c-special-indent-hook, which enables
you to solve anomalous indentation problems. It is described in
Other Indentation, not here. All these hooks adhere to the
standard Emacs conventions.
When you open a buffer, CC Mode first initializes it with the
currently active style (see Styles). Then it calls
c-mode-common-hook, and finally it calls the language-specific
hook. Thus, any style settings done in these hooks will override
those set by c-default-style.
Hook run only once per Emacs session, when CC Mode is initialized. This is a good place to change key bindings (or add new ones) in any of the CC Mode key maps. See Sample .emacs File.
Common hook across all languages. It's run immediately before the language specific hook.
The language specific mode hooks. The appropriate one is run as the last thing when you enter that language mode.
Although these hooks are variables defined in CC Mode, you can give
them values before CC Mode's code is loaded—indeed, this is the
only way to use c-initialization-hook. Their values aren't
overwritten when CC Mode gets loaded.
Here's a simplified example of what you can add to your .emacs file to do things whenever any CC Mode language is edited. See the Emacs manuals for more information on customizing Emacs via hooks. See Sample .emacs File, for a more complete sample .emacs file.
(defun my-c-mode-common-hook ()
;; my customizations for all of c-mode and related modes
(no-case-fold-search)
)
(add-hook 'c-mode-common-hook 'my-c-mode-common-hook)
The variables that CC Mode's style system control are called style variables. Note that style variables are ordinary Lisp variables, which the style system initializes; you can change their values at any time (e.g. in a hook function). The style system can also set other variables, to some extent. See Styles.
Style variables are handled specially in several ways:
c-style-variables-are-local-p to nil before CC Mode is
initialized.
set-from-style. When the
style system initializes a buffer-local copy of a style variable for a
CC Mode buffer, if its global binding is still that symbol then it
will be set from the current style. Otherwise it will retain its
global default14. This
“otherwise” happens, for example, when you've set the variable with
setq at the top level of your .emacs (see Config Basics).
c-offsets-alist (see c-offsets-alist) is
an association list with an element for each syntactic symbol. It's
handled a little differently from the other style variables. It's
default global binding is the empty list nil, rather than
set-from-style. Before the style system is initialized, you
can add individual elements to c-offsets-alist by calling
c-set-offset(see c-offsets-alist) just like you would set
other style variables with setq. Those elements will then
prevail when the style system later initializes a buffer-local copy of
c-offsets-alist.
c-special-indent-hook is also handled in a
special way. Styles can only add functions to this hook, not remove
them, so any global settings you put on it are always
preserved15. The value
you give this variable in a style definition can be either a function
or a list of functions.
user style when the style system is first initialized.
See Built-in Styles, for details.
The style variables are:
c-indent-comment-alist,
c-indent-comments-syntactically-p (see Indentation Commands);
c-doc-comment-style (see Doc Comments);
c-block-comment-prefix, c-comment-prefix-regexp
(see Custom Filling and Breaking);
c-hanging-braces-alist (see Hanging Braces);
c-hanging-colons-alist (see Hanging Colons);
c-hanging-semi&comma-criteria (see Hanging Semicolons and Commas);
c-cleanup-list (see Clean-ups);
c-basic-offset (see Customizing Indentation);
c-offsets-alist (see c-offsets-alist);
c-comment-only-line-offset (see Comment Line-Up);
c-special-indent-hook, c-label-minimum-indentation
(see Other Indentation);
c-backslash-column, c-backslash-max-column
(see Custom Macros).
By 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 programmers come and go, there could be a number of styles in use. For this reason, CC Mode makes it convenient for you to set up logical groupings of customizations called styles, associate a single name for any particular style, and pretty easily start editing new or existing code using these styles.
If you're lucky, one of CC Mode's built-in styles might be just what you're looking for. These are:
gnuk&rbsdwhitesmithstroustrupellemtellinuxpythonjavac-default-style installs this style when you enter
java-mode.
awkc-default-style installs this style when you enter
awk-mode.
usersetqs and c-set-offsets at the top level of your
.emacs file (see Config Basics). The style system creates
this style as part of its initialization and doesn't modify it
afterwards.
When you create a new buffer, its style will be set from
c-default-style. The factory default is the style gnu,
except in Java and AWK modes where it's java and awk.
Remember that if you set a style variable with the Customization interface or at the top level of your .emacs file before the style system is initialised (see 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 C-c . (see Other Commands). To set it from a file's local variable list, File Styles.
This variable specifies which style to install by default in new buffers. It takes either a style name string, or an association list of major mode symbols to style names:
- When
c-default-styleis a string, it must be an existing style name. This style is then used for all modes.- When
c-default-styleis an association list, the mode language is looked up to find a style name string.- If
c-default-styleis an association list where the mode language mode isn't found then the special symbol `other' is looked up. If it's found then the associated style is used.- If `other' is not found then the `gnu' style is used.
In all cases, the style described in
c-default-styleis installed before the language hooks are run, so you can always override this setting by including an explicit call toc-set-stylein your language mode hook, or inc-mode-common-hook.The standard value of
c-default-styleis((java-mode . "java") (awk-mode . "awk") (other . "gnu")).
This variable always contains the buffer's current style name, as a string.
If none of the built-in styles is appropriate, you'll probably want to
create a new style definition, possibly based on an existing
style. To do this, put the new style's settings into a list with the
following format - the list can then be passed as an argument to the
function c-add-style. You can see an example of a style
definition in Sample .emacs File.
Optional base-style, if present, must be a string which is the name of the base style from which this style inherits. At most one base-style is allowed in a style definition. If base-style is not specified, the style inherits from the table of factory default values18 instead. All styles eventually inherit from this internal table. Style loops generate errors. The list of pre-existing styles can be seen in Built-in Styles.
The dotted pairs (variable . value) each consist of a variable and the value it is to be set to when the style is later activated.19 The variable can be either a CC Mode style variable or an arbitrary Emacs variable. In the latter case, it is not made buffer-local by the CC Mode style system.
Two variables are treated specially in the dotted pair list:
c-offsets-alist (syntactic-symbol . offset)
as described in c-offsets-alist. These are passed to
c-set-offset so there is no need to set every syntactic symbol
in your style, only those that are different from the inherited style.
c-special-indent-hookc-special-indent-hook using
add-hook<