cc-mode
contains two minor-mode-like features that you should
find useful while you enter new C code. The first is called
auto-newline mode, and the second is called hungry-delete
mode. These minor modes can be toggled on and off independently, and
cc-mode
can be configured so that it comes up with any
combination of these minor modes. By default, both of these minor modes
are turned off.
The state of the minor modes is always reflected in the minor mode list
on the modeline of the cc-mode
buffer. When auto-newline mode is
enabled, you will see `C/a' on the mode line (5). When hungry delete mode is
enabled you would see `C/h' and when both modes are enabled, you'd
see `C/ah'.
cc-mode
provides keybindings which allow you to toggle the minor
modes while editing code on the fly. To toggle just the auto-newline
state, hit C-c C-a (c-toggle-auto-state
). When you do
this, you should see the `a' indicator either appear or disappear
on the modeline. Similarly, to toggle just the hungry-delete state, use
C-c C-d (c-toggle-hungry-state
), and to toggle both states
together, use C-c C-t (c-toggle-auto-hungry-state
).
To set up the auto-newline and hungry-delete states to your preferred
values, you would need to add some lisp to your `.emacs' file that
called one of the c-toggle-*-state
functions directly. When
called programmatically, each function takes a numeric value, where
a positive number enables the minor mode, a negative number disables the
mode, and zero toggles the current state of the mode.
So for example, if you wanted to enable both auto-newline and hungry-delete for all your C file editing, you could add the following to your `.emacs' file:
(add-hook 'c-mode-common-hook '(lambda () (c-toggle-auto-hungry-state 1)))
Auto-newline minor mode works by enabling certain electric commands. Electric commands are typically bound to special characters such as the left and right braces, colons, semi-colons, etc., which when typed, perform some magic formatting in addition to inserting the typed character. As a general rule, electric commands are only electric when the following conditions apply:
Certain other conditions may apply on a language specific basis. For
example, the second slash (/) of a C++ style line comment is
electric in c++-mode
, objc-mode
, and java-mode
, but
not in c-mode
.
When you type either an open or close brace (i.e. { or }),
the electric command c-electric-brace
gets run. This command has
two electric formatting behaviors. First, it will perform some
re-indentation of the line the brace was typed on, and second, it will
add various newlines before and/or after the typed brace.
Re-indentation occurs automatically whenever the electric behavior is
enabled. If the brace ends up on a line other than the one it was typed
on, then that line is on is also indented according to
c-offsets-alist
.
The insertion of newlines is controlled by the
c-hanging-braces-alist
variable. This variable contains a
mapping between syntactic symbols related to braces, and a list of
places to insert a newline. The syntactic symbols that are useful for
this list are: class-open
, class-close
, defun-open
,
defun-close
, inline-open
, inline-close
,
brace-list-open
, brace-list-close
,
brace-list-intro
, brace-list-entry
, block-open
,
block-close
, substatement-open
, and
statement-case-open
. See section Syntactic Symbols for a more
detailed description of these syntactic symbols.
The value associated with each syntactic symbol in this association list is called an ACTION which can be either a function or a list. See section Custom Brace and Colon Hanging for a more detailed discussion of using a function as a brace hanging ACTION.
When ACTION is a list, it can contain any combination of the
symbols before
or after
, directing cc-mode
where to
put newlines in relationship to the brace being inserted. Thus, if the
list contains only the symbol after
, then the brace is said to
hang on the right side of the line, as in:
// here, open braces always `hang' void spam( int i ) { if( i == 7 ) { dosomething(i); } }
When the list contains both after
and before
, the braces
will appear on a line by themselves, as shown by the close braces in the
above example. The list can also be empty, in which case no newlines
are added either before or after the brace.
For example, the default value of c-hanging-braces-alist
is:
(defvar c-hanging-braces-alist '((brace-list-open) (substatement-open after) (block-close . c-snug-do-while)))
which says that brace-list-open
braces should both hang on the
right side, and allow subsequent text to follow on the same line as the
brace. Also, substatement-open
braces should hang on the right
side, but subsequent text should follow on the next line. Here, in the
block-close
entry, you also see an example of using a function as
an ACTION.
Using a mechanism similar to brace hanging (see section Hanging Braces),
colons can also be made to hang using the variable
c-hanging-colons-alist
. The syntactic symbols appropriate for
this association list are: case-label
, label
,
access-label
, member-init-intro
, and inher-intro
.
See section Hanging Braces and section Custom Brace and Colon Hanging for
details. Note however, that c-hanging-colons-alist
does not
implement functions as ACTIONs.
In C++, double-colons are used as a scope operator but because these
colons always appear right next to each other, newlines before and after
them are controlled by a different mechanism, called clean-ups in
cc-mode
. See section Clean-ups for details.
Semicolons and commas are also electric in cc-mode
, but since
these characters do not correspond directly to syntactic symbols, a
different mechanism is used to determine whether newlines should be
automatically inserted after these characters. See section Customizing Semi-colons and Commas for details.
A few other keys also provide electric behavior. For example the
# key (c-electric-pound
) is electric when it is typed as
the first non-whitespace character on a line. 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
cpp macro definitions.
Stars and slashes (i.e. * and /) are also electric under
certain circumstances. If a star is inserted as the second character of
a C style block comment on a comment-only line, then the comment
delimiter is indented as defined by c-offsets-alist
. A
comment-only line is defined as a line which contains only a comment, as
in:
void spam( int i ) { // this is a comment-only line... if( i == 7 ) // but this is not { dosomething(i); } }
Likewise, if a slash is inserted as the second slash in a C++ style line
comment (also only on a comment-only line), then the line is indented as
defined by c-offsets-alist
.
Clean-ups are a mechanism complementary to colon and brace
hanging. On the surface, it would seem that clean-ups overlap the
functionality provided by the c-hanging-*-alist
variables, and
similarly, clean-ups are only enabled when auto-newline minor mode is
enabled. Clean-ups are used however to adjust code "after-the-fact",
i.e. to eliminate some whitespace that isn't inserted by electric
commands, or whitespace that contains intervening constructs.
You can configure cc-mode
's clean-ups by setting the variable
c-cleanup-list
, which is a list of clean-up symbols. By default,
cc-mode
cleans up only the scope-operator
construct, which
is necessary for proper C++ support. Note that clean-ups are only
performed when the construct does not occur within a literal (see
section Auto-newline insertion), and when there is nothing but whitespace
appearing between the individual components of the construct.
There are currently only five specific constructs that cc-mode
can clean up, as indicated by these symbols:
brace-else-brace
-- cleans up `} else {' constructs by
placing the entire construct on a single line. Clean-up occurs when the
open brace after the `else' is typed. So for example, this:
void spam(int i) { if( i==7 ) { dosomething(); } else {appears like this after the open brace is typed:
void spam(int i) { if( i==7 ) { dosomething(); } else {
empty-defun-braces
-- cleans up braces following a top-level
function or class definition that contains no body. Clean up occurs
when the closing brace is typed. Thus the following:
class Spam { }is transformed into this when the close brace is typed:
class Spam {}
defun-close-semi
-- cleans up the terminating semi-colon on
top-level function or class definitions when they follow a close
brace. Clean up occurs when the semi-colon is typed.
So for example, the following:
class Spam { } ;is transformed into this when the semi-colon is typed:
class Spam { };
list-close-comma
-- cleans up commas following braces in array
and aggregate initializers. Clean up occurs when the comma is typed.
scope-operator
-- cleans up double colons which may designate a
C++ scope operator split across multiple lines(7). Clean up occurs when
the second colon is typed. You will always want scope-operator
in the c-cleanup-list
when you are editing C++ code.
Hungry deletion of whitespace, or as it more commonly called, hungry-delete mode, is a simple feature that some people find extremely useful. In fact, you might find yourself wanting hungry-delete in all your editing modes!
In a nutshell, when hungry-delete mode is enabled, hitting the DEL character will consume all preceding whitespace, including newlines and tabs. This can really cut down on the number of DEL's you have to type if, for example you made a mistake on the preceding line.
By default, cc-mode
actually runs the command
c-electric-delete
when you hit DEL. When this command is
used to delete a single character (i.e. when it is called interactively
with no numeric argument), it really runs the function contained in the
variable c-delete-function
. This function is called with a
single argument, which is the number of characters to delete.
c-delete-function
is also called when the DEL key is typed
inside a literal (see section Auto-newline insertion. Inside a literal,
c-electric-delete
is not electric, which is typical of all the
so-called electric commands.
Go to the first, previous, next, last section, table of contents.