CC Mode

4.1 Indentation Commands

The following commands reindent C constructs. Note that when you change your coding style, either interactively or through some other means, your file does not automatically get reindented. You will need to execute one of the following commands to see the effects of your changes.

Also, variables like c-hanging-* and c-cleanup-list (see Customizing Auto-newlines) only affect how on-the-fly code is formatted. Changing the “hanginess” of a brace and then reindenting, will not move the brace to a different line. For this, you’re better off getting an external program like GNU indent, which will rearrange brace location, amongst other things.

Preprocessor directives are handled as syntactic whitespace from other code, i.e., they can be interspersed anywhere without affecting the indentation of the surrounding code, just like comments.

The code inside macro definitions is, by default, still analyzed syntactically so that you get relative indentation there just as you’d get if the same code was outside a macro. However, since there is no hint about the syntactic context, i.e., whether the macro expands to an expression, to some statements, or perhaps to whole functions, the syntactic recognition can be wrong. CC Mode manages to figure it out correctly most of the time, though.

Some macros, when invoked, “have their own semicolon”. To get the next line indented correctly, rather than as a continuation line, See Macros with semicolons.

Reindenting large sections of code can take a long time. When CC Mode reindents a region of code, it is essentially equivalent to hitting TAB on every line of the region.

These commands indent code:

TAB (c-indent-command) ¶

This command indents the current line. That is all you need to know about it for normal use.

c-indent-command does different things, depending on the setting of c-syntactic-indentation (see Indentation Engine Basics):

• When it’s non-nil (which it normally is), the command indents the line according to its syntactic context. With a prefix argument (C-u TAB), it will re-indent the entire expression³ that begins at the line’s left margin.
• When it’s nil, the command indents the line by an extra c-basic-offset columns. A prefix argument acts as a multiplier. A bare prefix (C-u TAB) is equivalent to -1, removing c-basic-offset columns from the indentation.

The precise behavior is modified by several variables: With c-tab-always-indent, you can make TAB insert whitespace in some circumstances—c-insert-tab-function then defines precisely what sort of “whitespace” this will be. Set the standard Emacs variable indent-tabs-mode to t if you want real ‘tab’ characters to be used in the indentation, to nil if you want only spaces. See Just Spaces in GNU Emacs Manual.

User Option: c-tab-always-indent ¶

This variable modifies how TAB operates.

• When it is t (the default), TAB simply indents the current line.
• When it is nil, TAB (re)indents the line only if point is to the left of the first non-whitespace character on the line. Otherwise it inserts some whitespace (a tab or an equivalent number of spaces; see below) at point.
• With some other value, the line is reindented. Additionally, if point is within a string or comment, some whitespace is inserted.

User Option: c-insert-tab-function ¶

When “some whitespace” is inserted as described above, what actually happens is that the function stored in c-insert-tab-function is called. Normally, this is insert-tab, which inserts a real tab character or the equivalent number of spaces (depending on indent-tabs-mode). Some people, however, set c-insert-tab-function to tab-to-tab-stop so as to get hard tab stops when indenting.

The kind of indentation the next five commands do depends on the setting of c-syntactic-indentation (see Indentation Engine Basics):

• when it is non-nil (the default), the commands indent lines according to their syntactic context;
• when it is nil, they just indent each line the same amount as the previous non-blank line. The commands that indent a region aren’t very useful in this case.

C-M-q (c-indent-exp) ¶

Indents an entire balanced brace or parenthesis expression. Note that point must be on the opening brace or parenthesis of the expression you want to indent.

C-c C-q (c-indent-defun) ¶

Indents the entire top-level function, class or macro definition encompassing point. It leaves point unchanged. This function can’t be used to reindent a nested brace construct, such as a nested class or function, or a Java method. The top-level construct being reindented must be complete, i.e., it must have both a beginning brace and an ending brace.

C-M-\ (indent-region) ¶

Indents an arbitrary region of code. This is a standard Emacs command, tailored for C code in a CC Mode buffer. Note, of course, that point and mark must delineate the region you want to indent.

C-M-h (c-mark-function) ¶

While not strictly an indentation command, this is useful for marking the current top-level function or class definition as the current region. As with c-indent-defun, this command operates on top-level constructs, and can’t be used to mark say, a Java method.

These variables are also useful when indenting code:

User Option: indent-tabs-mode ¶

This is a standard Emacs variable that controls how line indentation is composed. When it’s non-nil, tabs can be used in a line’s indentation, otherwise only spaces are used.

User Option: c-progress-interval ¶

When indenting large regions of code, this variable controls how often a progress message is displayed. Set this variable to nil to inhibit the progress messages, or set it to an integer which is how often (in seconds) progress messages are to be displayed.

4.2 Comment Commands

When the commands in this section add comment delimiters, they use either line comments or block comments depending on the setting of the comment style (see Minor Modes).

C-c C-c (comment-region) ¶

This command comments out the lines that start in the region. With a negative argument, it does the opposite: it deletes the comment delimiters from these lines. See Multi-Line Comments in GNU Emacs Manual, for fuller details. comment-region isn’t actually part of CC Mode; it is given a CC Mode binding for convenience.

M-; (comment-dwim or indent-for-comment ⁴) ¶

Insert a comment at the end of the current line, if none is there already. Then reindent the comment according to comment-column (see Options for Comments in GNU Emacs Manual) and the variables below. Finally, position the point after the comment starter. C-u M-; kills any comment on the current line, together with any whitespace before it. This is a standard Emacs command, but CC Mode enhances it a bit with two variables:

User Option: c-indent-comment-alist ¶

This style variable allows you to vary the column that M-; puts the comment at, depending on what sort of code is on the line, and possibly the indentation of any similar comment on the preceding line. It is an association list that maps different types of lines to actions describing how they should be handled. If a certain line type isn’t present on the list then the line is indented to the column specified by comment-column.

See the documentation string for a full description of this variable (use C-h v c-indent-comment-alist).

User Option: c-indent-comments-syntactically-p ¶

Normally, when this style variable is nil, M-; will indent comment-only lines according to c-indent-comment-alist, just as it does with lines where other code precede the comments. However, if you want it to act just like TAB for comment-only lines you can get that by setting c-indent-comments-syntactically-p to non-nil.

If c-indent-comments-syntactically-p is non-nil then c-indent-comment-alist won’t be consulted at all for comment-only lines.

4.3 Movement Commands

CC Mode contains some useful commands for moving around in C code.

C-M-a (c-beginning-of-defun) ¶

C-M-e (c-end-of-defun)

Move to the beginning or end of the current or next function. Other constructs (such as structs or classes) which have a brace block also count as “functions” here. To move over several functions, you can give these commands a repeat count.

The start of a function is at its header. The end of the function is after its closing brace, or after the semicolon of a construct (such as a struct) which doesn’t end at the brace. These two commands try to leave point at the beginning of a line near the actual start or end of the function. This occasionally causes point not to move at all.

By default, these commands will recognize functions contained within a declaration scope such as a C++ class or namespace construct, should the point start inside it. If CC Mode fails to find function beginnings or ends inside the current declaration scope, it will search the enclosing scopes. If you want CC Mode to recognize functions only at the top level⁵, set c-defun-tactic to t.

These functions are analogous to the Emacs built-in commands beginning-of-defun and end-of-defun, except they eliminate the constraint that the top-level opening brace of the defun must be in column zero. See Defuns in GNU Emacs Manual, for more information.

C-M-a (AWK Mode) (c-awk-beginning-of-defun) ¶

C-M-e (AWK Mode) (c-awk-end-of-defun)

Move to the beginning or end of the current or next AWK defun. These commands can take prefix-arguments, their functionality being entirely equivalent to beginning-of-defun and end-of-defun.

AWK Mode defuns are either pattern/action pairs (either of which might be implicit) or user defined functions. Having the ‘{’ and ‘}’ (if there are any) in column zero, as is suggested for some modes, is neither necessary nor helpful in AWK mode.

M-a (c-beginning-of-statement) ¶

M-e (c-end-of-statement)

Move to the beginning or end of the innermost C statement. If point is already there, move to the next beginning or end of a statement, even if that means moving into a block. (Use C-M-b or C-M-f to move over a balanced block.) A prefix argument n means move over n statements.

If point is within or next to a comment or a string which spans more than one line, these commands move by sentences instead of statements.

When called from a program, these functions take three optional arguments: the repetition count, a buffer position limit which is the farthest back to search for the syntactic context, and a flag saying whether to do sentence motion in or near comments and multiline strings.

C-c C-u (c-up-conditional) ¶

Move back to the containing preprocessor conditional, leaving the mark behind. A prefix argument acts as a repeat count. With a negative argument, move forward to the end of the containing preprocessor conditional.

‘#elif’ is treated like ‘#else’ followed by ‘#if’, so the function stops at them when going backward, but not when going forward.

This key sequence is not bound in AWK Mode, which doesn’t have preprocessor statements.

M-x c-up-conditional-with-else ¶

A variety of c-up-conditional that also stops at ‘#else’ lines. Normally those lines are ignored.

M-x c-down-conditional ¶

Move forward into the next nested preprocessor conditional, leaving the mark behind. A prefix argument acts as a repeat count. With a negative argument, move backward into the previous nested preprocessor conditional.

‘#elif’ is treated like ‘#else’ followed by ‘#if’, so the function stops at them when going forward, but not when going backward.

M-x c-down-conditional-with-else ¶

A variety of c-down-conditional that also stops at ‘#else’ lines. Normally those lines are ignored.

C-c C-p (c-backward-conditional) ¶

C-c C-n (c-forward-conditional)

Move backward or forward across a preprocessor conditional, leaving the mark behind. A prefix argument acts as a repeat count. With a negative argument, move in the opposite direction.

These key sequences are not bound in AWK Mode, which doesn’t have preprocessor statements.

M-x c-backward-into-nomenclature ¶

A popular programming style, especially for object-oriented languages such as C++ is to write symbols in a mixed case format, where the first letter of each word is capitalized, and not separated by underscores. E.g., ‘SymbolsWithMixedCaseAndNoUnderlines’.

