8. Customizing Auto-newlines

CC Mode determines whether to insert auto-newlines in two basically different ways, depending on the character just typed:

Braces and Colons

CC Mode first determines the syntactic context of the brace or colon (see section Syntactic Symbols), then looks for a corresponding element in an alist. This element specifies where to put newlines - this is any combination of before and after the brace or colon. If no alist element is found, newlines are inserted both before and after a brace, but none are inserted around a colon. See Hanging Braces and Hanging Colons.

Semicolons and Commas

The variable c-hanging-semi&comma-criteria contains a list of functions which determine whether to insert a newline after a newly typed semicolon or comma. See section Hanging Semicolons and Commas.

The names of these configuration variables contain ‘hanging’ because they let you hang the pertinent characters. A character which introduces a C construct is said to hang on the right when it appears at the end of a line after other code, being separated by a line break from the construct it introduces, like the opening brace in:

while (i < MAX) {
    total += entry[i];
    entry [i++] = 0;
}

A character hangs on the left when it appears at the start of the line after the construct it closes off, like the above closing brace.

The next chapter, “Clean-ups”, describes how to configure CC Mode to remove these automatically added newlines in certain specific circumstances. See section Clean-ups.

8.1 Hanging Braces

To specify which kinds of braces you want auto-newlines put around, you set the style variable c-hanging-braces-alist. Its structure and semantics are described in this section. Details of how to set it up, and its relationship to CC Mode’s style system are given in Style Variables.

Say you wanted an auto-newline after (but not before) the following ‘{’:

if (foo < 17) {

First you need to find the syntactic context of the brace—type a <RET> before the brace to get it on a line of its own(28), then type C-c C-s. That will tell you something like:

((substatement-open 1061))

So here you need to put the entry (substatement-open . (after)) into c-hanging-braces-alist.

If you don’t want any auto-newlines for a particular syntactic symbol, put this into c-hanging-braces-alist:

(brace-entry-open)

If some brace syntactic symbol is not in c-hanging-brace-alist, its entry is taken by default as (before after)—insert a newline both before and after the brace. In place of a “before/after” list you can specify a function in this alist—this is useful when the auto newlines depend on the code around the brace.

User Option: c-hanging-braces-alist

This variable is an association list which maps syntactic symbols to lists of places to insert a newline. See (elisp)Association Lists section ‘Association Lists’ in GNU Emacs Lisp Reference Manual. The key of each element is the syntactic symbol, the associated value is either nil, a list, or a function.

The Key - the syntactic symbol

The syntactic symbols that are useful as keys in this list are brace-list-intro, statement-cont, inexpr-class-open, inexpr-class-close, and all the *-open and *-close symbols. See section 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. Elements with any other value as a key get ignored.

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(29).

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.

The associated value - the “ACTION” list or function

The value associated with each syntactic symbol in this association list is called an action, which can be either a list or a function which returns a list. See section Custom Brace Hanging, for how to use a function as a brace hanging action.

The list action (or the list returned by action when it’s a function) contains some 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 hangs 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 newlines are added neither before nor 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) (statement-cont) (substatement-open after) (block-close . c-snug-do-while) (extern-lang-open after) (namespace-open after) (module-open after) (composition-open after) (inexpr-class-open after) (inexpr-class-close before))

which says that brace-list-open, brace-entry-open and statement-cont(30) 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.

8.1.1 Custom Brace Hanging

Syntactic symbols aren’t the only place where you can customize CC Mode with the lisp equivalent of callback functions. Remember that actions are usually a list containing some combination of the symbols before and after (see section Hanging Braces). For more flexibility, you can instead specify brace “hanginess” by giving a syntactic symbol an action function in c-hanging-braces-alist; this function determines the “hanginess” of a brace, usually by looking at the code near it.

An action function is called with two arguments: the syntactic symbol for the brace (e.g. substatement-open), and the buffer position where the brace has been inserted. Point is undefined on entry to an action function, but the function must preserve it (e.g. by using save-excursion). The return value should be a list containing some combination of before and after, including neither of them (i.e. nil).

Variable: c-syntactic-context

During the call to the indentation or brace hanging action function, this variable is bound to the full syntactic analysis list. This might be, for example, ‘((block-close 73))’. Don’t ever give c-syntactic-context a value yourself—this would disrupt the proper functioning of CC Mode.

This variable is also bound in three other circumstances: (i) when calling a c-hanging-semi&comma-criteria function (see section Hanging Semicolons and Commas); (ii) when calling a line-up function (see section Custom Line-Up Functions); (iii) when calling a c-special-indent-hook function (see section Other Special Indentations).

