Go to the first, previous, next, last section, table of contents.


Minor Modes

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 insertion

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.

Hanging Braces

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.

Hanging Colons

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.

Hanging Semi-colons and commas

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.

Other electric commands

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

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:

Hungry-deletion of whitespace

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.