These commands move backward or forward to the beginning of the next capitalized word. With prefix argument n, move n times. If n is negative, move in the opposite direction.

Note that these two commands have been superseded by subword-mode, which you should use instead. See Subword Movement and Editing. They might be removed from a future release of CC Mode.

4.4 Filling and Line Breaking Commands

Since there’s a lot of normal text in comments and string literals, CC Mode provides features to edit these like in text mode. The goal is to do it seamlessly, i.e., you can use auto fill mode, sentence and paragraph movement, paragraph filling, adaptive filling etc. wherever there’s a piece of normal text without having to think much about it. CC Mode keeps the indentation, fixes suitable comment line prefixes, and so on.

You can configure the exact way comments get filled and broken, and where Emacs does auto-filling (see Customizing Filling and Line Breaking). Typically, the style system (see Styles) will have set this up for you, so you probably won’t have to bother.

Line breaks are by default handled (almost) the same regardless of whether they are made by auto fill mode (see Auto Fill in GNU Emacs Manual), by paragraph filling (e.g., with M-q), or explicitly with M-j or similar methods. In string literals, the new line gets the same indentation as the previous nonempty line.⁶.

M-q (c-fill-paragraph) ¶

This command fills multiline string literals and both block and line style comments. In Java buffers, the Javadoc markup words are recognized as paragraph starters. The line oriented Pike autodoc markup words are recognized in the same way in Pike mode.

The formatting of the starters (/*) and enders (*/) of block comments are kept as they were before the filling. I.e., if either the starter or ender were on a line of its own, then it stays on its own line; conversely, if the delimiter has comment text on its line, it keeps at least one word of that text with it on the line.

This command is the replacement for fill-paragraph in CC Mode buffers.

M-j (c-indent-new-comment-line) ¶

This breaks the current line at point and indents the new line. If point was in a comment, the new line gets the proper comment line prefix. If point was inside a macro, a backslash is inserted before the line break. It is the replacement for indent-new-comment-line.

M-x c-context-line-break ¶

Insert a line break suitable to the context: If the point is inside a comment, the new line gets the suitable indentation and comment line prefix like c-indent-new-comment-line. In normal code it’s indented like newline-and-indent would do. In macros it acts like newline-and-indent but additionally inserts and optionally aligns the line ending backslash so that the macro remains unbroken. See Customizing Macros, for details about the backslash alignment. In a string, a backslash is inserted only if the string is within a macro⁷.

This function is not bound to a key by default, but it’s intended to be used on the RET key. If you like the behavior of newline-and-indent on RET, you should consider switching to this function. See Sample Init File.

M-x c-context-open-line ¶

This is to C-o (M-x open-line) as c-context-line-break is to RET. I.e., it works just like c-context-line-break but leaves the point before the inserted line break.

4.5 Minor Modes

CC Mode contains several minor-mode-like features that you might find useful while writing new code or editing old code:

comment style

This specifies whether comment commands (such as M-;) insert block comments or line comments⁸.

electric mode

When this is enabled, certain visible characters cause reformatting as they are typed. This is normally helpful, but can be a nuisance when editing chaotically formatted code. It can also be disconcerting, especially for users who are new to CC Mode.

auto-newline mode

This automatically inserts newlines where you’d probably want to type them yourself, e.g., after typing ‘}’s. Its action is suppressed when electric mode is disabled.

hungry-delete mode

This lets you delete a contiguous block of whitespace with a single key: for example, the newline and indentation just inserted by auto-newline when you want to back up and write a comment after the last statement.

subword mode

This mode makes basic word movement commands like M-f (forward-word) and M-b (backward-word) treat the parts of sillycapsed symbols as different words. E.g., ‘NSGraphicsContext’ is treated as three words ‘NS’, ‘Graphics’, and ‘Context’.

syntactic-indentation mode

When this is enabled (which it normally is), indentation commands such as C-j indent lines of code according to their syntactic structure. Otherwise, a line is simply indented to the same level as the previous one and TAB adjusts the indentation in steps of c-basic-offset.

Full details on how these minor modes work are at Electric Keys and Keywords, Auto-newline Insertion, Hungry Deletion of Whitespace, Subword Movement and Editing, and Indentation Engine Basics.

You can toggle each of these minor modes on and off, and you can configure CC Mode so that it starts up with your favorite combination of them (see Sample Init File). By default, when you initialize a buffer, the comment style is set to the default for the major mode, electric mode and syntactic-indentation mode are enabled, but the other three modes are disabled.