As an example, CC Mode itself uses this feature to dynamically determine the hanginess of braces which close “do-while” constructs:

void do_list( int count, char** atleast_one_string )
{
    int i=0;
    do {
        handle_string( atleast_one_string[i] );
        i++;
    } while( i < count );
}

CC Mode assigns the block-close syntactic symbol to the brace that closes the do construct, and normally we’d like the line that follows a block-close brace to begin on a separate line. However, with “do-while” constructs, we want the while clause to follow the closing brace. To do this, we associate the block-close symbol with the action function c-snug-do-while:

(defun c-snug-do-while (syntax pos)
  "Dynamically calculate brace hanginess for do-while statements."
  (save-excursion
    (let (langelem)
      (if (and (eq syntax 'block-close)
               (setq langelem (assq 'block-close c-syntactic-context))
               (progn (goto-char (cdr langelem))
                      (if (= (following-char) ?{)
                          (forward-sexp -1))
                      (looking-at "\\<do\\>[^_]")))
          '(before)
        '(before after)))))

This function simply looks to see if the brace closes a “do-while” clause and if so, returns the list ‘(before)’ indicating that a newline should be inserted before the brace, but not after it. In all other cases, it returns the list ‘(before after)’ so that the brace appears on a line by itself.

8.2 Hanging Colons

Using a mechanism similar to brace hanging (see section Hanging Braces), colons can also be made to hang using the style variable c-hanging-colons-alist - When a colon is typed, CC Mode determines its syntactic context, looks this up in the alist c-changing-colons-alist and inserts up to two newlines accordingly. Here, however, If CC Mode fails to find an entry for a syntactic symbol in the alist, no newlines are inserted around the newly typed colon.

User Option: c-hanging-colons-alist

The Key - the syntactic symbol

The syntactic symbols appropriate as keys in this association list are: case-label, label, access-label, member-init-intro, and inher-intro. See section Syntactic Symbols. Elements with any other value as a key get ignored.

The associate value - the “ACTION” list

The action here is simply a list containing a combination of the symbols before and after. Unlike in c-hanging-braces-alist, functions as actions are not supported - there doesn’t seem to be any need for them.

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.

8.3 Hanging Semicolons and Commas

User Option: c-hanging-semi&comma-criteria

This style variable takes a list of functions; these get called when you type a semicolon or comma. The functions are called in order without arguments. When these functions are entered, point is just after the newly inserted ‘;’ or ‘,’ and they must preserve point (e.g., by using save-excursion). During the call, the variable c-syntactic-context is bound to the syntactic context of the current line(31) see section Custom Brace Hanging. These functions don’t insert newlines themselves, rather they direct CC Mode whether or not to do so. They should return one of the following values:

t

A newline is to be inserted after the ‘;’ or ‘,’, and no more functions from the list are to be called.

stop

No more functions from the list are to be called, and no newline is to be inserted.

nil

No determination has been made, and the next function in the list is to be called.

Note that auto-newlines are never inserted before a semicolon or comma. If every function in the list is called without a determination being made, then no newline is added.

In AWK mode, this variable is set by default to nil. In the other modes, the default value is a list containing a single function, c-semi&comma-inside-parenlist. This inserts newlines after all semicolons, apart from those separating for-clause statements.

Function: c-semi&comma-no-newlines-before-nonblanks

This is an example of a criteria function, provided by CC Mode. It prevents newlines from being inserted after semicolons when there is a non-blank following line. Otherwise, it makes no determination. To use, add this function to the front of the c-hanging-semi&comma-criteria list.

(defun c-semi&comma-no-newlines-before-nonblanks () (save-excursion (if (and (= (c-last-command-char) ?\;) (zerop (forward-line 1)) (bolp) ; forward-line has funny behavior at eob. (not (looking-at "^[ \t]*$"))) 'stop nil)))

Function: c-semi&comma-inside-parenlist

Function: c-semi&comma-no-newlines-for-oneline-inliners

The function c-semi&comma-inside-parenlist is what prevents newlines from being inserted inside the parenthesis list of for statements. In addition to c-semi&comma-no-newlines-before-nonblanks described above, CC Mode also comes with the criteria function c-semi&comma-no-newlines-for-oneline-inliners, which suppresses newlines after semicolons inside one-line inline method definitions (e.g. in C++ or Java).

This document was generated on September 26, 2026 using texi2html 1.82.