www.delorie.com/gnu/docs/emacs/cc-mode_8.html   search  
Buy the book!

CC Mode Manual

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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 default in auto-newline mode is to insert newlines both before and after a brace, but that can be controlled by the c-hanging-braces-alist style 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-entry-open, block-open, block-close, substatement-open, statement-case-open, extern-lang-open, extern-lang-close, namespace-open, namespace-close, inexpr-class-open, and inexpr-class-close(9). See section 8. Syntactic Symbols, for a more detailed description of these syntactic symbols, except for inexpr-class-open and inexpr-class-close, which aren't actual syntactic symbols.

The braces of anonymous inner classes in Java are given the special symbols inexpr-class-open and inexpr-class-close, so that they can be distinguished from the braces of normal classes(10).

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 7.5.2 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 ) {

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.

If a syntactic symbol is missing entirely from c-hanging-braces-alist, it's treated in the same way as an ACTION with a list containing before and after, so that braces by default end up on their own line.

For example, the default value of c-hanging-braces-alist is:
   (substatement-open after)
   (block-close . c-snug-do-while)
   (extern-lang-open after)
   (inexpr-class-open after)
   (inexpr-class-close before))

which says that brace-list-open and brace-entry-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, extern-lang-open, and inexpr-class-open braces should hang on the right side, but subsequent text should follow on the next line. The opposite holds for inexpr-class-close braces; they won't hang, but the following text continues on the same line. Here, in the block-close entry, you also see an example of using a function as an ACTION. In all other cases, braces are put on a line by themselves.

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 them can introduce performance problems. See section 10. Performance Issues, for more information.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

  webmaster     delorie software   privacy  
  Copyright 2003   by The Free Software Foundation     Updated Jun 2003