CC Mode displays the current state of the first five of these minor modes on the mode line by appending characters to the major mode’s name: ‘/’ or ‘*’ to indicate the comment style (respectively line or block), and one letter for each of the other minor modes which is enabled - ‘l’ for electric mode, ‘a’ for auto-newline mode, ‘h’ for hungry delete mode, and ‘w’ for subword mode. If the comment style was block and all the other modes were enabled, you’d see ‘C/*lahw’⁹.

Here are the commands to toggle these modes:

C-c C-k (c-toggle-comment-style) ¶

Toggle the comment style between line style and block style. In modes (such as AWK Mode) which only have one of these styles, this function does nothing.

C-c C-l (c-toggle-electric-state) ¶

Toggle electric minor mode. When the command turns the mode off, it also suppresses auto-newline mode.

C-c C-a (c-toggle-auto-newline) ¶

Toggle auto-newline minor mode. When the command turns the mode on, it also enables electric minor mode.

M-x c-toggle-hungry-state¹⁰ ¶

Toggle hungry-delete minor mode.

M-x c-toggle-auto-hungry-state¹¹ ¶

Toggle both auto-newline and hungry delete minor modes.

C-c C-w (M-x subword-mode) ¶

Toggle subword mode.

M-x c-toggle-syntactic-indentation ¶

Toggle syntactic-indentation mode.

Common to all the toggle functions above is that if they are called programmatically, they take an optional numerical argument. For c-toggle-comment style, a positive value will select block comments, a negative value will select line comments. For the other functions, a positive value will turn on the minor mode (or both of them in the case of c-toggle-auto-hungry-state) and a negative value will turn it (or them) off.

4.6 Electric Keys and Keywords

Most punctuation keys provide electric behavior: as well as inserting themselves they perform some other action, such as reindenting the line. This reindentation saves you from having to reindent a line manually after typing, say, a ‘}’. A few keywords, such as else, also trigger electric action.

You can inhibit the electric behavior described here by disabling electric minor mode (see Minor Modes).

Common to all these keys is that they only behave electrically when used in normal code (as contrasted with getting typed in a string literal or comment). Those which cause re-indentation do so only when c-syntactic-indentation has a non-nil value (which it does by default).

These keys and keywords 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.

* ¶

/

A star (bound to c-electric-star) or a slash (c-electric-slash) causes reindentation when you type it as the second component of a C style block comment opener (‘/*’) or a C++ line comment opener (‘//’) respectively, but only if the comment opener is the first thing on the line (i.e., there’s only whitespace before it).

Additionally, you can configure CC Mode so that typing a slash at the start of a line within a block comment will terminate the comment. You don’t need to have electric minor mode enabled to get this behavior. See Clean-ups.

In AWK mode, ‘*’ and ‘/’ do not delimit comments and are not electric.

< ¶

>

A less-than or greater-than sign (bound to c-electric-lt-gt) is electric in two circumstances: when it is an angle bracket in a C++ ‘template’ declaration (and similar constructs in other languages) and when it is the second of two < or > characters in a C++ style stream operator. In either case, the line is reindented. Angle brackets in C ‘#include’ directives are not electric.

( ¶

)

The normal parenthesis characters ‘(’ and ‘)’ (bound to c-electric-paren) reindent the current line. This is useful for getting the closing parenthesis of an argument list aligned automatically.

You can also configure CC Mode to insert a space automatically between a function name and the ‘(’ you’ve just typed, and to remove it automatically after typing ‘)’, should the argument list be empty. You don’t need to have electric minor mode enabled to get these actions. See Clean-ups.

{ ¶

}

Typing a brace (bound to c-electric-brace) reindents the current line. Also, one or more newlines might be inserted if auto-newline minor mode is enabled. See Auto-newline Insertion. Additionally, you can configure CC Mode to compact excess whitespace inserted by auto-newline mode in certain circumstances. See Clean-ups.

: ¶

Typing a colon (bound to c-electric-colon) reindents the current line. Additionally, one or more newlines might be inserted if auto-newline minor mode is enabled. See Auto-newline Insertion. If you type a second colon immediately after such an auto-newline, by default the whitespace between the two colons is removed, leaving a C++ scope operator. See Clean-ups.

If you prefer, you can insert ‘::’ in a single operation, avoiding all these spurious reindentations, newlines, and clean-ups. See Other Commands.

; ¶

,

Typing a semicolon or comma (bound to c-electric-semi&comma) reindents the current line. Also, a newline might be inserted if auto-newline minor mode is enabled. See Auto-newline Insertion. Additionally, you can configure CC Mode so that when auto-newline has inserted whitespace after a ‘}’, it will be removed again when you type a semicolon or comma just after it. See Clean-ups.

Command: c-electric-continued-statement ¶

Certain keywords are electric, causing 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 only then is it possible to decide whether it’s a new statement or a continuation of the preceding if.

CC Mode uses Abbrev mode (see Abbrevs in GNU Emacs Manual) 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.7 Auto-newline Insertion

When you have Auto-newline minor mode enabled (see Minor Modes), CC Mode inserts newlines for you automatically (in certain syntactic contexts) when you type a left or right brace, a colon, a semicolon, or a comma. Sometimes a newline appears before the character you type, sometimes after it, sometimes both.

Auto-newline only triggers when the following conditions hold:

• Auto-newline minor mode is enabled, as evidenced by the indicator ‘a’ after the mode name on the modeline (e.g., ‘C/a’ or ‘C/la’).
• The character was typed at the end of a line, or with only whitespace after it, and possibly a ‘\’ escaping the newline.
• The character is not on its own line already. (This applies only to insertion of a newline before the character.)
• The character was not typed inside of a literal ¹².
• No numeric argument was supplied to the command (i.e., it was typed as normal, with no C-u prefix).

You can configure the precise circumstances in which newlines get inserted (see Customizing Auto-newlines). Typically, the style system (see Styles) will have set this up for you, so you probably won’t have to bother.

Sometimes CC Mode inserts an auto-newline where you don’t want one, such as after a ‘}’ when you’re about to type a ‘;’. Hungry deletion can help here (see Hungry Deletion of Whitespace), or you can activate an appropriate clean-up, which will remove the excess whitespace after you’ve typed the ‘;’. See Clean-ups for a full description. See also Electric Keys and Keywords for a summary of clean-ups listed by key.

4.8 Hungry Deletion of Whitespace

If you want to delete an entire block of whitespace at point, you can use hungry deletion. This deletes all the contiguous whitespace either before point or after point in a single operation. “Whitespace” here includes tabs and newlines, but not comments or preprocessor commands. Hungry deletion can markedly cut down on the number of times you have to hit deletion keys when, for example, you’ve made a mistake on the preceding line and have already pressed C-j.

Hungry deletion is a simple feature that some people find extremely useful. In fact, you might find yourself wanting it in all your editing modes!

Loosely speaking, in what follows, DEL means “the backspace key” and DELETE means “the forward delete key”. This is discussed in more detail below.

There are two different ways you can use hungry deletion:

Using Hungry Delete Mode with DEL and C-d

Here you toggle Hungry Delete minor mode with M-x c-toggle-hungry-state¹³ (see Minor Modes.) This makes DEL and C-d do backwards and forward hungry deletion.

DEL (c-electric-backspace) ¶

This command is run by default when you hit the DEL key. When hungry delete mode is enabled, it deletes any amount of whitespace in the backwards direction. Otherwise, or when used with a prefix argument or in a literal (see Auto-newline Insertion), the command just deletes backwards in the usual way. (More precisely, it calls the function contained in the variable c-backspace-function, passing it the prefix argument, if any.)

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 (see Deletion in GNU Emacs Lisp Reference Manual, the function which deletes a single character.

C-d (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 just does delete-char, more or less. (Strictly speaking, it calls the function in c-delete-function with the prefix argument.)

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.

Using Distinct Bindings

The other (newer and recommended) way to use hungry deletion is to perform c-hungry-delete-backwards and c-hungry-delete-forward directly through their key sequences rather than using the minor mode toggling.

C-c C-DEL, or C-c DEL (c-hungry-delete-backwards)¹⁴ ¶

Delete any amount of whitespace in the backwards direction (regardless whether hungry-delete mode is enabled or not). This command is bound to both C-c C-DEL and C-c DEL, since the more natural one, C-c C-DEL, is sometimes difficult to type at a character terminal.

C-c C-d, C-c C-DELETE, or C-c DELETE (c-hungry-delete-forward) ¶

Delete any amount of whitespace in the forward direction (regardless whether hungry-delete mode is enabled or not). This command is bound to both C-c C-Delete and C-c Delete for the same reason as for DEL above.

When we talk about DEL, and Delete above, we actually do so without connecting them to the physical keys commonly known as Backspace and Delete. The default bindings to those two keys 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. Similarly, C-c Delete and C-c C-Delete are bound to c-hungry-delete which is controlled in the same way by delete-key-deletes-forward.

Emacs 21 and later automatically binds Backspace and Delete to DEL and C-d according to your environment, and CC Mode extends those bindings to C-c C-Backspace etc. If you need to change the bindings through normal-erase-is-backspace-mode then CC Mode will also adapt its extended bindings accordingly.

In earlier (X)Emacs versions, CC Mode doesn’t bind either Backspace or Delete directly. Only the key codes DEL and C-d are bound, and it’s up to the default bindings to map the physical keys to them. You might need to modify this yourself if the defaults are unsuitable.

Getting your Backspace and Delete keys properly set up can sometimes be tricky. The information in DEL Does Not Delete in GNU Emacs Manual, might be helpful if you’re having trouble with this in GNU Emacs.

4.9 Subword Movement and Editing

In spite of the GNU Coding Standards, it is popular to name a symbol by mixing uppercase and lowercase letters, e.g., ‘GtkWidget’, ‘EmacsFrameClass’, or ‘NSGraphicsContext’. Here we call these mixed case symbols nomenclatures. Also, each capitalized (or completely uppercase) part of a nomenclature is called a subword. Here are some examples:

The subword minor mode replaces the basic word oriented movement and editing commands with variants that recognize subwords in a nomenclature and treat them as separate words:

Note that if you have changed the key bindings for the word oriented commands in your .emacs or a similar place, the keys you have configured are also used for the corresponding subword oriented commands.

Type C-c C-w to toggle subword mode on and off. To make the mode turn on automatically, put the following code in your .emacs:

(add-hook 'c-mode-common-hook
          (lambda () (subword-mode 1)))

As a bonus, you can also use subword-mode in non-CC Mode buffers by typing M-x subword-mode.

4.10 Other Commands

Here are the various other commands that didn’t fit anywhere else:

C-c . (c-set-style) ¶

Switch to the specified style in the current buffer. Use like this:

C-c . style-name RET

You can use the TAB in the normal way to do completion on the style name. Note that all style names are case insensitive, even the ones you define yourself.

Setting a style in this way does not automatically reindent your file. For commands that you can use to view the effect of your changes, see Indentation Commands and Filling and Line Breaking Commands.

For details of the CC Mode style system, see Styles.

C-c : (c-scope-operator) ¶

In C++, it is also sometimes desirable to insert the double-colon scope operator without performing the electric behavior of colon insertion. C-c : does just this.

C-c C-z (c-display-defun-name) ¶

Display the current function name, if any, in the minibuffer. Additionally, if a prefix argument is given, push the function name to the kill ring. If there is no current function, c-display-defun-name does nothing. In Emacs, you can use this command in the middle of an interactive search if you set the customizable option isearch-allow-scroll to non-nil. See Not Exiting Isearch in GNU Emacs Manual.

C-c C-\ (c-backslash-region) ¶

This function inserts and aligns or deletes end-of-line backslashes in the current region. These are typically used in multi-line macros.

With no prefix argument, it inserts any missing backslashes and aligns them according to the c-backslash-column and c-backslash-max-column variables. With a prefix argument, it deletes any backslashes.

The function does not modify blank lines at the start of the region. If the region ends at the start of a line, it always deletes the backslash (if any) at the end of the previous line.

To customize the precise workings of this command, Customizing Macros.

The recommended line breaking function, c-context-line-break (see Filling and Line Breaking Commands), is especially nice if you edit multiline macros frequently. When used inside a macro, it automatically inserts and adjusts the mandatory backslash at the end of the line to keep the macro together, and it leaves the point at the right indentation column for the code. Thus you can write code inside macros almost exactly as you can elsewhere, without having to bother with the trailing backslashes.

C-c C-e (c-macro-expand) ¶

This command expands C, C++, Objective C or Pike macros in the region, using an appropriate external preprocessor program. Normally it displays its output in a temporary buffer, but if you give it a prefix arg (with C-u C-c C-e) it will overwrite the original region with the expansion.

The command does not work in any of the other modes, and the key sequence is not bound in these other modes.

c-macro-expand isn’t actually part of CC Mode, even though it is bound to a CC Mode key sequence. If you need help setting it up or have other problems with it, you can either read its source code or ask for help in the standard (X)Emacs forums.

5.1 Font Locking Preliminaries

The font locking for most of the CC Mode languages were provided directly by the Font Lock package prior to version 5.30 of CC Mode. In the transition to CC Mode the patterns have been reworked completely and are applied uniformly across all the languages except AWK mode, just like the indentation rules (although each language still has some peculiarities of its own, of course). Since the languages previously had completely separate font locking patterns, this means that it’s a bit different in most languages now.

The main goal for the font locking in CC Mode is accuracy, to provide a dependable aid in recognizing the various constructs. Some, like strings and comments, are easy to recognize while others, like declarations and types, can be very tricky. CC Mode can go to great lengths to recognize declarations and casts correctly, especially when the types aren’t recognized by standard patterns. This is a fairly demanding analysis which can be slow on older hardware, and it can therefore be disabled by choosing a lower decoration level with the variable font-lock-maximum-decoration (see Font Lock in GNU Emacs Manual).

The decoration levels are used as follows:

1. Minimal font locking: Fontify only comments, strings and preprocessor directives (in the languages that use cpp).
2. Fast font locking: In addition to level 1, fontify keywords, simple types and declarations that are easy to recognize. The variables *-font-lock-extra-types (where ‘*’ is the name of the language) are used to recognize types (see below). Documentation comments like Javadoc are fontified according to c-doc-comment-style (see Documentation Comments).

   Use this if you think the font locking is too slow. It’s the closest corresponding level to level 3 in the old font lock patterns.

3. Accurate font locking: Like level 2 but uses a different approach that can recognize types and declarations much more accurately. The *-font-lock-extra-types variables are still used, but user defined types are recognized correctly anyway in most cases. Therefore those variables should be fairly restrictive and not contain patterns that are uncertain.

   This level is designed for fairly modern hardware and a font lock support mode like Lazy Lock or Just-in-time Lock mode that only fontifies the parts that are actually shown. Fontifying the whole buffer at once can easily get bothersomely slow even on contemporary hardware. See Font Lock in GNU Emacs Manual.

Since user defined types are hard to recognize you can provide additional regexps to match those you use:

User Option: c-font-lock-extra-types ¶

User Option: c++-font-lock-extra-types ¶

User Option: objc-font-lock-extra-types ¶

User Option: java-font-lock-extra-types ¶

User Option: idl-font-lock-extra-types ¶

User Option: pike-font-lock-extra-types ¶

For each language there’s a variable *-font-lock-extra-types, where ‘*’ stands for the language in question. It contains a list of regexps that matches identifiers that should be recognized as types, e.g., ‘\\sw+_t’ to recognize all identifiers ending with ‘_t’ as is customary in C code. Each regexp should not match more than a single identifier.

The default values contain regexps for many types in standard runtime libraries that are otherwise difficult to recognize, and patterns for standard type naming conventions like the ‘_t’ suffix in C and C++. Java, Objective-C and Pike have as a convention to start class names with capitals, so there are patterns for that in those languages.

Despite the names of these variables, they are not only used for fontification but in other places as well where CC Mode needs to recognize types.

5.2 Faces

CC Mode attempts to use the standard faces for programming languages in accordance with their intended purposes as far as possible. No extra faces are currently provided, with the exception of a replacement face c-invalid-face for emacsen that don’t provide font-lock-warning-face.

• Normal comments are fontified in font-lock-comment-face.
• Comments that are recognized as documentation (see Documentation Comments) get font-lock-doc-face (Emacs) or font-lock-doc-string-face (XEmacs) if those faces exist. If they don’t then font-lock-comment-face is used.
• String and character literals are fontified in font-lock-string-face.
• Keywords are fontified with font-lock-keyword-face.
• font-lock-function-name-face is used for function names in declarations and definitions, and classes in those contexts. It’s also used for preprocessor defines with arguments.
• Variables in declarations and definitions, and other identifiers in such variable contexts, get font-lock-variable-name-face. It’s also used for preprocessor defines without arguments.
• Builtin constants are fontified in font-lock-constant-face if it exists, font-lock-reference-face otherwise. As opposed to the preceding two faces, this is used on the names in expressions, and it’s not used in declarations, even if there happen to be a ‘const’ in them somewhere.
• font-lock-type-face is put on types (both predefined and user defined) and classes in type contexts.
• Label identifiers get font-lock-constant-face if it exists, font-lock-reference-face otherwise.
• Name qualifiers and identifiers for scope constructs are fontified like labels.
• Special markup inside documentation comments are also fontified like labels.
• Preprocessor directives get font-lock-preprocessor-face if it exists (i.e., XEmacs). In Emacs they get font-lock-builtin-face or font-lock-reference-face, for lack of a closer equivalent.
• Some kinds of syntactic errors are fontified with font-lock-warning-face in Emacs. In older XEmacs versions there’s no corresponding standard face, so there a special c-invalid-face is used, which is defined to stand out sharply by default.

  Note that it’s not used for ‘#error’ or ‘#warning’ directives, since those aren’t syntactic errors in themselves.

5.3 Documentation Comments

There are various tools to supply documentation in the source as specially structured comments, e.g., the standard Javadoc tool in Java. CC Mode provides an extensible mechanism to fontify such comments and the special markup inside them.

User Option: c-doc-comment-style ¶

This is a style variable that specifies which documentation comment style to recognize, e.g., javadoc for Javadoc comments.

The value may also be a list of styles, in which case all of them are recognized simultaneously (presumably with markup cues that don’t conflict).

The value may also be an association list to specify different comment styles for different languages. The symbol for the major mode is then looked up in the alist, and the value of that element is interpreted as above if found. If it isn’t found then the symbol other is looked up and its value is used instead.

The default value for c-doc-comment-style is ((java-mode . javadoc) (pike-mode . autodoc) (c-mode . gtkdoc)).

Note that CC Mode uses this variable to set other variables that handle fontification etc. That’s done at mode initialization or when you switch to a style which sets this variable. Thus, if you change it in some other way, e.g., interactively in a CC Mode buffer, you will need to do M-x java-mode (or whatever mode you’re currently using) to reinitialize.

Note also that when CC Mode starts up, the other variables are modified before the mode hooks are run. If you change this variable in a mode hook, you’ll have to call c-setup-doc-comment-style afterwards to redo that work.

CC Mode currently provides handing of the following doc comment styles:

javadoc ¶

Javadoc comments, the standard tool in Java.

autodoc ¶

For Pike autodoc markup, the standard in Pike.

gtkdoc ¶

For GtkDoc markup, widely used in the Gnome community.

doxygen ¶

For Doxygen markup, which can be used with C, C++, Java and variety of other languages.

The above is by no means complete. If you’d like to see support for other doc comment styles, please let us know (see Mailing Lists and Submitting Bug Reports).

You can also write your own doc comment fontification support to use with c-doc-comment-style: Supply a variable or function *-font-lock-keywords where ‘*’ is the name you want to use in c-doc-comment-style. If it’s a variable, it’s prepended to font-lock-keywords. If it’s a function, it’s called at mode initialization and the result is prepended. For an example, see javadoc-font-lock-keywords in cc-fonts.el. It is even possible, to a limited extent, to fontify constructs inside a doc comment with other faces. For an example, see pike autodoc comment style towards the end of cc-fonts-el.

If you add support for another doc comment style, please consider contributing it: send a note to [email protected].

5.4 Marking “Wrong” style comments

Most languages supported by CC Mode have two styles of comments, namely block comments and line comments. Your project may have such a strong preference for one of them, that you wish “wrong” style comments to be clearly marked.

You can get CC Mode to do this by setting the default comment style, if necessary, (see Minor Modes) and setting the customizable option c-mark-wrong-style-of-comment to non-nil.

Variable: c-mark-wrong-style-of-comment ¶

When this customizable option is non-nil, comment delimiters which aren’t of the default style will be fontified with font-lock-warning-face.

5.5 Miscellaneous Font Locking

In some languages, particularly in C++, there are constructs which are syntactically ambiguous—they could be either declarations or expressions, and CC Mode cannot tell for sure which. Often such a construct is one of the operators ‘*’ or ‘&’ surrounded by two identifiers.

Experience shows that very often when such a construct is a declaration it will be written with the operator touching exactly one of the identifiers, like:

foo *bar

or

foo& bar

. Whether such code is fontified depends on the setting of c-asymmetry-fontification-flag.

Variable: c-asymmetry-fontification-flag ¶

When c-asymmetry-fontification-flag is non-nil (which it is by default), code like the above, with white space either before or after the operator, but not both, is fontified as a declaration. When the variable is nil, such a construct gets the default face.

When the construct is an expression there will often be white space both before and after the operator or there will be no white space around it at all, like:

foo * bar

or

foo&bar

.

Such code is not fontified as a declaration. (Typically, the identifiers don’t get a non-default face.)

For clarity’s sake, we emphasize that the “asymmetry” rule in this section only applies when CC Mode cannot disambiguate a construct in any other way.

5.6 AWK Mode Font Locking

The general appearance of font-locking in AWK mode is much like in any other programming mode. See Faces for Font Lock in GNU Emacs Lisp Reference Manual.

The following faces are, however, used in a non-standard fashion in AWK mode:

font-lock-variable-name-face

This face was intended for variable declarations. Since variables are not declared in AWK, this face is used instead for AWK system variables (such as NF) and “Special File Names” (such as "/dev/stderr").

font-lock-builtin-face (Emacs)/font-lock-preprocessor-face (XEmacs)

This face is normally used for preprocessor directives in CC Mode. There are no such things in AWK, so this face is used instead for standard functions (such as match).

font-lock-string-face

As well as being used for strings, including localizable strings, (delimited by ‘"’ and ‘_"’), this face is also used for AWK regular expressions (delimited by ‘/’).

font-lock-warning-face (Emacs)/c-invalid-face (XEmacs)

This face highlights the following syntactically invalid AWK constructs:

• An unterminated string or regular expression. Here the opening delimiter (‘"’ or ‘/’ or ‘_"’) is displayed in font-lock-warning-face. This is most noticeable when typing in a new string/regular expression into a buffer, when the warning-face serves as a continual reminder to terminate the construct.

  AWK mode fontifies unterminated strings/regular expressions differently from other modes: Only the text up to the end of the line is fontified as a string (escaped newlines being handled correctly), rather than the text up to the next string quote.

• A space between the function name and opening parenthesis when calling a user function. The last character of the function name and the opening parenthesis are highlighted. This font-locking rule will spuriously highlight a valid concatenation expression where an identifier precedes a parenthesized expression. Unfortunately.
• Whitespace following the ‘\’ in what otherwise looks like an escaped newline. The ‘\’ is highlighted.

6.1 Hooks

CC Mode provides several hooks that you can use to customize the mode for your coding style. The main hook is c-mode-common-hook; typically, you’ll put the bulk of your customizations here. In addition, each language mode has its own hook, allowing you to fine tune your settings individually for the different CC Mode languages, and there is a package initialization hook. Finally, there is c-special-indent-hook, which enables you to solve anomalous indentation problems. It is described in Other Special Indentations, not here. All these hooks adhere to the standard Emacs conventions.

When you open a buffer, CC Mode first initializes it with the currently active style (see Styles). Then it calls c-mode-common-hook, and finally it calls the language-specific hook. Thus, any style settings done in these hooks will override those set by c-default-style.

Variable: c-initialization-hook ¶

Hook run only once per Emacs session, when CC Mode is initialized. This is a good place to change key bindings (or add new ones) in any of the CC Mode key maps. See Sample Init File.

Variable: c-mode-common-hook ¶

Common hook across all languages. It’s run immediately before the language specific hook.

Variable: c-mode-hook ¶

Variable: c++-mode-hook ¶

Variable: objc-mode-hook ¶

Variable: java-mode-hook ¶

Variable: idl-mode-hook ¶

Variable: pike-mode-hook ¶

Variable: awk-mode-hook ¶

The language specific mode hooks. The appropriate one is run as the last thing when you enter that language mode.

Although these hooks are variables defined in CC Mode, you can give them values before CC Mode’s code is loaded—indeed, this is the only way to use c-initialization-hook. Their values aren’t overwritten when CC Mode gets loaded.

Here’s a simplified example of what you can add to your .emacs file to do things whenever any CC Mode language is edited. See the Emacs manuals for more information on customizing Emacs via hooks. See Sample Init File, for a more complete sample .emacs file.

(defun my-c-mode-common-hook ()
  ;; my customizations for all of c-mode and related modes
  (no-case-fold-search)
  )
(add-hook 'c-mode-common-hook 'my-c-mode-common-hook)

6.2 Style Variables

The variables that CC Mode’s style system control are called style variables. Note that style variables are ordinary Lisp variables, which the style system initializes; you can change their values at any time (e.g., in a hook function). The style system can also set other variables, to some extent. See Styles.

Style variables are handled specially in several ways:

• Style variables are by default buffer-local variables. However, they can instead be made global by setting c-style-variables-are-local-p to nil before CC Mode is initialized.
• The default global binding of any style variable (with two exceptions - see below) is the special symbol set-from-style. When the style system initializes a buffer-local copy of a style variable for a CC Mode buffer, if its global binding is still that symbol then it will be set from the current style. Otherwise it will retain its global default¹⁷. This “otherwise” happens, for example, when you’ve set the variable with setq at the top level of your .emacs (see Configuration Basics).
• The style variable c-offsets-alist (see c-offsets-alist) is an association list with an element for each syntactic symbol. It’s handled a little differently from the other style variables. Its default global binding is the empty list nil, rather than set-from-style. Before the style system is initialized, you can add individual elements to c-offsets-alist by calling c-set-offset (see c-offsets-alist) just like you would set other style variables with setq. Those elements will then prevail when the style system later initializes a buffer-local copy of c-offsets-alist.
• The style variable c-special-indent-hook is also handled in a special way. Styles can only add functions to this hook, not remove them, so any global settings you put on it are always preserved¹⁸. The value you give this variable in a style definition can be either a function or a list of functions.
• The global bindings of the style variables get captured in the special user style when the style system is first initialized. See Built-in Styles, for details.

The style variables are:
c-indent-comment-alist, c-indent-comments-syntactically-p (see Indentation Commands);
c-doc-comment-style (see Documentation Comments);
c-block-comment-prefix, c-comment-prefix-regexp (see Customizing Filling and Line Breaking);
c-hanging-braces-alist (see Hanging Braces);
c-hanging-colons-alist (see Hanging Colons);
c-hanging-semi&comma-criteria (see Hanging Semicolons and Commas);
c-cleanup-list (see Clean-ups);
c-basic-offset (see Customizing Indentation);
c-offsets-alist (see c-offsets-alist);
c-comment-only-line-offset (see Comment Line-Up Functions);
c-special-indent-hook, c-label-minimum-indentation (see Other Special Indentations);
c-backslash-column, c-backslash-max-column (see Customizing Macros).

6.3 Styles

By style we mean the layout of the code—things like how many columns to indent a block of code, whether an opening brace gets indented to the level of the code it encloses, or of the construct that introduces it, or “hangs” at the end of a line.

Most people only need to edit code formatted in just a few well-defined and consistent styles. For example, their organization might impose a “blessed” style that all its programmers must conform to. Similarly, people who work on GNU software will have to use the GNU coding style. Some shops are more lenient, allowing a variety of coding styles, and as programmers come and go, there could be a number of styles in use. For this reason, CC Mode makes it convenient for you to set up logical groupings of customizations called styles, associate a single name for any particular style, and pretty easily start editing new or existing code using these styles.

As an alternative to writing a style definition yourself, you can have CC Mode guess (at least part of) your style by looking at an already formatted piece of your code, Guessing the Style.

• Built-in Styles
• Choosing a Style
• Adding and Amending Styles
• Guessing the Style
• File Styles

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²⁸, 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 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 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²⁹.

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 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³⁰ 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.

• Custom Brace Hanging

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

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

8.2 Hanging Colons

Using a mechanism similar to brace hanging (see 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 Syntactic Symbols. Elements with any other value as a key get ignored.

The associated 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 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³¹ see 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).

10.1 Syntactic Analysis

The first thing CC Mode does when indenting a line of code, is to analyze the line by calling c-guess-basic-syntax, determining the syntactic context of the (first) construct on that line. Although this function is mainly used internally, it can sometimes be useful in Line-up functions (see Custom Line-Up Functions) or in functions on c-special-indent-hook (see Other Special Indentations).

Function: c-guess-basic-syntax ¶

Determine the syntactic context of the current line.

The syntactic context is a list of syntactic elements, where each syntactic element in turn is a list³³ Here is a brief and typical example:

((defun-block-intro 1959))

The first thing inside each syntactic element is always a syntactic symbol. It describes the kind of construct that was recognized, e.g., statement, substatement, class-open, class-close, etc. See Syntactic Symbols, for a complete list of currently recognized syntactic symbols and their semantics. The remaining entries are various data associated with the recognized construct; there might be zero or more.

Conceptually, a line of code is always indented relative to some position higher up in the buffer (typically the indentation of the previous line). That position is the anchor position in the syntactic element. If there is an entry after the syntactic symbol in the syntactic element list then it’s either nil or that anchor position.

Here is an example. Suppose we had the following code as the only thing in a C++ buffer ³⁴:

 1: void swap( int& a, int& b )
 2: {
 3:     int tmp = a;
 4:     a = b;
 5:     b = tmp;
 6: }

We can use C-c C-s (c-show-syntactic-information) to report what the syntactic analysis is for the current line:

C-c C-s (c-show-syntactic-information) ¶

This command calculates the syntactic analysis of the current line and displays it in the minibuffer. The command also highlights the anchor position(s).

Running this command on line 4 of this example, we’d see in the echo area³⁵:

((statement 35))

and the ‘i’ of int on line 3 would be highlighted. This tells us that the line is a statement and it is indented relative to buffer position 35, the highlighted position. If you were to move point to line 3 and hit C-c C-s, you would see:

((defun-block-intro 29))

This indicates that the ‘int’ line is the first statement in a top level function block, and is indented relative to buffer position 29, which is the brace just after the function header.

Here’s another example:

 1: int add( int val, int incr, int doit )
 2: {
 3:     if( doit )
 4:         {
 5:             return( val + incr );
 6:         }
 7:     return( val );
 8: }

Hitting C-c C-s on line 4 gives us:

((substatement-open 46))

which tells us that this is a brace that opens a substatement block.³⁶

Syntactic contexts can contain more than one element, and syntactic elements need not have anchor positions. The most common example of this is a comment-only line:

 1: void draw_list( List<Drawables>& drawables )
 2: {
 3:         // call the virtual draw() method on each element in list
 4:     for( int i=0; i < drawables.count(), ++i )
 5:     {
 6:         drawables[i].draw();
 7:     }
 8: }

Hitting C-c C-s on line 3 of this example gives:

((comment-intro) (defun-block-intro 46))

and you can see that the syntactic context contains two syntactic elements. Notice that the first element, ‘(comment-intro)’, has no anchor position.

10.2 Syntactic Symbols

This section is a complete list of the syntactic symbols which appear in the c-offsets-alist style variable, along with brief descriptions. The previous section (see Syntactic Analysis) states what syntactic symbols are and how the indentation engine uses them.

More detailed descriptions of these symbols, together with snippets of source code to which they apply, appear in the examples in the subsections below. Note that, in the interests of brevity, the anchor position associated with most syntactic symbols is not specified. In cases of doubt, type C-c C-s on a pertinent line—this highlights the anchor position.

The syntactic symbols which indicate brace constructs follow a general naming convention. When a line begins with an open or close brace, its syntactic symbol will contain the suffix -open or -close respectively. The first line within the brace block construct will contain the suffix -block-intro.

In constructs which can span several lines, a distinction is usually made between the first line that introduces the construct and the lines that continue it. The syntactic symbols that indicate these lines will contain the suffixes -intro or -cont respectively.

The best way to understand how all this works is by looking at some examples. Remember that you can see the syntax of any source code line by using C-c C-s.

string

Inside a multiline string. Comment String Label and Macro Symbols.

c

Inside a multiline C style block comment. Comment String Label and Macro Symbols.

defun-open

Brace that opens a top-level function definition. Function Symbols.

defun-close

Brace that closes a top-level function definition. Function Symbols.

defun-block-intro

The first line in a top-level defun. Function Symbols.

class-open

Brace that opens a class definition. Class related Symbols.

class-close

Brace that closes a class definition. Class related Symbols.

inline-open

Brace that opens an in-class inline method. Class related Symbols.

inline-close

Brace that closes an in-class inline method. Class related Symbols.

func-decl-cont

The region between a function definition’s argument list and the function opening brace (excluding K&R argument declarations). In C, you cannot put anything but whitespace and comments in this region, however in C++ and Java, throws declarations and other things can appear here. Comment String Label and Macro Symbols.

knr-argdecl-intro

First line of a K&R C argument declaration. K&R Symbols.

knr-argdecl

Subsequent lines in a K&R C argument declaration. K&R Symbols.

topmost-intro

The first line in a “topmost” definition. Function Symbols.

topmost-intro-cont

Topmost definition continuation lines. This is only used in the parts that aren’t covered by other symbols such as func-decl-cont and knr-argdecl. Function Symbols.

annotation-top-cont

Topmost definition continuation lines where all previous items are annotations. Java Symbols.

member-init-intro

First line in a member initialization list. Class related Symbols.

member-init-cont

Subsequent member initialization list lines. Class related Symbols.

inher-intro

First line of a multiple inheritance list. Class related Symbols.

inher-cont

Subsequent multiple inheritance lines. Class related Symbols.

block-open

Statement block open brace. Comment String Label and Macro Symbols.

block-close

Statement block close brace. Conditional Construct Symbols.

brace-list-open

Open brace of an enum or static array list. Brace List Symbols.

brace-list-close

Close brace of an enum or static array list. Brace List Symbols.

brace-list-intro

First line after the opening ‘{’ in an enum or static array list. Brace List Symbols.

brace-list-entry

Subsequent lines in an enum or static array list. Brace List Symbols.

brace-entry-open

Subsequent lines in an enum or static array list where the line begins with an open brace. Brace List Symbols.

statement

A statement. Function Symbols.

statement-cont

A continuation of a statement. Function Symbols.

annotation-var-cont

A continuation of a statement where all previous items are annotations. Java Symbols.

statement-block-intro

The first line in a new statement block. Conditional Construct Symbols.

statement-case-intro

The first line in a case block. Switch Statement Symbols.

statement-case-open

The first line in a case block that starts with a brace. Switch Statement Symbols.

substatement

The first line after a conditional or loop construct. Conditional Construct Symbols.

substatement-open

The brace that opens a substatement block. Conditional Construct Symbols.

substatement-label

The first line after a conditional or loop construct if it’s a label. Conditional Construct Symbols.

case-label

A label in a switch block. Switch Statement Symbols.

access-label

C++ access control label. Class related Symbols.

label

Any other label. Comment String Label and Macro Symbols.

do-while-closure

The while line that ends a do-while construct. Conditional Construct Symbols.

else-clause

The else line of an if-else construct. Conditional Construct Symbols.

catch-clause

The catch or finally (in Java) line of a try-catch construct. Conditional Construct Symbols.

comment-intro

A line containing only a comment introduction. Comment String Label and Macro Symbols.

arglist-intro

The first line in an argument list. Parenthesis (Argument) List Symbols.

arglist-cont

Subsequent argument list lines when no arguments follow on the same line as the arglist opening paren. Parenthesis (Argument) List Symbols.

arglist-cont-nonempty

Subsequent argument list lines when at least one argument follows on the same line as the arglist opening paren. Parenthesis (Argument) List Symbols.

arglist-close

The solo close paren of an argument list. Parenthesis (Argument) List Symbols.

stream-op

Lines continuing a stream operator (C++ only). Comment String Label and Macro Symbols.

inclass

The line is nested inside a class definition. Class related Symbols.

cpp-macro

The start of a preprocessor macro definition. Comment String Label and Macro Symbols.

cpp-define-intro

The first line inside a multiline preprocessor macro if c-syntactic-indentation-in-macros is set. Multiline Macro Symbols.

cpp-macro-cont

All lines inside multiline preprocessor macros if c-syntactic-indentation-in-macros is nil. Multiline Macro Symbols.

friend

A C++ friend declaration. Class related Symbols.

objc-method-intro

The first line of an Objective-C method definition. Objective-C Method Symbols.

objc-method-args-cont

Lines continuing an Objective-C method definition. Objective-C Method Symbols.

objc-method-call-cont

Lines continuing an Objective-C method call. Objective-C Method Symbols.

extern-lang-open

Brace that opens an extern block (e.g., extern "C" {...}). External Scope Symbols.

extern-lang-close

Brace that closes an extern block. External Scope Symbols.

inextern-lang

Analogous to inclass syntactic symbol, but used inside extern blocks. External Scope Symbols.

namespace-open

namespace-close

innamespace

These are analogous to the three extern-lang symbols above, but are returned for C++ namespace blocks. External Scope Symbols.

module-open

module-close

inmodule

Analogous to the above, but for CORBA IDL module blocks. External Scope Symbols.

composition-open

composition-close

incomposition

Analogous to the above, but for CORBA CIDL composition blocks. External Scope Symbols.

template-args-cont

C++ template argument list continuations. Class related Symbols.

inlambda

Analogous to inclass syntactic symbol, but used inside lambda (i.e., anonymous) functions. Used in C++ and Pike modes. Statement Block Symbols.

lambda-intro-cont

Lines continuing the header of a lambda function, i.e., between the lambda keyword and the function body. Only used in Pike mode. Statement Block Symbols.

inexpr-statement

A statement block inside an expression. The gcc C and C++ extension for this is recognized. It’s also used for the special functions that take a statement block as an argument in Pike. Statement Block Symbols.

inexpr-class

A class definition inside an expression. This is used for anonymous classes in Java. It’s also used for anonymous array initializers in Java. Java Symbols.

• Function Symbols
• Class related Symbols
• Conditional Construct Symbols
• Switch Statement Symbols
• Brace List Symbols
• External Scope Symbols
• Parenthesis (Argument) List Symbols
• Comment String Label and Macro Symbols
• Multiline Macro Symbols
• Objective-C Method Symbols
• Java Symbols
• Statement Block Symbols
• K&R Symbols

 1: void
 2: swap( int& a, int& b )
 3: {
 4:     int tmp = a;
 5:     a = b;
 6:     b = tmp;
 7:     int ignored =
 8:         a + b;
 9: }

 1: class Bass
 2:     : public Guitar,
 3:       public Amplifiable
 4: {
 5: public:
 6:     Bass()
 7:         : eString( new BassString( 0.105 )),
 8:           aString( new BassString( 0.085 )),
 9:           dString( new BassString( 0.065 )),
10:           gString( new BassString( 0.045 ))
11:     {
12:         eString.tune( 'E' );
13:         aString.tune( 'A' );
14:         dString.tune( 'D' );
15:         gString.tune( 'G' );
16:     }
17:     friend class Luthier;
18: };

((inclass 58) (access-label 58))

((inclass 58) (topmost-intro 60))

((inclass 58) (inline-open))

 1: class Bass
 2:     : public Guitar,
 3:       public Amplifiable
 4: {
 5: public:
 6:     Bass();
 7: };
 8:
 9: inline
10: Bass::Bass()
11:     : eString( new BassString( 0.105 )),
12:       aString( new BassString( 0.085 )),
13:       dString( new BassString( 0.065 )),
14:       gString( new BassString( 0.045 ))
15: {
16:     eString.tune( 'E' );
17:     aString.tune( 'A' );
18:     dString.tune( 'D' );
19:     gString.tune( 'G' );
20: }

((inclass 58) (topmost-intro 380) (friend))

 1: ThingManager <int,
 2:    Framework::Callback *,
 3:    Mutex> framework_callbacks;

 1: void spam( int index )
 2: {
 3:     for( int i=0; i<index; i++ )
 4:     {
 5:         if( i == 10 )
 6:             do_something_special();
 7:         else
 8:           silly_label:
 9:             do_something( i );
10:     }
11:     do {
12:         another_thing( i-- );
13:     }
14:     while( i > 0 );
15: }

 1: void spam( enum Ingredient i )
 2: {
 3:     switch( i ) {
 4:     case Ham:
 5:         be_a_pig();
 6:         break;
 7:     case Salt:
 8:         drink_some_water();
 9:         break;
10:     default:
11:         {
12:             what_is_it();
13:             break;
14:         }
15:     }
14: }

 1: static char* ingredients[] =
 2: {
 3:     "Ham",
 4:     "Salt",
 5:     NULL
 6: };

 1: struct intpairs[] =
 2: {
 3:     { 1, 2 },
 4:     {
 5:         3,
 6:         4
 7:     }
 8:     { 1,
 9:       2 },
10:     { 3, 4 }
11: };

 1: extern "C"
 2: {
 3:     int thing_one( int );
 4:     int thing_two( double );
 5: }

((inextern-lang) (topmost-intro 14))

 1: void a_function( int line1,
 2:                  int line2 );
 3:
 4: void a_longer_function(
 5:     int line1,
 6:     int line2
 7:     );
 8:
 9: void call_them( int line1, int line2 )
10: {
11:     a_function(
12:         line1,
13:         line2
14:         );
15:
16:     a_longer_function( line1,
17:                        line2 );
18: }

 1: void Bass::play( int volume )
 2: const
 3: {
 4:     /* this line starts a multiline
 5:      * comment.  This line should get 'c' syntax */
 6:
 7:     char* a_multiline_string = "This line starts a multiline \
 8: string.  This line should get 'string' syntax.";
 9:
