11. 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 an 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 9.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.

Function: 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
<--> c-basic-offset@c

and

if (n > 0)
{                     <- c-indent-one-line-block@c
    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.

Function: c-indent-multi-line-block

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

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

and

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

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

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

Function: c-lineup-argcont

Line up a continued argument. E.g:

foo (xyz, aaa + bbb + ccc
          + ddd + eee + fff);  <- c-lineup-argcont@c

Only continuation lines like this are touched, nil is returned on lines which are the start of an argument.

Within a gcc asm block, : is recognised as an argument separator, but of course only between operand specifications, not in the expressions for the operands.

Works with: arglist-cont, arglist-cont-nonempty.

Function: c-lineup-arglist

Line up the current argument line under the first argument.

As a special case, if an argument on the same line as the open parenthesis starts with a brace block opener, the indentation is c-basic-offset only. This is intended as a "DWIM" measure in cases like macros that contains statement blocks, e.g:

A_VERY_LONG_MACRO_NAME ({
        some (code, with + long, lines * in[it]);
    });
<--> c-basic-offset@c

This is motivated partly because it's more in line with how code blocks are handled, and partly since it approximates the behavior of earlier CC Mode versions, which due to inaccurate analysis tended to indent such cases this way.

Works with: arglist-cont-nonempty, arglist-close.

Function: c-lineup-arglist-intro-after-paren: Line up a line to 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.

Function: c-lineup-arglist-close-under-paren

Set 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. It can also be used with arglist-cont and arglist-cont-nonempty to line up all lines inside a parenthesis under the open paren.

As a special case, if a brace block is opened at the same line as the open parenthesis of the argument list, the indentation is c-basic-offset only. See c-lineup-arglist for further discussion of this "DWIM" measure.

Works with: Almost all symbols, but are typically most useful on arglist-close, brace-list-close, arglist-cont and arglist-cont-nonempty.

Function: c-lineup-arglist-operators

Line up lines starting with an infix operator under the open paren. Return nil on lines that don't start with an operator, to leave those cases to other lineup functions. Example:

if (  x < 10
   || at_limit (x,     <- c-lineup-arglist-operators@c
                list)  <- c-lineup-arglist-operators returns nil@c
   )

Since this function doesn't do anything for lines without an infix operator you typically want to use it together with some other lineup settings, e.g. as follows (the arglist-close setting is just a suggestion to get a consistent style):

(c-set-offset 'arglist-cont
              '(c-lineup-arglist-operators 0))
(c-set-offset 'arglist-cont-nonempty
              '(c-lineup-arglist-operators c-lineup-arglist))
(c-set-offset 'arglist-close
              '(c-lineup-arglist-close-under-paren))

Works with: arglist-cont, arglist-cont-nonempty.

Function: 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.

Function: c-lineup-cascaded-calls

Line up "cascaded calls" under each other. If the line begins with -> or . and the preceding line ends with one or more function calls preceded by the same token, then the arrow is lined up with the first of those tokens. E.g:

r = proc->add(17)->add(18)
        ->add(19) +         <- c-lineup-cascaded-calls@c
  offset;                   <- c-lineup-cascaded-calls (inactive)@c

In any other situation nil is returned to allow use in list expressions.

Works with: topmost-intro-cont, statement-cont, arglist-cont, arglist-cont-nonempty.

Function: 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@c

and

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

As a special case, if a brace block is opened at the same line as the open parenthesis of the argument list, the indentation is c-basic-offset instead of the open paren column. See c-lineup-arglist for further discussion of this "DWIM" measure.

Works with: All *-close symbols.

Function: 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.

User Option: c-comment-only-line-offset

This style variable 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.

Function: c-lineup-cpp-define

Line up macro continuation lines according to the indentation of the construct preceding the macro. E.g:

const char msg[] =    <- The beginning of the preceding construct.@c
  \"Some text.\";

#define X(A, B)  \
do {             \    <- c-lineup-cpp-define@c
  printf (A, B); \
} while (0)

and:

int dribble() {
  if (!running)       <- The beginning of the preceding construct.@c
    error(\"Not running!\");

#define X(A, B)    \
  do {             \  <- c-lineup-cpp-define@c
    printf (A, B); \
  } while (0)

If c-syntactic-indentation-in-macros is non-nil, the function returns the relative indentation to the macro start line to allow accumulation with other offsets. E.g. in the following cases, cpp-define-intro is combined with the statement-block-intro that comes from the `do {' that hangs on the `#define' line:

const char msg[] =
  \"Some text.\";

#define X(A, B) do { \
  printf (A, B);     \  <- c-lineup-cpp-define@c
  this->refs++;      \
} while (0)             <- c-lineup-cpp-define@c

and:

int dribble() {
  if (!running)
    error(\"Not running!\");

#define X(A, B) do { \
    printf (A, B);   \  <- c-lineup-cpp-define@c
    this->refs++;    \
  } while (0)           <- c-lineup-cpp-define@c

The relative indentation returned by c-lineup-cpp-define is zero and two, respectively, on the two lines in each of these examples. They are then added to the two column indentation that statement-block-intro gives in both cases here.

If the relative indentation is zero, then nil is returned instead. That is useful in a list expression to specify the default indentation on the top level.

If c-syntactic-indentation-in-macros is nil then this function keeps the current indentation, except for empty lines (ignoring the ending backslash) where it takes the indentation from the closest preceding nonempty line in the macro. If there's no such line in the macro then the indentation is taken from the construct preceding it, as described above.

Works with: cpp-define-intro.

Function: 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.
Works with: Any syntactic symbol.

Function: c-lineup-gcc-asm-reg

Line up a gcc asm register under one on a previous line.

    asm ("foo %1, %0\n"
         "bar %0, %1"
         : "=r" (w),
           "=r" (x)
         :  "0" (y),
            "1" (z));

The `x' line is aligned to the text after the `:' on the `w' line, and similarly `z' under `y'.

This is done only in an `asm' or `__asm__' block, and only to those lines mentioned. Anywhere else nil is returned. The usual arrangement is to have this routine as an extra feature at the start of arglist lineups, e.g.

(c-lineup-gcc-asm-reg c-lineup-arglist)

Works with: arglist-cont, arglist-cont-nonempty.

Function: 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.

Function: c-lineup-java-inher

Line up Java implements and extends declarations. If class names follow 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
    <--> c-basic-offset@c

and

class Foo
    extends Cyphr,
            Bar       <- c-lineup-java-inher@c

Works with: inher-cont.

Function: c-lineup-java-throws

Line up Java throws declarations. If exception names follow 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@c
        Bar           <- c-lineup-java-throws@c
<--><--> c-basic-offset@c

and

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

Works with: func-decl-cont.

Function: c-lineup-knr-region-comment

Line up a comment in the "K&R region" with the declaration. That is the region between the function or class header and the beginning of the block. E.g:

int main()
/* Called at startup. */  <- c-lineup-knr-region-comment@c
{
  return 0;
}

Return nil if called in any other situation, to be useful in list expressions.

Works with: comment-intro.

Function: c-lineup-math: Line up the current line to 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: topmost-intro-cont, statement-cont, arglist-cont, arglist-cont-nonempty.

Function: 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@c

and

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

and

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

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

Function: c-lineup-ObjC-method-call: For Objective-C code, line up selector args as Emacs Lisp 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.

Function: 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.

Function: 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.

Function: 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(32). E.g:

int main()
{ puts ("Hello!");
  return 0;           <- c-lineup-runin-statements@c
}

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.

Function: c-lineup-streamop: Line up C++ stream operators (i.e. `<<' and `>>').
Works with: stream-op.

Function: c-lineup-string-cont

Line up a continued string under the one it continues. A continued string in this sense is where a string literal follows directly after another one. E.g:

result = prefix + "A message "
                  "string.";    <- c-lineup-string-cont@c

nil is returned in other situations, to allow stacking with other lineup functions.

Works with: topmost-intro-cont, statement-cont, arglist-cont, arglist-cont-nonempty.

Function: 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.

Function: c-lineup-topmost-intro-cont

Line up declaration continuation lines zero or one indentation step(33). For lines preceding a definition, zero is used. For other lines, c-basic-offset is added to the indentation. E.g:

int
neg (int i)           <- c-lineup-topmost-intro-cont@c
{
    return -i;
}

and

struct
larch                 <- c-lineup-topmost-intro-cont@c
{
    double height;
}
    the_larch,        <- c-lineup-topmost-intro-cont@c
    another_larch;    <- c-lineup-topmost-intro-cont@c
<--> c-basic-offset@c

and

struct larch
the_larch,            <- c-lineup-topmost-intro-cont@c
    another_larch;    <- c-lineup-topmost-intro-cont@c

Works with: topmost-intro-cont.

Function: 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@c
    }

and

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

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 and all in* symbols, e.g. inclass and inextern-lang.

[ << ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

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