Auto-newline insertion Hanging Colons

4.1.1: 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 re-indented.

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, extern-lang-close, namespace-open, and namespace-close. See 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 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 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)
                                 (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 Performance Issues for more information.

Auto-newline insertion

Hanging Colons