10:   note:
11:     {
12: #ifdef LOCK
13:         Lock acquire();
14: #endif // LOCK
15:         slap_pop();
16:         cout << "I played "
17:              << "a note\n";
18:     }
19: }

 1: #define LIST_LOOP(cons, listp)                         \
 2:   for (cons = listp; !NILP (cons); cons = XCDR (cons)) \
 3:     if (!CONSP (cons))                                 \
 4:       signal_error ("Invalid list format", listp);     \
 5:     else

 1: - (void)setDelegate:anObject
 2:           withStuff:stuff
 3: {
 4:     [delegate masterWillRebind:self
 5:               toDelegate:anObject
 6:               withExtraStuff:stuff];
 7: }

 1:  @Test
 2:  public void watch(Observable o) {
 3:      @NonNull
 4:      Observer obs = new Observer() {
 5:          public void update(Observable o, Object arg) {
 6:              history.addElement(arg);
 7:          }
 8:      };
 9:      o.addObserver(obs);
 10: }

 1: int res = ({
 2:         int y = foo (); int z;
 3:         if (y > 0) z = y; else z = - y;
 4:         z;
 5:     });

 1:  std::for_each(someList.begin(), someList.end(), [&total](int x) {
 2:                                                     total += x;
 3:                                                 });

 1: array itgob()
 2: {
 3:     string s = map (backtrace()[-2][3..],
 4:                     lambda
 5:                         (mixed arg)
 6:                     {
 7:                         return sprintf ("%t", arg);
 8:                     }) * ", " + "\n";
 9:     return catch {
10:             write (s + "\n");
11:         };
12: }

 1: int add_three_integers(a, b, c)
 2:      int a;
 3:      int b;
 4:      int c;
 5: {
 6:     return a + b + c;
 7: }

