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


Minor Modes

@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 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:

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 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.

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 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.

Hanging Semi-colons and commas

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.

Other electric commands

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

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:

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 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.

Auto-fill mode interaction

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.