This is ../info/ccmode, produced by makeinfo version 4.0 from
cc-mode.texi.
INFO-DIR-SECTION Emacs
START-INFO-DIR-ENTRY
* CC Mode: (ccmode). Emacs mode for editing C, C++, Objective-C,
Java, Pike, and IDL code.
END-INFO-DIR-ENTRY
Copyright (C) 1995, 96, 97, 98, 99, 2000, 2001 Free Software
Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "The GNU Manifesto", "Distribution" and "GNU
GENERAL PUBLIC LICENSE", with the Front-Cover texts being "A GNU
Manual", and with the Back-Cover Texts as in (a) below. A copy of the
license is included in the section entitled "GNU Free Documentation
License" in the Emacs manual.
(a) The FSF's Back-Cover Text is: "You have freedom to copy and
modify this GNU Manual, like GNU software. Copies published by the Free
Software Foundation raise funds for GNU development."
This document is part of a collection distributed under the GNU Free
Documentation License. If you want to distribute this document
separately from the collection, you can do so by adding a copy of the
license to the document, as described in section 6 of the license.
File: ccmode, Node: Syntactic Symbols, Next: Indentation Functions, Prev: Customizing Indentation, Up: Top
Syntactic Symbols
*****************
Here is a complete list of the recognized syntactic symbols as
described in the `c-offsets-alist' style variable, along with a brief
description. More detailed descriptions follow.
`string'
Inside a multi-line string.
`c'
Inside a multi-line C style block comment.
`defun-open'
Brace that opens a top-level function definition.
`defun-close'
Brace that closes a top-level function definition.
`defun-block-intro'
The first line in a top-level defun.
`class-open'
Brace that opens a class definition.
`class-close'
Brace that closes a class definition.
`inline-open'
Brace that opens an in-class inline method.
`inline-close'
Brace that closes an in-class inline method.
`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.
`knr-argdecl-intro'
First line of a K&R C argument declaration.
`knr-argdecl'
Subsequent lines in a K&R C argument declaration.
`topmost-intro'
The first line in a "topmost" definition.
`topmost-intro-cont'
Topmost definition continuation lines.
`member-init-intro'
First line in a member initialization list.
`member-init-cont'
Subsequent member initialization list lines.
`inher-intro'
First line of a multiple inheritance list.
`inher-cont'
Subsequent multiple inheritance lines.
`block-open'
Statement block open brace.
`block-close'
Statement block close brace.
`brace-list-open'
Open brace of an enum or static array list.
`brace-list-close'
Close brace of an enum or static array list.
`brace-list-intro'
First line in an enum or static array list.
`brace-list-entry'
Subsequent lines in an enum or static array list.
`brace-entry-open'
Subsequent lines in an enum or static array list where the line
begins with an open brace.
`statement'
A statement.
`statement-cont'
A continuation of a statement.
`statement-block-intro'
The first line in a new statement block.
`statement-case-intro'
The first line in a case block.
`statement-case-open'
The first line in a case block that starts with a brace.
`substatement'
The first line after a conditional or loop construct.
`substatement-open'
The brace that opens a substatement block.
`case-label'
A `case' or `default' label.
`access-label'
C++ access control label.
`label'
Any non-special C label.
`do-while-closure'
The `while' line that ends a `do'-`while' construct.
`else-clause'
The `else' line of an `if'-`else' construct.
`catch-clause'
The `catch' or `finally' (in Java) line of a `try'-`catch'
construct.
`comment-intro'
A line containing only a comment introduction.
`arglist-intro'
The first line in an argument list.
`arglist-cont'
Subsequent argument list lines when no arguments follow on the
same line as the arglist opening paren.
`arglist-cont-nonempty'
Subsequent argument list lines when at least one argument follows
on the same line as the arglist opening paren.
`arglist-close'
The solo close paren of an argument list.
`stream-op'
Lines continuing a stream operator (C++ only).
`inclass'
The line is nested inside a class definition.
`cpp-macro'
The start of a C preprocessor macro definition.
`cpp-macro-cont'
Subsequent lines of a multi-line C preprocessor macro definition.
`friend'
A C++ friend declaration.
`objc-method-intro'
The first line of an Objective-C method. definition.
`objc-method-args-cont'
Lines continuing an Objective-C method. definition
`objc-method-call-cont'
Lines continuing an Objective-C method call.
`extern-lang-open'
Brace that opens an external language block.
`extern-lang-close'
Brace that closes an external language block.
`inextern-lang'
Analogous to `inclass' syntactic symbol, but used inside external
language blocks (e.g. `extern "C" {').
`namespace-open'
Brace that opens a C++ namespace block.
`namespace-close'
Brace that closes a C++ namespace block.
`innamespace'
Analogous to `inextern-lang' syntactic symbol, but used inside C++
namespace blocks.
`template-args-cont'
C++ template argument list continuations.
`inlambda'
Analogous to `inclass' syntactic symbol, but used inside lambda
(i.e. anonymous) functions. Only used in Pike mode.
`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.
`inexpr-statement'
A statement block inside an expression. The gcc C extension of
this is recognized. It's also used for the special functions that
takes a statement block as an argument in Pike.
`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.
Most syntactic symbol names follow a general naming convention.
When a line begins with an open or close brace, the syntactic symbol
will contain the suffix `-open' or `-close' respectively.
Usually, a distinction is made between the first line that
introduces a construct and lines that continue a construct, and the
syntactic symbols that represent these lines will contain the suffix
`-intro' or `-cont' respectively. As a sub-classification of this
scheme, a line which is the first of a particular brace block construct
will contain the suffix `-block-intro'.
Let's look at some examples to understand how this works. Remember
that you can check the syntax of any line by using `C-c C-s'.
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: }
Line 1 shows a `topmost-intro' since it is the first line that
introduces a top-level construct. Line 2 is a continuation of the
top-level construct introduction so it has the syntax
`topmost-intro-cont'. Line 3 shows a `defun-open' since it is the
brace that opens a top-level function definition. Line 9 is the
corresponding `defun-close' since it contains the brace that closes the
top-level function definition. Line 4 is a `defun-block-intro', i.e.
it is the first line of a brace-block, enclosed in a top-level function
definition.
Lines 5, 6, and 7 are all given `statement' syntax since there isn't
much special about them. Note however that line 8 is given
`statement-cont' syntax since it continues the statement begun on the
previous line.
Here's another example, which illustrates some C++ class syntactic
symbols:
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: }
As in the previous example, line 1 has the `topmost-intro' syntax.
Here however, the brace that opens a C++ class definition on line 4 is
assigned the `class-open' syntax. Note that in C++, classes, structs,
and unions are essentially equivalent syntactically (and are very
similar semantically), so replacing the `class' keyword in the example
above with `struct' or `union' would still result in a syntax of
`class-open' for line 4 (1). Similarly, line 18 is assigned
`class-close' syntax.
Line 2 introduces the inheritance list for the class so it is
assigned the `inher-intro' syntax, and line 3, which continues the
inheritance list is given `inher-cont' syntax.
Hitting `C-c C-s' on line 5 shows the following analysis:
`((inclass . 58) (access-label . 67))'
The primary syntactic symbol for this line is `access-label' as this a
label keyword that specifies access protection in C++. However,
because this line is also a top-level construct inside a class
definition, the analysis actually shows two syntactic symbols. The
other syntactic symbol assigned to this line is `inclass'. Similarly,
line 6 is given both `inclass' and `topmost-intro' syntax:
`((inclass . 58) (topmost-intro . 60))'
Line 7 introduces a C++ member initialization list and as such is
given `member-init-intro' syntax. Note that in this case it is _not_
assigned `inclass' since this is not considered a top-level construct.
Lines 8 through 10 are all assigned `member-init-cont' since they
continue the member initialization list started on line 7.
Line 11's analysis is a bit more complicated:
`((inclass . 58) (inline-open))'
This line is assigned a syntax of both `inline-open' and `inclass'
because it opens an "in-class" C++ inline method definition. This is
distinct from, but related to, the C++ notion of an inline function in
that its definition occurs inside an enclosing class definition, which
in C++ implies that the function should be inlined. If though, the
definition of the `Bass' constructor appeared outside the class
definition, the construct would be given the `defun-open' syntax, even
if the keyword `inline' appeared before the method name, as in:
class Bass
: public Guitar,
public Amplifiable
{
public:
Bass();
}
inline
Bass::Bass()
: eString( new BassString( 0.105 )),
aString( new BassString( 0.085 )),
dString( new BassString( 0.065 )),
gString( new BassString( 0.045 ))
{
eString.tune( 'E' );
aString.tune( 'A' );
dString.tune( 'D' );
gString.tune( 'G' );
}
Returning to the previous example, line 16 is given `inline-close'
syntax, while line 12 is given `defun-block-open' syntax, and lines 13
through 15 are all given `statement' syntax. Line 17 is interesting in
that its syntactic analysis list contains three elements:
`((friend) (inclass . 58) (topmost-intro . 380))'
The `friend' syntactic symbol is a modifier that typically does not
have a relative buffer position.
Template definitions introduce yet another syntactic symbol:
1: ThingManager <int,
2: Framework::Callback *,
3: Mutex> framework_callbacks;
Here, line 1 is analyzed as a `topmost-intro', but lines 2 and 3 are
both analyzed as `template-args-cont' lines.
Here is another (totally contrived) example which illustrates how
syntax is assigned to various conditional constructs:
1: void spam( int index )
2: {
3: for( int i=0; i<index; i++ )
4: {
5: if( i == 10 )
6: {
7: do_something_special();
8: }
9: else
10: do_something( i );
11: }
12: do {
13: another_thing( i-- );
14: }
15: while( i > 0 );
16: }
Only the lines that illustrate new syntactic symbols will be discussed.
Line 4 has a brace which opens a conditional's substatement block.
It is thus assigned `substatement-open' syntax, and since line 5 is the
first line in the substatement block, it is assigned
`substatement-block-intro' syntax. Lines 6 and 7 are assigned similar
syntax. Line 8 contains the brace that closes the inner substatement
block. It is given the syntax `block-close', as are lines 11 and 14.
Line 9 is a little different -- since it contains the keyword `else'
matching the `if' statement introduced on line 5, it is given the
`else-clause' syntax. The `try'-`catch' constructs in C++ and Java are
treated this way too, with the only difference that the `catch', and in
Java also `finally', is marked with `catch-clause'.
Line 10 is also slightly different. Because `else' is considered a
conditional introducing keyword (2), and because the following
substatement is not a brace block, line 10 is assigned the
`substatement' syntax.
One other difference is seen on line 15. The `while' construct that
closes a `do' conditional is given the special syntax
`do-while-closure' if it appears on a line by itself. Note that if the
`while' appeared on the same line as the preceding close brace, that
line would have been assigned `block-close' syntax instead.
Switch statements have their own set of syntactic symbols. Here's an
example:
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: }
Here, lines 4, 7, and 10 are all assigned `case-label' syntax, while
lines 5 and 8 are assigned `statement-case-intro'. Line 11 is treated
slightly differently since it contains a brace that opens a block -- it
is given `statement-case-open' syntax.
There are a set of syntactic symbols that are used to recognize
constructs inside of brace lists. A brace list is defined as an `enum'
or aggregate initializer list, such as might statically initialize an
array of structs. The three special aggregate constructs in Pike, `({
})', `([ ])' and `(< >)', are treated as brace lists too. An example:
1: static char* ingredients[] =
2: {
3: "Ham",
4: "Salt",
5: NULL
6: }
Following convention, line 2 in this example is assigned
`brace-list-open' syntax, and line 3 is assigned `brace-list-intro'
syntax. Likewise, line 6 is assigned `brace-list-close' syntax. Lines
4 and 5 however, are assigned `brace-list-entry' syntax, as would all
subsequent lines in this initializer list.
Your static initializer might be initializing nested structures, for
example:
1: struct intpairs[] =
2: {
3: { 1, 2 },
4: {
5: 3,
6: 4
7: }
8: { 1,
9: 2 },
10: { 3, 4 }
11: }
Here, you've already seen the analysis of lines 1, 2, 3, and 11. On
line 4, things get interesting; this line is assigned
`brace-entry-open' syntactic symbol because it's a bracelist entry line
that starts with an open brace. Lines 5 and 6 (and line 9) are pretty
standard, and line 7 is a `brace-list-close' as you'd expect. Once
again, line 8 is assigned as `brace-entry-open' as is line 10.
External language definition blocks also have their own syntactic
symbols. In this example:
1: extern "C"
2: {
3: int thing_one( int );
4: int thing_two( double );
5: }
line 2 is given the `extern-lang-open' syntax, while line 5 is given
the `extern-lang-close' syntax. The analysis for line 3 yields:
`((inextern-lang) (topmost-intro . 14))', where `inextern-lang' is a
modifier similar in purpose to `inclass'.
Similarly, C++ namespace constructs have their own associated
syntactic symbols. In this example:
1: namespace foo
2: {
3: void xxx() {}
4: }
line 2 is given the `namespace-open' syntax, while line 4 is given the
`namespace-close' syntax. The analysis for line 3 yields:
`((innamespace) (topmost-intro . 17))', where `innamespace' is a
modifier similar in purpose to `inextern-lang' and `inclass'.
A number of syntactic symbols are associated with parenthesis lists,
a.k.a argument lists, as found in function declarations and function
calls. This example illustrates these:
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: }
Lines 5 and 12 are assigned `arglist-intro' syntax since they are
the first line following the open parenthesis, and lines 7 and 14 are
assigned `arglist-close' syntax since they contain the parenthesis that
closes the argument list.
Lines that continue argument lists can be assigned one of two
syntactic symbols. For example, Lines 2 and 17 are assigned
`arglist-cont-nonempty' syntax. What this means is that they continue
an argument list, but that the line containing the parenthesis that
opens the list is _not empty_ following the open parenthesis. Contrast
this against lines 6 and 13 which are assigned `arglist-cont' syntax.
This is because the parenthesis that opens their argument lists is the
last character on that line.
Note that there is no `arglist-open' syntax. This is because any
parenthesis that opens an argument list, appearing on a separate line,
is assigned the `statement-cont' syntax instead.
A few miscellaneous syntactic symbols that haven't been previously
covered are illustrated by this C++ example:
1: void Bass::play( int volume )
2: const
3: {
4: /* this line starts a multi-line
5: * comment. This line should get `c' syntax */
6:
7: char* a_multiline_string = "This line starts a multi-line \
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: }
The lines to note in this example include:
* Line 2 is assigned the `func-decl-cont' syntax.
* Line 4 is assigned both `defun-block-intro' _and_ `comment-intro'
syntax.
* Line 5 is assigned `c' syntax.
* Line 6 which, even though it contains nothing but whitespace, is
assigned `defun-block-intro'. Note that the appearance of the
comment on lines 4 and 5 do not cause line 6 to be assigned
`statement' syntax because comments are considered to be
"syntactic whitespace", which are ignored when analyzing code.
* Line 8 is assigned `string' syntax.
* Line 10 is assigned `label' syntax.
* Line 11 is assigned `block-open' syntax.
* Lines 12 and 14 are assigned `cpp-macro' syntax in addition to the
normal syntactic symbols (`statement-block-intro' and `statement',
respectively). Normally `cpp-macro' is configured to cancel out
the normal syntactic context to make all preprocessor directives
stick to the first column, but that's easily changed if you want
preprocessor directives to be indented like the rest of the code.
* Line 17 is assigned `stream-op' syntax.
Multi-line C preprocessor macros are now (somewhat) supported. At
least CC Mode now recognizes the fact that it is inside a multi-line
macro, and it properly skips such macros as syntactic whitespace. In
this example:
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
line 1 is given the syntactic symbol `cpp-macro'. This first line of a
macro is always given this symbol. The second and subsequent lines
(e.g. lines 2 through 5) are given the `cpp-macro-cont' syntactic
symbol, with a relative buffer position pointing to the `#' which
starts the macro definition.
In Objective-C buffers, there are three additional syntactic symbols
assigned to various message calling constructs. Here's an example
illustrating these:
1: - (void)setDelegate:anObject
2: withStuff:stuff
3: {
4: [delegate masterWillRebind:self
5: toDelegate:anObject
6: withExtraStuff:stuff];
7: }
Here, line 1 is assigned `objc-method-intro' syntax, and line 2 is
assigned `objc-method-args-cont' syntax. Lines 5 and 6 are both
assigned `objc-method-call-cont' syntax.
Java has a concept of anonymous classes, which may look something
like this:
1: public void watch(Observable o) {
2: o.addObserver(new Observer() {
3: public void update(Observable o, Object arg) {
4: history.addElement(arg);
5: }
6: });
7: }
The brace following the `new' operator opens the anonymous class.
Lines 3 and 6 are assigned the `inexpr-class' syntax, besides the
`inclass' symbol used in normal classes. Thus, the class will be
indented just like a normal class, with the added indentation given to
`inexpr-class'.
There are a few occasions where a statement block may be used inside
an expression. One is in C code using the gcc extension for this, e.g:
1: int res = ({
2: int y = foo (); int z;
3: if (y > 0) z = y; else z = - y;
4: z;
5: });
Lines 2 and 5 get the `inexpr-statement' syntax, besides the symbols
they'd get in a normal block. Therefore, the indentation put on
`inexpr-statement' is added to the normal statement block indentation.
In Pike code, there are a few other situations where blocks occur
inside statements, as illustrated here:
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: }
Lines 4 through 8 contain a lambda function, which CC Mode recognizes
by the `lambda' keyword. If the function argument list is put on a
line of its own, as in line 5, it gets the `lambda-intro-cont' syntax.
The function body is handled as an inline method body, with the
addition of the `inlambda' syntactic symbol. This means that line 6
gets `inlambda' and `inline-open', and line 8 gets `inline-close'(3).
On line 9, `catch' is a special function taking a statement block as
its argument. The block is handled as an in-expression statement with
the `inexpr-statement' syntax, just like the gcc extended C example
above. The other similar special function, `gauge', is handled like
this too.
Two other syntactic symbols can appear in old style, non-prototyped C
code (4):
1: int add_three_integers(a, b, c)
2: int a;
3: int b;
4: int c;
5: {
6: return a + b + c;
7: }
Here, line 2 is the first line in an argument declaration list and
so is given the `knr-argdecl-intro' syntactic symbol. Subsequent lines
(i.e. lines 3 and 4 in this example), are given `knr-argdecl' syntax.
---------- Footnotes ----------
(1) This is the case even for C and Objective-C. For consistency,
structs in all supported languages are syntactically equivalent to
classes. Note however that the keyword `class' is meaningless in C and
Objective-C.
(2) The list of conditional keywords are (in C, C++, Objective-C,
Java, and Pike): `for', `if', `do', `else', `while', and `switch'. C++
and Java have two additional conditional keywords: `try' and `catch'.
Java also has the `finally' and `synchronized' keywords.
(3) You might wonder why it doesn't get `inlambda' too. It's
because the closing brace is relative to the opening brace, which
stands on its own line in this example. If the opening brace was
hanging on the previous line, then the closing brace would get the
`inlambda' syntax too to be indented correctly.
(4) a.k.a. K&R C, or Kernighan & Ritchie C
File: ccmode, Node: Indentation Functions, Next: Performance Issues, Prev: Syntactic Symbols, Up: Top
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.
File: ccmode, Node: Performance Issues, Next: Limitations and Known Bugs, Prev: Indentation Functions, Up: Top
Performance Issues
******************
C and its derivative languages are highly complex creatures. Often,
ambiguous code situations arise that require CC Mode to scan large
portions of the buffer to determine syntactic context. Such
pathological code(1) can cause CC Mode to perform fairly badly. This
section identifies some of the coding styles to watch out for, and
suggests some workarounds that you can use to improve performance.
Because CC Mode has to scan the buffer backwards from the current
insertion point, and because C's syntax is fairly difficult to parse in
the backwards direction, CC Mode often tries to find the nearest
position higher up in the buffer from which to begin a forward scan.
The farther this position is from the current insertion point, the
slower the mode gets. Some coding styles can even force CC Mode to
scan from the beginning of the buffer for every line of code!
One of the simplest things you can do to reduce scan time, is make
sure any brace that opens a top-level construct(2) always appears in the
leftmost column. This is actually an Emacs constraint, as embodied in
the `beginning-of-defun' function which CC Mode uses heavily. If you
insist on hanging top-level open braces on the right side of the line,
then you might want to set the variable `defun-prompt-regexp' to
something reasonable, however that "something reasonable" is difficult
to define, so CC Mode doesn't do it for you.
A special note about `defun-prompt-regexp' in Java mode: while much
of the early sample Java code seems to encourage a style where the brace
that opens a class is hung on the right side of the line, this is not a
good style to pursue in Emacs. CC Mode comes with a variable
`c-Java-defun-prompt-regexp' which tries to define a regular expression
usable for this style, but there are problems with it. In some cases
it can cause `beginning-of-defun' to hang(3). For this reason, it is
not used by default, but if you feel adventurous, you can set
`defun-prompt-regexp' to it in your mode hook. In any event, setting
and rely on `defun-prompt-regexp' will definitely slow things down
anyway because you'll be doing regular expression searches for every
line you indent, so you're probably screwed either way!
Another alternative for XEmacs users, is to set the variable
`c-enable-xemacs-performance-kludge-p' to non-`nil'. This tells CC
Mode to use XEmacs-specific built-in functions which, in some
circumstances, can locate the top-most opening brace much quicker than
`beginning-of-defun'. Preliminary testing has shown that for styles
where these braces are hung (e.g. most JDK-derived Java styles), this
hack can improve performance of the core syntax parsing routines from 3
to 60 times. However, for styles which _do_ conform to Emacs'
recommended style of putting top-level braces in column zero, this hack
can degrade performance by about as much. Thus this variable is set to
`nil' by default, since the Emacs-friendly styles should be more common
(and encouraged!). Note that this variable has no effect in Emacs
since the necessary built-in functions don't exist (in Emacs 20.2 or
20.3 as of this writing 27-Apr-1998).
You will probably notice pathological behavior from CC Mode when
working in files containing large amounts of C preprocessor macros.
This is because Emacs cannot skip backwards over these lines as quickly
as it can comments.
Previous versions of CC Mode had potential performance problems when
recognizing K&R style function argument declarations. This was because
there are ambiguities in the C syntax when K&R style argument lists are
used(4). CC Mode has adopted BOCM's convention for limiting the
search: it assumes that argdecls are indented at least one space, and
that the function headers are not indented at all. With current
versions of CC Mode, user customization of `c-recognize-knr-p' is
deprecated. Just don't put argdecls in column zero!
You might want to investigate the speed-ups contained in the file
`cc-lobotomy.el', which comes as part of the CC Mode distribution, but
is completely unsupported. As mentioned previous, CC Mode always
trades speed for accuracy, however it is recognized that sometimes you
need speed and can sacrifice some accuracy in indentation. The file
`cc-lobotomy.el' contains hacks that will "dumb down" CC Mode in some
specific ways, making that trade-off of accurancy for speed. I won't
go into details of its use here; you should read the comments at the
top of the file, and look at the variable `cc-lobotomy-pith-list' for
details.
---------- Footnotes ----------
(1) such as the output of `lex(1)'!
(2) E.g. a function in C, or outermost class definition in C++ or
Java.
(3) This has been observed in Emacs 19.34 and XEmacs 19.15.
(4) It is hard to distinguish them from top-level declarations.
File: ccmode, Node: Limitations and Known Bugs, Next: Frequently Asked Questions, Prev: Performance Issues, Up: Top
Limitations and Known Bugs
**************************
* Re-indenting large regions or expressions can be slow.
* `c-indent-exp' has not been fully optimized. It essentially
equivalent to hitting `TAB' (`c-indent-command') on every line.
Some information is cached from line to line, but such caching
invariable causes inaccuracies in analysis in some bizarre
situations.
* XEmacs versions from 19.15 until (as of this writing 12-Mar-1998)
20.4 contain a variable called `signal-error-on-buffer-boundary'.
This was intended as a solution to user interface problems
associated with buffer movement and the `zmacs-region'
deactivation on errors. However, setting this variable to a
non-default value had the deleterious side effect of breaking many
built-in primitive functions. Most users will not be affected
since they never change the value of this variable. *Do not set
this variable to `nil'*; you will cause serious problems in CC
Mode and probably other XEmacs packages! As of at least XEmacs
20.4, the effects this variable tried to correct have been fixed
in other, better ways.
File: ccmode, Node: Frequently Asked Questions, Next: Getting the Latest CC Mode Release, Prev: Limitations and Known Bugs, Up: Top
Frequently Asked Questions
**************************
*Q.* _How do I re-indent the whole file?_
*A.* Visit the file and hit `C-x h' to mark the whole buffer. Then
hit `C-M-\'.
*Q.* _How do I re-indent the entire function? `C-M-x' doesn't
work._
*A.* `C-M-x' is reserved for future Emacs use. To re-indent the
entire function hit `C-c C-q'.
*Q.* _How do I re-indent the current block?_
*A.* First move to the brace which opens the block with `C-M-u',
then re-indent that expression with `C-M-q'.
*Q.* _Why doesn't the `RET' key indent the new line?_
*A.* Emacs' convention is that `RET' just adds a newline, and that
`C-j' adds a newline and indents it. You can make `RET' do this
too by adding this to your `c-mode-common-hook':
(define-key c-mode-base-map "\C-m" 'c-context-line-break)
This is a very common question. If you want this to be the default
behavior, don't lobby me, lobby RMS! :-)
*Q.* _I put `(c-set-offset 'substatement-open 0)' in my `.emacs'
file but I get an error saying that `c-set-offset''s function
definition is void._
*A.* This means that CC Mode wasn't loaded into your Emacs session
by the time the `c-set-offset' call was reached, most likely
because CC Mode is being autoloaded. Instead of putting the
`c-set-offset' line in your top-level `.emacs' file, put it in
your `c-mode-common-hook', or simply modify `c-offsets-alist'
directly:
(setq c-offsets-alist '((substatement-open . 0)))
*Q.* _How do I make strings, comments, keywords, and other
constructs appear in different colors, or in bold face, etc.?_
*A.* "Syntax Colorization" is a standard Emacs feature, controlled
by `font-lock-mode'. CC Mode does not contain font-lock
definitions for any of its supported languages.
*Q.* _`M-a' and `M-e' used to move over entire balanced brace
lists, but now they move into blocks. How do I get the old
behavior back?_
*A.* Use `C-M-f' and `C-M-b' to move over balanced brace blocks.
Use `M-a' and `M-e' to move by statements, which will also move
into blocks.
*Q.* _Whenever I try to indent a line or type an "electric" key
such as `;', `{', or `}', I get an error that look like this:
`Invalid function: (macro . #[...'. What gives?_
*A.* This is a common error when CC Mode hasn't been compiled
correctly, especially under Emacs 19.34(1). If you are using the
standalone CC Mode distribution, try recompiling it according to
the instructions in the `README' file.
---------- Footnotes ----------
(1) Technically, it's because some macros wasn't defined during the
compilation, so the byte compiler put in function calls instead of the
macro expansions. Later, when the interpreter tries to call the macros
as functions, it shows this (somewhat cryptic) error message.
File: ccmode, Node: Getting the Latest CC Mode Release, Next: Mailing Lists and Submitting Bug Reports, Prev: Frequently Asked Questions, Up: Top
Getting the Latest CC Mode Release
**********************************
CC Mode is standard with all versions of Emacs since 19.34 and of
XEmacs since 19.16.
Due to release schedule skew, it is likely that all of these Emacsen
have old versions of CC Mode and so should be upgraded. Access to the
CC Mode source code, as well as more detailed information on Emacsen
compatibility, etc. are all available via the Web at:
`http://cc-mode.sourceforge.net/'
_Old URLs, including the FTP URLs, should no longer be used._
There are many files under these directories; you can pick up the
entire distribution (named `cc-mode.tar.gz'; a gzip'd tar file), or any
of the individual files, including PostScript documentation.
File: ccmode, Node: Mailing Lists and Submitting Bug Reports, Next: Sample .emacs File, Prev: Getting the Latest CC Mode Release, Up: Top
Mailing Lists and Submitting Bug Reports
****************************************
To report bugs, use the `C-c C-b' (`c-submit-bug-report') command.
This provides vital information we need to reproduce your problem.
Make sure you include a concise, but complete code example. Please try
to boil your example down to just the essential code needed to
reproduce the problem, and include an exact recipe of steps needed to
expose the bug. Be especially sure to include any code that appears
_before_ your bug example, if you think it might affect our ability to
reproduce it.
Please try to produce the problem in an Emacs instance without any
customizations loaded (i.e. start it with the `-q -no-site-file'
arguments). If it works correctly there, the problem might be caused by
faulty customizations in either your own or your site configuration. In
that case, we'd appreciate if you isolate the Emacs Lisp code that trigs
the bug and include it in your report.
Bug reports are now sent to the following email addresses:
<bug-cc-mode@gnu.org> and <bug-gnu-emacs@gnu.org>; the latter is
mirrored on the Usenet newsgroup `gnu.emacs.bug'. You can send other
questions and suggestions (kudos? ;-) to <bug-cc-mode@gnu.org>.
If you want to get announcements of new CC Mode releases, send the
word _subscribe_ in the body of a message to
<cc-mode-announce-request@lists.sourceforge.net>. Announcements will
also be posted to the Usenet newsgroups `gnu.emacs.sources',
`comp.emacs' and `comp.emacs.xemacs'.