10.3 Indentation Calculation

Indentation for a line is calculated from the syntactic context (see Syntactic Analysis).

First, a buffer position is found whose column will be the base for the indentation calculation. It’s the anchor position in the first syntactic element that provides one that is used. If no syntactic element has an anchor position then column zero is used.

Second, the syntactic symbols in each syntactic element are looked up in the c-offsets-alist style variable (see c-offsets-alist), which is an association list of syntactic symbols and the offsets to apply for those symbols. These offsets are added together with the base column to produce the new indentation column.

Let’s use our two code examples above to see how this works. Here is our first example again:

 1: void swap( int& a, int& b )
 2: {
 3:     int tmp = a;
 4:     a = b;
 5:     b = tmp;
 6: }

Let’s say point is on line 3 and we hit the TAB key to reindent the line. The syntactic context for that line is:

((defun-block-intro 29))

Since buffer position 29 is the first and only anchor position in the list, CC Mode goes there and asks for the current column. This brace is in column zero, so CC Mode uses ‘0’ as the base column.

Next, CC Mode looks up defun-block-intro in the c-offsets-alist style variable. Let’s say it finds the value ‘4’; it adds this to the base column ‘0’, yielding a running total indentation of 4 spaces.

Since there is only one syntactic element on the list for this line, indentation calculation is complete, and the total indentation for the line is 4 spaces.

