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 Note: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(1). 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.
---------- Footnotes ----------
(1) Run-in style doesn't really work too well. You might need to
write your own custom indentation functions to better support this
style.