@ccmode{} 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 @ccmode{} can be configured so that it starts 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 @ccmode{} buffer. When auto-newline mode is enabled, you will see `C/a' on the mode line (7). When hungry delete mode is enabled you would see `C/h' and when both modes are enabled, you'd see `C/ah'.
@ccmode{} provides keybindings which allow you to toggle the minor
modes on the fly while editing code. 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,
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:
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 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
,
statement-case-open
,
extern-lang-open
, and extern-lang-close
.
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 the ACTION is a list, it can contain any combination of the
symbols before
and after
, directing @ccmode{} 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) (extern-lang-open after)))
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
and extern-lang-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.
A word of caution: it is not a good idea to hang top-level construct
introducing braces, such as class-open
or defun-open
.
Emacs makes an assumption that such braces will always appear in column
zero, hanging such braces can introduce performance problems.
See section Performance Issues for more information.
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 assocation list are: case-label
, label
,
access-label
, member-init-intro
, and inher-intro
.
Note however that for c-hanging-colons-alist
, ACTIONs as
functions are not supported. See also section Custom Brace and Colon Hanging for details.
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 @ccmode{}. See section Clean-ups for details.
Semicolons and commas are also electric in @ccmode{}, 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
# (c-electric-pound
) is electric when 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 /, c-electric-star
and
c-electric-slash
respectively) 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
.
Less-than and greater-than signs (c-electric-lt-gt
) are also
electric, but only in C++ mode. Hitting the second of two < or
> keys re-indents the line if it is a C++ style stream operator.
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 is inserted by electric
commands, or whitespace that contains intervening constructs.
You can configure @ccmode{}'s clean-ups by setting the variable
c-cleanup-list
, which is a list of clean-up symbols. By default,
@ccmode{} 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 @ccmode{} 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 {
brace-elseif-brace
-- similar to the brace-else-brace
clean-up, but cleans up `} else if (...){' constructs. For
example:
void spam(int i) { if( i==7 ) { dosomething(); } else if( i==3 ) {appears like this after the open brace is typed:
void spam(int i) { if( i==7 ) { dosomething(); } else if( i==3 ) {
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(9). 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 Backspace key(10) will consume all preceding whitespace, including newlines and tabs. This can really cut down on the number of Backspace's you have to type if, for example you made a mistake on the preceding line.
By default, when you hit the Backspace key
@ccmode{} runs the command c-electric-backspace
, which deletes
text in the backwards direction. When deleting a single character, or
when Backspace is hit in a literal
(see section Auto-newline insertion),
or when hungry-delete mode is disabled, the function
contained in the c-backspace-function
variable is called with one
argument (the number of characters to delete). This variable is set to
backward-delete-char-untabify
by default.
Similarly, hitting the DEL key runs the command
c-electric-delete
. Some versions of Emacs(11) support separation
of the Backspace and DEL keys, so that DEL will delete
in the forward direction when delete-key-deletes-forward
is
non-nil
. If your Emacs supports this, and
delete-key-deletes-forward
is non-nil
, and hungry-delete
mode is enabled, then DEL will consume all whitespace following
point. When deleting a single character, or when DEL is hit in a
literal, or when hungry-delete mode is disabled, the function contained
in the c-delete-function
variable is called with one argument
(the number of characters to delete). This variable is set to
delete-char
by default.
However, if delete-key-deletes-forward
is nil
, or your
Emacs does not support separation of Backspace and DEL, then
c-electric-delete
simply calls c-electric-backspace
.
One other note about minor modes is worth mentioning here. CC Mode now
works much better with auto-fill mode (a standard Emacs minor mode) by
correctly auto-filling both line (e.g. C++ style) and block (e.g. C
style) oriented comments. When auto-fill-mode
is enabled, line
oriented comments will also be auto-filled by inserting a newline at the
line break, and inserting `//' at the start of the next line.
When auto-filling block oriented comments, the behavior is dependent on
the value of the variable c-comment-continuation-stars
. When
this variable is nil
, the old behavior for auto-filling C
comments is in effect. In this case, the line is broken by closing the
comment and starting a new comment on the next line.
If you set c-comment-continuation-stars
to a string, then a long
C block comment line is broken by inserting a newline at the line break
position, and inserting this string at the beginning of the next comment
line. The default value for c-comment-continuation-stars
is
`* ' (a star followed by a single space)(12).
Go to the first, previous, next, last section, table of contents.