Here’s another example:

 1: int add( int val, int incr, int doit )
 2: {
 3:     if( doit )
 4:         {
 5:             return( val + incr );
 6:         }
 7:     return( val );
 8: }

If we were to hit TAB on line 4 in the above example, the same basic process is performed, despite the differences in the syntactic context. The context for this line is:

((substatement-open 46))

Here, CC Mode goes to buffer position 46, which is the ‘i’ in if on line 3. This character is in the fourth column on that line so the base column is ‘4’. Then CC Mode looks up the substatement-open symbol in c-offsets-alist. Let’s say it finds the value ‘4’. It’s added with the base column and yields an indentation for the line of 8 spaces.

Simple, huh?

Actually, it’s a bit more complicated than that since the entries on c-offsets-alist can be much more than plain offsets. See c-offsets-alist, for the full story.

Anyway, the mode usually just does The Right Thing without you having to think about it in this much detail. But when customizing indentation, it’s helpful to understand the general indentation model being used.

As you configure CC Mode, you might want to set the variable c-echo-syntactic-information-p to non-nil so that the syntactic context and calculated offset always is echoed in the minibuffer when you hit TAB.

11.1 c-offsets-alist

This section explains the structure and semantics of the style variable c-offsets-alist, the principal variable for configuring indentation. Details of how to set it up, and its relationship to CC Mode’s style system are given in Style Variables.

