GNU Info

(ccmode)Hanging Braces

---

Next: Hanging Colons Up: Auto-newline Insertion

---

Enter node , (file) or (file)node

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'(1).  Note: 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(2).

   The value associated with each syntactic symbol in this association
list is called an ACTION which can be either a function or a list.
Note: 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.

   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:

       ((brace-list-open)
        (brace-entry-open)
        (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.  Note: Performance
Issues, for more information.

   ---------- Footnotes ----------

   (1) Note that the aggregate constructs in Pike mode, `({', `})',
`([', `])', and `(<', `>)', do not count as brace lists in this regard,
even though they do for normal indentation purposes.  It's currently
not possible to set automatic newlines on these constructs.

   (2) The braces of anonymous classes produces a combination of
`inexpr-class', and `class-open' or `class-close' in normal indentation
analysis.