9. Indentation Functions

Often there are cases when a simple offset setting on a syntactic symbol isn't enough to get the desired indentation. Therefore, it's also possible to use a indentation function (a.k.a. line-up function) for a syntactic symbol.

CC Mode comes with many predefined indentation functions for common situations. If none of these does what you want, you can write your own, see 7.5.1 Custom Indentation Functions. If you do, it's probably a good idea to start working from one of these predefined functions, they can be found in the file `cc-align.el'.

For every function below there is a "works with" list that indicates which syntactic symbols the function is intended to be used with.

c-lineup-arglist

Line up the current argument line under the first argument.

Works with: arglist-cont-nonempty.

c-lineup-arglist-intro-after-paren

Line up a line just after the open paren of the surrounding paren or brace block.

Works with: defun-block-intro, brace-list-intro, statement-block-intro, statement-case-intro, arglist-intro.

c-lineup-arglist-close-under-paren

Set e.g. your arglist-close syntactic symbol to this line-up function so that parentheses that close argument lists will line up under the parenthesis that opened the argument list.

Works with: defun-close, class-close, inline-close, block-close, brace-list-close, arglist-close, extern-lang-close, namespace-close (for most of these, a zero offset will normally produce the same result, though).

c-lineup-close-paren

Line up the closing paren under its corresponding open paren if the open paren is followed by code. If the open paren ends its line, no indentation is added. E.g:

main (int, char ** ) // c-lineup-close-paren

and

main ( int, char ** ) // c-lineup-close-paren

Works with: defun-close, class-close, inline-close, block-close, brace-list-close, arglist-close, extern-lang-close, namespace-close.

c-lineup-streamop