User Option: c-offsets-alist ¶

This is an alist which associates an offset with each syntactic symbol. This offset is a rule specifying how to indent a line whose syntactic context matches the symbol. See Syntactic Analysis.

Note that the buffer-local binding of this alist in a CC Mode buffer contains an entry for every syntactic symbol. Its global binding and its settings within style specifications usually contain only a few entries. See Style Variables.

The offset specification associated with any particular syntactic symbol can be an integer, a variable name, a vector, a function or lambda expression, a list, or one of the following special symbols: +, -, ++, --, *, or /. The meanings of these values are described in detail below.

Here is an example fragment of a c-offsets-alist, showing some of these kinds of offsets:

((statement . 0)
 (substatement . +)
 (cpp-macro . [0])
 (topmost-intro-cont . c-lineup-topmost-intro-cont)
 (statement-block-intro . (add c-lineup-whitesmith-in-block
                               c-indent-multi-line-block))
 …

)

Command: c-set-offset (C-c C-o) ¶

This command changes the entry for a syntactic symbol in the current binding of c-offsets-alist, or it inserts a new entry if there isn’t already one for that syntactic symbol.

You can use c-set-offset interactively within a CC Mode buffer to make experimental changes to your indentation settings. C-c C-o prompts you for the syntactic symbol to change (defaulting to that of the current line) and the new offset (defaulting to the current offset).

c-set-offset takes two arguments when used programmatically: symbol, the syntactic element symbol to change and offset, the new offset for that syntactic element. You can call the command in your .emacs to change the global binding of c-offsets-alist (see Style Variables); you can use it in a hook function to make changes from the current style. CC Mode itself uses this function when initializing styles.

The “offset specifications” in c-offsets-alist can be any of the following:

An integer

The integer specifies a relative offset. All relative offsets⁴⁴ will be added together and used to calculate the indentation relative to an anchor position earlier in the buffer. See Indentation Calculation, for details. Most of the time, it’s probably better to use one of the special symbols like + than an integer (apart from zero).

One of the symbols +, -, ++, --, *, or /

These special symbols describe a relative offset in multiples of c-basic-offset:

By defining a style’s indentation in terms of c-basic-offset, you can change the amount of whitespace given to an indentation level while maintaining the same basic shape of your code. Here are the values that the special symbols correspond to:

+

c-basic-offset times 1

-

c-basic-offset times -1

++

c-basic-offset times 2

--

c-basic-offset times -2

*

c-basic-offset times 0.5

/

c-basic-offset times -0.5

A vector

The first element of the vector, an integer, sets the absolute indentation column. This will override any previously calculated indentation, but won’t override relative indentation calculated from syntactic elements later on in the syntactic context of the line being indented. See Indentation Calculation. Any elements in the vector beyond the first will be ignored.

A function or lambda expression

The function will be called and its return value will in turn be evaluated as an offset specification. Functions are useful when more context than just the syntactic symbol is needed to get the desired indentation. See Line-Up Functions, and Custom Line-Up Functions, for details about them.

A symbol with a variable binding

If the symbol also has a function binding, the function takes precedence over the variable. Otherwise the value of the variable is used. It must be an integer (which is used as relative offset) or a vector (an absolute offset).

A list

The offset can also be a list containing several offset specifications; these are evaluated recursively and combined. A list is typically only useful when some of the offsets are line-up functions. A common strategy is calling a sequence of functions in turn until one of them recognizes that it is appropriate for the source line and returns a non-nil value.

nil values are always ignored when the offsets are combined. The first element of the list specifies the method of combining the non-nil offsets from the remaining elements:

first

Use the first offset that doesn’t evaluate to nil. Subsequent elements of the list don’t get evaluated.

min

Use the minimum of all the offsets. All must be either relative or absolute; they can’t be mixed.

max

Use the maximum of all the offsets. All must be either relative or absolute; they can’t be mixed.

add

Add all the evaluated offsets together. Exactly one of them may be absolute, in which case the result is absolute. Any relative offsets that preceded the absolute one in the list will be ignored in that case.

As a compatibility measure, if the first element is none of the above then it too will be taken as an offset specification and the whole list will be combined according to the method first.

If an offset specification evaluates to nil, then a relative offset of 0 (zero) is used⁴⁵.

11.2 Interactive Customization

As an example of how to customize indentation, let’s change the style of this example⁴⁶:

 1: int add( int val, int incr, int doit )
 2: {
 3:   if( doit )
 4:     {
 5:       return( val + incr );
 6:     }
 7:   return( val );
 8: }

to:

 1: int add( int val, int incr, int doit )
 2: {
 3:   if( doit )
 4:   {
 5:     return( val + incr );
 6:   }
 7:   return( val );
 8: }

In other words, we want to change the indentation of braces that open a block following a condition so that the braces line up under the conditional, instead of being indented. Notice that the construct we want to change starts on line 4. To change the indentation of a line, we need to see which syntactic symbols affect the offset calculations for that line. Hitting C-c C-s on line 4 yields:

((substatement-open 44))

so we know that to change the offset of the open brace, we need to change the indentation for the substatement-open syntactic symbol.

To do this interactively, just hit C-c C-o. This prompts you for the syntactic symbol to change, providing a reasonable default. In this case, the default is substatement-open, which is just the syntactic symbol we want to change!

After you hit return, CC Mode will then prompt you for the new offset value, with the old value as the default. The default in this case is ‘+’, but we want no extra indentation so enter ‘0’ and RET. This will associate the offset 0 with the syntactic symbol substatement-open.

To check your changes quickly, just hit C-c C-q (c-indent-defun) to reindent the entire function. The example should now look like:

 1: int add( int val, int incr, int doit )
 2: {
 3:   if( doit )
 4:   {
 5:     return( val + incr );
 6:   }
 7:   return( val );
 8: }

Notice how just changing the open brace offset on line 4 is all we needed to do. Since the other affected lines are indented relative to line 4, they are automatically indented the way you’d expect. For more complicated examples, this might not always work. The general approach to take is to always start adjusting offsets for lines higher up in the file, then reindent and see if any following lines need further adjustments.

Command: c-set-offset symbol offset ¶

This is the command bound to C-c C-o. It provides a convenient way to set offsets on c-offsets-alist both interactively (see the example above) and from your mode hook.

It takes two arguments when used programmatically: symbol is the syntactic element symbol to change and offset is the new offset for that syntactic element.

11.3 Line-Up Functions

Often there are cases when a simple offset setting on a syntactic symbol isn’t enough to get the desired indentation—for example, you might want to line up a closing parenthesis with the matching opening one rather than indenting relative to its “anchor point”. CC Mode provides this flexibility with line-up functions.

The way you associate a line-up function with a syntactic symbol is described in c-offsets-alist. CC Mode comes with many predefined line-up functions for common situations. If none of these does what you want, you can write your own. See Custom Line-Up Functions. Sometimes, it is easier to tweak the standard indentation by adding a function to c-special-indent-hook (see Other Special Indentations).

The line-up functions haven’t been adapted for AWK buffers or tested with them. Some of them might work serendipitously. There shouldn’t be any problems writing custom line-up functions for AWK mode.

The calling convention for line-up functions is described fully in Custom Line-Up Functions. Roughly speaking, the return value is either an offset itself (such as + or [0]), another line-up function, or it’s nil, meaning “this function is inappropriate in this case - try a different one”. See c-offsets-alist.

The subsections below describe all the standard line-up functions, categorized by the sort of token the lining-up centers around. For each of these functions there is a “works with” list that indicates which syntactic symbols the function is intended to be used with.

• Brace and Parenthesis Line-Up Functions
• List Line-Up Functions
• Operator Line-Up Functions
• Comment Line-Up Functions
• Miscellaneous Line-Up Functions

11.4 Custom Line-Up Functions

The most flexible way to customize indentation is by writing custom line-up functions, and associating them with specific syntactic symbols (see c-offsets-alist). Depending on the effect you want, it might be better to write a c-special-indent-hook function rather than a line-up function (see Other Special Indentations).

