4. Minor Modes

CC Mode contains two minor-mode-like features that you should find useful while entering 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 CC Mode 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 CC Mode buffer. When auto-newline mode is enabled, you will see `C/a' on the mode line(6). When hungry delete mode is enabled you will see `C/h' and if both modes were enabled, you'd see `C/ah'.

CC Mode provides key bindings 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 (bound to 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)))

4.1 Auto-newline Insertion

Auto-newline minor mode works by enabling certain electric characters. Special characters such as the left and right braces, colons, semicolons, etc., have been made electric to perform some magic formatting in addition to inserting the typed character. As a general rule, electric characters are only electric when the following conditions apply:

• Auto-newline minor mode is enabled, as evidenced by a `C/a' or `C/ah' indicator on the modeline.

• The character was not typed inside of a literal (7).

• No numeric argument was supplied to the command (i.e. it was typed as normal, with no C-u prefix).

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 reindentation of the line the brace was typed on, and second, it will add various newlines before and/or after the typed brace. Reindentation 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 reindented.

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.

User Option: c-hanging-braces-alist

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 brace-list-intro, statement-cont, inexpr-class-open, inexpr-class-close, and all the *-open and *-close symbols. See section 10. 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(8).

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 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 9.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 ) { 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) (statement-cont) (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, brace-entry-open and statement-cont(9) 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.

4.1.2 Hanging Colons

Using a mechanism similar to brace hanging (see section 4.1.1 Hanging Braces), colons can also be made to hang using the style variable c-hanging-colons-alist.

User Option: c-hanging-colons-alist

The syntactic symbols appropriate for this association 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 9.5.2 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 CC Mode. See section 4.1.5 Clean-ups, for details.

4.1.3 Hanging Semicolons and Commas

Semicolons and commas are also electric in CC Mode, 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 9.5.3 Customizing Semicolons and Commas, for details.

4.1.4 Other Electric Commands

A few other keys also provide electric behavior, often only to reindent the line. Common to all of them is that they only reindent if used in normal code (as opposed to in a string literal or comment), and c-syntactic-indentation isn't nil. They are:

#

Pound (bound to c-electric-pound) is electric when typed as the first non-whitespace character on a line and not within a macro definition. 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 preprocessor macro definitions.

Pound is not electric in AWK buffers, where `#' starts a comment, and is bound to self-insert-command like any typical printable character.

*

/

Stars and slashes (bound to c-electric-star and c-electric-slash respectively) are also electric under certain circumstances. If a `*' 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 `/' 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.

In AWK mode, `*' and `/' do not delimit comments and are bound to self-insert-command.

<

>

Less-than and greater-than signs (bound to c-electric-lt-gt) are electric, but only in C++ mode. Hitting the second of two < or > keys reindents the line if it is a C++ style stream operator.

(

)

The normal parenthesis characters `(' and `)' reindent the current line. This is useful for getting the closing parenthesis of an argument list aligned automatically.

Command: c-electric-continued-statement

Certain keywords, depending on language, are electric to cause reindentation when they are preceded only by whitespace on the line. The keywords are those that continue an earlier statement instead of starting a new one: else, while, catch (only in C++ and Java) and finally (only in Java).

An example:

for (i = 0; i < 17; i++) if (a[i]) res += a[i]->offset; else

Here, the else should be indented like the preceding if, since it continues that statement. CC Mode will automatically reindent it after the else has been typed in full, since it's not until then it's possible to decide whether it's a new statement or a continuation of the preceding if.