Line up C++ stream operators (i.e. `<<' and `>>').

Works with: stream-op.

c-lineup-multi-inher

Line up the classes in C++ multiple inheritance clauses and member initializers under each other. E.g:

Foo::Foo (int a, int b): Cyphr (a), Bar (b) // c-lineup-multi-inher

and

class Foo : public Cyphr, public Bar // c-lineup-multi-inher

and

Foo::Foo (int a, int b) : Cyphr (a) , Bar (b) // c-lineup-multi-inher

Works with: inher-cont, member-init-cont.

c-lineup-java-inher

Line up Java implements and extends declarations. If class names follows on the same line as the `implements'/`extends' keyword, they are lined up under each other. Otherwise, they are indented by adding c-basic-offset to the column of the keyword. E.g:

class Foo extends Bar // c-lineup-java-inher <--> c-basic-offset

and

class Foo extends Cyphr, Bar // c-lineup-java-inher

Works with: inher-cont.

c-lineup-java-throws

Line up Java throws declarations. If exception names follows on the same line as the throws keyword, they are lined up under each other. Otherwise, they are indented by adding c-basic-offset to the column of the `throws' keyword. The `throws' keyword itself is also indented by c-basic-offset from the function declaration start if it doesn't hang. E.g:

int foo() throws // c-lineup-java-throws Bar // c-lineup-java-throws <--><--> c-basic-offset

and

int foo() throws Cyphr, Bar, // c-lineup-java-throws Vlod // c-lineup-java-throws

Works with: func-decl-cont.

c-indent-one-line-block

Indent a one line block c-basic-offset extra. E.g:

if (n > 0) {m+=n; n=0;} // c-indent-one-line-block <--> c-basic-offset

and

if (n > 0) { // c-indent-one-line-block m+=n; n=0; }

The block may be surrounded by any kind of parenthesis characters. nil is returned if the line doesn't start with a one line block, which makes the function usable in list expressions.

Works with: Almost all syntactic symbols, but most useful on the -open symbols.

c-indent-multi-line-block

Indent a multi line block c-basic-offset extra. E.g:

int *foo[] = { NULL, {17}, // c-indent-multi-line-block

and

int *foo[] = { NULL, { // c-indent-multi-line-block 17 }, <--> c-basic-offset

The block may be surrounded by any kind of parenthesis characters. nil is returned if the line doesn't start with a multi line block, which makes the function usable in list expressions.

Works with: Almost all syntactic symbols, but most useful on the -open symbols.

c-lineup-C-comments

Line up C block comment continuation lines. Various heuristics are used to handle most of the common comment styles. Some examples:

/* /** /* * text * text text */ */ */ /* text /* /** text ** text ** text */ */ */ /************************************************** * text *************************************************/ /************************************************** Free form text comments: In comments with a long delimiter line at the start, the indentation is kept unchanged for lines that start with an empty comment line prefix. The delimiter line is whatever matches the comment-start-skip regexp. **************************************************/

The style variable c-comment-prefix-regexp is used to recognize the comment line prefix, e.g. the `*' that usually starts every line inside a comment.

Works with: The c syntactic symbol.

c-lineup-comment

Line up a comment-only line according to the style variable c-comment-only-line-offset. If the comment is lined up with a comment starter on the previous line, that alignment is preserved.

c-comment-only-line-offset specifies the extra offset for the line. It can contain an integer or a cons cell of the form

(<non-anchored-offset> . <anchored-offset>)

where non-anchored-offset is the amount of offset given to non-column-zero anchored lines, and anchored-offset is the amount of offset to give column-zero anchored lines. Just an integer as value is equivalent to (<value> . -1000).

Works with: comment-intro.

c-lineup-runin-statements

Line up statements for coding standards which place the first statement in a block on the same line as the block opening brace(34). E.g:

int main() { puts (\"Hello world!\"); return 0; // c-lineup-runin-statements }

If there is no statement after the opening brace to align with, nil is returned. This makes the function usable in list expressions.

Works with: The statement syntactic symbol.

c-lineup-math

Line up the current line after the equal sign on the first line in the statement. If there isn't any, indent with c-basic-offset. If the current line contains an equal sign too, try to align it with the first one.

Works with: statement-cont.

c-lineup-template-args

Line up the arguments of a template argument list under each other, but only in the case where the first argument is on the same line as the opening `<'.

To allow this function to be used in a list expression, nil is returned if there's no template argument on the first line.

Works with: template-args-cont.

c-lineup-ObjC-method-call

For Objective-C code, line up selector args as elisp-mode does with function args: go to the position right after the message receiver, and if you are at the end of the line, indent the current line c-basic-offset columns from the opening bracket; otherwise you are looking at the first character of the first method call argument, so lineup the current line with it.

Works with: objc-method-call-cont.

c-lineup-ObjC-method-args

For Objective-C code, line up the colons that separate args. The colon on the current line is aligned with the one on the first line.

Works with: objc-method-args-cont.

c-lineup-ObjC-method-args-2

Similar to c-lineup-ObjC-method-args but lines up the colon on the current line with the colon on the previous line.

Works with: objc-method-args-cont.

c-lineup-inexpr-block

This can be used with the in-expression block symbols to indent the whole block to the column where the construct is started. E.g. for Java anonymous classes, this lines up the class under the `new' keyword, and in Pike it lines up the lambda function body under the `lambda' keyword. Returns nil if the block isn't part of such a construct.

Works with: inlambda, inexpr-statement, inexpr-class.

c-lineup-whitesmith-in-block

Line up lines inside a block in Whitesmith style. It's done in a way that works both when the opening brace hangs and when it doesn't. E.g:

something { foo; // c-lineup-whitesmith-in-block }

and

something { foo; // c-lineup-whitesmith-in-block } <--> c-basic-offset

In the first case the indentation is kept unchanged, in the second c-basic-offset is added.

Works with: defun-close, defun-block-intro, block-close, brace-list-close, brace-list-intro, statement-block-intro, inclass, inextern-lang, innamespace.

c-lineup-dont-change

This lineup function makes the line stay at whatever indentation it already has; think of it as an identity function for lineups. It is used for cpp-macro-cont lines.

Works with: Any syntactic symbol.