CC Mode comes with an extensive set of predefined line-up functions, not all of which are used by the default styles. So there’s a good chance the function you want already exists. See Line-Up Functions, for a list of them. If you write your own line-up function, it’s probably a good idea to start working from one of these predefined functions, which can be found in the file cc-align.el. If you have written a line-up function that you think is generally useful, you’re very welcome to contribute it; please contact [email protected].

Line-up functions are passed a single argument, the syntactic element (see below). At the time of the call, point will be somewhere on the line being indented. The return value is a c-offsets-alist offset specification: for example, an integer, a symbol such as +, a vector, nil⁴⁹, or even another line-up function. Full details of these are in c-offsets-alist.

Line-up functions must not move point or change the content of the buffer (except temporarily). They are however allowed to do hidden buffer changes, i.e., setting text properties for caching purposes etc. Buffer undo recording is disabled while they run.

The syntactic element passed as the parameter to a line-up function is a cons cell of the form

(syntactic-symbol . anchor-position)

where syntactic-symbol is the symbol that the function was called for, and anchor-position is the anchor position (if any) for the construct that triggered the syntactic symbol (see Syntactic Analysis). This cons cell is how the syntactic element of a line used to be represented in CC Mode 5.28 and earlier. Line-up functions are still passed this cons cell, so as to preserve compatibility with older configurations. In the future, we may decide to convert to using the full list format—you can prepare your setup for this by using the access functions (c-langelem-sym, etc.) described below.

Some syntactic symbols, e.g., arglist-cont-nonempty, have more info in the syntactic element: typically other positions that can be interesting besides the anchor position. That info can’t be accessed through the passed argument, which is a cons cell. Instead, you can get this information from the variable c-syntactic-element, which is dynamically bound to the complete syntactic element. The variable c-syntactic-context might also be useful: it gets dynamically bound to the complete syntactic context. See Custom Brace Hanging.

CC Mode provides a few functions to access parts of syntactic elements in a more abstract way. Besides making the code easier to read, they also hide the difference between the old cons cell form used in the line-up function argument and the new list form used in c-syntactic-element and everywhere else. The functions are:

Function: c-langelem-sym langelem ¶

Return the syntactic symbol in langelem.

Function: c-langelem-pos langelem ¶

Return the anchor position in langelem, or nil if there is none.

Function: c-langelem-col langelem &optional preserve-point ¶

Return the column of the anchor position in langelem. Also move the point to that position unless preserve-point is non-nil.

Function: c-langelem-2nd-pos langelem ¶

Return the secondary position in langelem, or nil if there is none.

Note that the return value of this function is always nil if langelem is in the old cons cell form. Thus this function is only meaningful when used on syntactic elements taken from c-syntactic-element or c-syntactic-context.

Sometimes you may need to use the syntactic context of a line other than the one being indented. You can determine this by (temporarily) moving point onto this line and calling c-guess-basic-syntax (see Syntactic Analysis).

Custom line-up functions can be as simple or as complex as you like, and any syntactic symbol that appears in c-offsets-alist can have a custom line-up function associated with it.

11.5 Other Special Indentations

To configure macros which you invoke without a terminating ‘;’, see Macros with semicolons.

Here are the remaining odds and ends regarding indentation:

User Option: c-label-minimum-indentation ¶

In ‘gnu’ style (see Built-in Styles), a minimum indentation is imposed on lines inside code blocks. This minimum indentation is controlled by this style variable. The default value is 1.

It’s the function c-gnu-impose-minimum that enforces this minimum indentation. It must be present on c-special-indent-hook to work.

User Option: c-special-indent-hook ¶

This style variable is a standard hook variable that is called after every line is indented by CC Mode. It is called only if c-syntactic-indentation is non-nil (which it is by default (see Indentation Engine Basics)). You can put a function on this hook to do any special indentation or ad hoc line adjustments your style dictates, such as adding extra indentation to constructors or destructor declarations in a class definition, etc. Sometimes it is better to write a custom Line-up Function instead (see Custom Line-Up Functions).

When the indentation engine calls this hook, the variable c-syntactic-context is bound to the current syntactic context (i.e., what you would get by typing C-c C-s on the source line. See Custom Brace Hanging.). Note that you should not change point or mark inside a c-special-indent-hook function, i.e., you’ll probably want to wrap your function in a save-excursion⁵⁰.

Setting c-special-indent-hook in style definitions is handled slightly differently from other variables—A style can only add functions to this hook, not remove them. See Style Variables.

12.1 Customizing Macro Backslashes

CC Mode provides some tools to help keep the line continuation backslashes in macros neat and tidy. Their precise action is customized with these variables:

User Option: c-backslash-column ¶

User Option: c-backslash-max-column ¶

These variables control the alignment columns for line continuation backslashes in multiline macros. They are used by the functions that automatically insert or align such backslashes, e.g., c-backslash-region and c-context-line-break.

c-backslash-column specifies the minimum column for the backslashes. If any line in the macro goes past this column, then the next tab stop (i.e., next multiple of tab-width) in that line is used as the alignment column for all the backslashes, so that they remain in a single column. However, if any lines go past c-backslash-max-column then the backslashes in the rest of the macro will be kept at that column, so that the lines which are too long “stick out” instead.

Don’t ever set these variables to nil. If you want to disable the automatic alignment of backslashes, use c-auto-align-backslashes.

User Option: c-auto-align-backslashes ¶

Align automatically inserted line continuation backslashes if non-nil. When line continuation backslashes are inserted automatically for line breaks in multiline macros, e.g., by c-context-line-break, they are aligned with the other backslashes in the same macro if this flag is set.

If c-auto-align-backslashes is nil, automatically inserted backslashes are preceded by a single space, and backslashes get aligned only when you explicitly invoke the command c-backslash-region (C-c C-\).

12.2 Macros with semicolons

Macros which needn’t (or mustn’t) be followed by a semicolon when you invoke them, macros with semicolons, are very common. These can cause CC Mode to parse the next line wrongly as a statement-cont (see Function Symbols) and thus mis-indent it. At the top level, a macro invocation before a defun start can cause, for example, c-beginning-of-defun (C-M-a) not to find the correct start of the current function.

You can prevent these by specifying which macros have semicolons. It doesn’t matter whether or not such a macro has a parameter list:

User Option: c-macro-names-with-semicolon ¶

This buffer-local variable specifies which macros have semicolons. After setting its value, you need to call c-make-macro-with-semi-re for it to take effect. It should be set to one of these values:

nil

There are no macros with semicolons.

a list of strings

Each string is the name of a macro with a semicolon. Only valid #define names are allowed here. For example, to set the default value, you could write the following into your .emacs:

(setq c-macro-names-with-semicolon
      '("Q_OBJECT" "Q_PROPERTY" "Q_DECLARE" "Q_ENUMS"))

a regular expression

This matches each symbol which is a macro with a semicolon. It must not match any string which isn’t a valid #define name. For example:

(setq c-macro-names-with-semicolon
      "\\<\\(CLEAN_UP_AND_RETURN\\|Q_[[:upper:]]+\\)\\>")

Function: c-make-macro-with-semi-re ¶

Call this (non-interactive) function, which sets internal variables, each time you change the value of c-macro-names-with-semicolon after the major mode function has run. It takes no arguments, and its return value has no meaning. This function is called by CC Mode’s initialization code, after the mode hooks have run.

12.3 Noise Macros

In CC Mode, noise macros are macros which expand to nothing, or compiler directives (such as GCC’s __attribute__) which play no part in the syntax of the C (etc.) language. Some noise macros are followed by arguments in parentheses (possibly optionally), others are not.

Noise macros can easily confuse CC Mode’s analysis of function headers, causing them to be mis-fontified, or even mis-indented. You can prevent this confusion by specifying the identifiers which constitute noise macros.

User Option: c-noise-macro-names ¶

This variable is a list of names of noise macros which never have parenthesized arguments. Each element is a string, and must be a valid identifier. Alternatively, the variable may be a regular expression which matches the names of such macros. Such a noise macro is treated as whitespace by CC Mode. It must not also be in, or be matched by c-noise-macro-with-parens-names.

User Option: c-noise-macro-with-parens-names ¶

This variable is a list of names of noise macros which optionally have arguments in parentheses. Each element of the list is a string, and must be a valid identifier. Alternatively, the variable may be a regular expression which matches the names of such macros. Such a noise macro must not also be in, or be matched by c-noise-macro-names. For performance reasons, such a noise macro, including any parenthesized arguments, is specially handled, but it is only handled when used in declaration contexts⁵¹.

The two compiler directives __attribute__ and __declspec have traditionally been handled specially in CC Mode; for example they are fontified with font-lock-keyword-face. You don’t need to include these directives in c-noise-macro-with-parens-names, but doing so is OK.

Function: c-make-noise-macro-regexps ¶

Call this (non-interactive) function, which sets internal variables, on changing the value of c-noise-macro-names or c-noise-macro-with-parens-names after the major mode’s function has run. This function is called by CC Mode’s initialization code, after the mode hooks have run.

12.4 Indenting Directives

Sometimes you may want to indent particular preprocessor directives (e.g. #pragma) as though they were statements. To do this, first set up c-cpp-indent-to-body-directives to include the directive name(s), then enable the “indent to body” feature with c-toggle-cpp-indent-to-body.

User Option: c-cpp-indent-to-body-directives ¶

This variable is a list of names of CPP directives (not including the introducing ‘#’) which will be indented as though statements. Each element is a string, and must be a valid identifier. The default value is ("pragma").

If you add more directives to this variable, or remove directives from it, whilst “indent to body” is active, you need to re-enable the feature by calling c-toggle-cpp-indent-to-body for these changes to take effect⁵².

Function: c-toggle-cpp-indent-to-body ¶

With M-x c-toggle-cpp-indent-to-body, you enable or disable the “indent to body” feature. When called programmatically, it takes an optional numerical argument. A positive value will enable the feature, a zero or negative value will disable it.

You should set up c-cpp-indent-to-body-directives before calling this function, since the function sets internal state which depends on that variable.