CC MODE Version 5 Documentation. Node: Indentation Commands

prev UP Commands NEXT Other Commands

5.1: Indentation Commands

Various commands are provided which allow you to conveniently re-indent C constructs. There are several things to note about these indentation commands. First, when you change your programming style, either interactively or through some other means, your file does not automatically get re-indented. When you change style parameters, you will typically need to reformat the line, expression, or buffer to see the effects of your changes.

Second, changing some variables have no effect on existing code, even when you do re-indent. For example, the c-hanging-* variables and c-cleanup-list only affect new code as it is typed in on-the-fly, so changing c-hanging-braces-alist and re-indenting the buffer will not adjust placement of braces already in the file.

Third, re-indenting large portions of code is currently rather inefficient. Improvements have been made since previous releases of CC Mode, and much more radical improvements are planned, but for now you need to be aware of this [1]. Some provision has been made to at least inform you as to the progress of the re-indentation. The variable c-progress-interval controls how often a progress message is displayed. Set this variable to nil to inhibit progress messages, including messages normally printed when indentation is started and completed.

Also, except as noted below, re-indentation is always driven by the same mechanisms that control on-the-fly indentation of code. See New Indentation Engine for details.

To indent a single line of code, use TAB (c-indent-command). The behavior of this command is controlled by the variable c-tab-always-indent. When this variable is t, TAB always just indents the current line. When nil, the line is indented only if point is at the left margin, or on or before the first non-whitespace character on the line, otherwise something else happens[2]. If the value of c-tab-always-indent is something other than t or nil (e.g. 'other), then a real tab character[3] is inserted only when point is inside a literal (see Auto-newline insertion), otherwise the line is indented.

To indent an entire balanced brace or parenthesis expression, use M-C-q (c-indent-exp). Note that point should be on the opening brace or parenthesis of the expression you want to indent.

Another very convenient keystroke is C-c C-q (c-indent-defun) when re-indents the entire top-level function or class definition that encompasses point. It leaves point at the same position within the buffer.

To indent any arbitrary region of code, use M-C-\ (indent-region). This is a standard Emacs command, specially tailored for C code in a CC Mode buffer. Note that of course, point and mark must delineate the region you want to indent.

While not strictly an indentation function, M-C-h (c-mark-function) is useful for marking the current top-level function or class definition as the current region.

[1] In particular, I have had people complain about the speed with which lex(1) output is re-indented. Lex, yacc, and other code generators usually output some pretty perversely formatted code. Don't try to indent this stuff!

[2] Actually what happens is that the function stored in c-insert-tab-function is called. Normally this just inserts a real tab character, or the equivalent number of spaces, depending on the setting of the variable indent-tabs-mode. If you preferred, you could set c-insert-tab-function to tab-to-tab-stop for example.

[3] The caveat about indent-tabs-mode in the previous footnote also applies here.

prev UP Commands NEXT Other Commands