CC Mode uses Abbrev mode (see section `Abbrevs' in The Emacs Editor) to accomplish this. It's therefore turned on by default in all language modes except IDL mode, since CORBA IDL doesn't have any statements.

4.1.5 Clean-ups

Clean-ups are mechanisms 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. Clean-ups are however used to adjust code "after-the-fact," i.e. to adjust the whitespace in constructs after they are typed.

Most of the clean-ups are only applicable to counteract automatically inserted newlines, and will therefore only have any effect if the auto-newline minor mode is turned on. Others will work all the time.

User Option: c-cleanup-list

You can configure CC Mode's clean-ups by setting the style variable c-cleanup-list, which is a list of clean-up symbols. By default, CC Mode 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 4.1 Auto-newline Insertion), and when there is nothing but whitespace appearing between the individual components of the construct.

These are the clean-ups that are only active in the auto-newline minor mode:

brace-else-brace

Clean up `} else {' constructs by placing the entire construct on a single line. Clean-up occurs when the open brace after the `else' is typed. So for example, this:

void spam(int i) { if( i==7 ) { dosomething(); } else {

appears like this after the last open brace is typed:

void spam(int i) { if( i==7 ) { dosomething(); } else {

brace-elseif-brace

Similar to the brace-else-brace clean-up, but this cleans up `} else if (...) {' constructs. For example:

void spam(int i) { if( i==7 ) { dosomething(); } else if( i==3 ) {

appears like this after the last open parenthesis is typed:

void spam(int i) { if( i==7 ) { dosomething(); } else if( i==3 ) {

and like this after the last open brace is typed:

void spam(int i) { if( i==7 ) { dosomething(); } else if( i==3 ) {

brace-catch-brace

Analogous to brace-elseif-brace, but cleans up `} catch (...) {' in C++ and Java mode.

empty-defun-braces

Clean up braces following a top-level function or class definition that contains no body. Clean up occurs when the closing brace is typed. Thus the following:

class Spam { }

is transformed into this when the close brace is typed:

class Spam {}

defun-close-semi

Clean up the terminating semicolon on top-level function or class definitions when they follow a close brace. Clean up occurs when the semicolon is typed. So for example, the following:

class Spam { } ;

is transformed into this when the semicolon is typed:

class Spam { };

list-close-comma

Clean up commas following braces in array and aggregate initializers. Clean up occurs when the comma is typed.

scope-operator

Clean up double colons which may designate a C++ scope operator split across multiple lines(10). Clean up occurs when the second colon is typed. You will always want scope-operator in the c-cleanup-list when you are editing C++ code.

The following clean-ups are always active when they occur on c-cleanup-list, and are thus not affected by the auto-newline minor mode:

space-before-funcall

Insert a space between the function name and the opening parenthesis of a function call. This produces function calls in the style mandated by the GNU coding standards, e.g. `signal (SIGINT, SIG_IGN)' and `abort ()'. Clean up occurs when the opening parenthesis is typed.

compact-empty-funcall

Clean up any space between the function name and the opening parenthesis of a function call that has no arguments. This is typically used together with space-before-funcall if you prefer the GNU function call style for functions with arguments but think it looks ugly when it's only an empty parenthesis pair. I.e. you will get `signal (SIGINT, SIG_IGN)', but `abort()'. Clean up occurs when the closing parenthesis is typed.

4.2 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 DEL or C-d keys will consume all preceding or following whitespace, including newlines and tabs. This can really cut down on the number of times you have to hit these keys if, for example, you made a mistake on the preceding line.

Command: c-electric-backspace

This command is run by default when you hit the DEL key. It deletes any amount of whitespace in the backwards direction if hungry-delete mode is enabled. When it's disabled, or when used with a prefix argument or in a literal (see section 4.1 Auto-newline Insertion), the function contained in the c-backspace-function variable is called with the prefix argument.

Variable: c-backspace-function

Hook that gets called by c-electric-backspace when it doesn't do an "electric" deletion of the preceding whitespace. The default value is backward-delete-char-untabify.

Command: c-electric-delete-forward

This function, which is bound to C-d by default, works just like c-electric-backspace but in the forward direction. When it doesn't do an "electric" deletion of the following whitespace, it calls the function in c-delete-function with its prefix argument.

Variable: c-delete-function

Hook that gets called by c-electric-delete-forward when it doesn't do an "electric" deletion of the following whitespace. The default value is delete-char.

Above we have only talked about the DEL and C-d key events, without connecting them to the physical keys commonly known as Backspace and Delete. The default behavior of those two depends on the flavor of (X)Emacs you are using.

In XEmacs 20.3 and beyond, the Backspace key is bound to c-electric-backspace and the Delete key is bound to c-electric-delete. You control the direction it deletes in by setting the variable delete-key-deletes-forward, a standard XEmacs variable. When this variable is non-nil, c-electric-delete will do forward deletion with c-electric-delete-forward, otherwise it does backward deletion with c-electric-backspace.

In other Emacs versions, CC Mode doesn't bind either Backspace or Delete. In XEmacs 19 and Emacs prior to 21 that means that it's up to you to fix them. Emacs 21 automatically binds them as appropriate to DEL and C-d.

Another way to use hungry deletion is to bind c-hungry-backspace and c-hungry-delete-forward directly to keys, and not use the mode toggling. For example C-c C-d and C-c DEL to match plain C-d and DEL,

(add-hook
 'c-mode-common-hook
 (lambda ()
   (define-key c-mode-base-map
               [?\C-c ?\d] 'c-hungry-backspace)
   (define-key c-mode-base-map
               [?\C-c ?\C-d] 'c-hungry-delete-forward)))

Command: c-hungry-backspace

Delete any amount of whitespace in the backwards direction (regardless whether hungry-delete mode is enabled or not).

Command: c-hungry-delete-forward

Delete any amount of whitespace in the forward direction (regardless whether hungry-delete mode is enabled or not).

This document was generated by XEmacs shared group account on December, 19 2009 using texi2html 1.65.