@comment Info directory entry for use by install-info. The indentation
@comment here is by request from the FSF folks.
-@dircategory Emacs
+@dircategory Emacs editing modes
@direntry
* CC Mode: (ccmode). Emacs mode for editing C, C++, Objective-C,
Java, Pike, AWK, and CORBA IDL code.
* Built-in Styles::
* Choosing a Style::
* Adding Styles::
+* Guessing the Style::
* File Styles::
Customizing Auto-newlines
Syntactic Symbols
-* Function Symbols::
-* Class Symbols::
-* Conditional Construct Symbols::
-* Switch Statement Symbols::
-* Brace List Symbols::
-* External Scope Symbols::
-* Paren List Symbols::
-* Literal Symbols::
-* Multiline Macro Symbols::
-* Objective-C Method Symbols::
+* Function Symbols::
+* Class Symbols::
+* Conditional Construct Symbols::
+* Switch Statement Symbols::
+* Brace List Symbols::
+* External Scope Symbols::
+* Paren List Symbols::
+* Literal Symbols::
+* Multiline Macro Symbols::
+* Objective-C Method Symbols::
* Java Symbols::
-* Statement Block Symbols::
-* K&R Symbols::
+* Statement Block Symbols::
+* K&R Symbols::
Customizing Indentation
* Comment Line-Up::
* Misc Line-Up::
+Customizing Macros
+
+* Macro Backslashes::
+* Macros with ;::
+
@end detailmenu
@end menu
syntactic recognition can be wrong. @ccmode{} manages to figure it
out correctly most of the time, though.
+Some macros, when invoked, ''have their own semicolon''. To get the
+next line indented correctly, rather than as a continuation line,
+@xref{Macros with ;}.
+
Reindenting large sections of code can take a long time. When
@ccmode{} reindents a region of code, it is essentially equivalent to
hitting @key{TAB} on every line of the region.
@itemx @kbd{C-M-e} (@code{c-end-of-defun})
@findex c-beginning-of-defun
@findex c-end-of-defun
+@vindex c-defun-tactic
+@vindex defun-tactic (c-)
Move to the beginning or end of the current or next function. Other
constructs (such as a structs or classes) which have a brace block
start or end of the function. This occasionally causes point not to
move at all.
+By default, these commands will recognize functions contained within a
+@dfn{declaration scope} such as a C++ @code{class} or @code{namespace}
+construct, should the point start inside it. If @ccmode fails to find
+function beginnings or ends inside the current declaration scope, it
+will search the enclosing scopes. If you want @ccmode to recognize
+functions only at the top level@footnote{this was @ccmode{}'s
+behavior prior to version 5.32.}, set @code{c-defun-tactic} to
+@code{t}.
+
These functions are analogous to the Emacs built-in commands
@code{beginning-of-defun} and @code{end-of-defun}, except they
eliminate the constraint that the top-level opening brace of the defun
and @ref{Indentation Engine Basics}.
You can toggle each of these minor modes on and off, and you can
-configure @ccmode{} so that it starts up with your favourite
+configure @ccmode{} so that it starts up with your favorite
combination of them (@pxref{Sample .emacs File}). By default, when
you initialize a buffer, electric mode and syntactic-indentation mode
are enabled but the other two modes are disabled.
a user function. The last character of the function name and the
opening parenthesis are highlighted. This font-locking rule will
spuriously highlight a valid concatenation expression where an
-identifier precedes a parenthesised expression. Unfortunately.
+identifier precedes a parenthesized expression. Unfortunately.
@item
Whitespace following the @samp{\} in what otherwise looks like an
for any particular style, and pretty easily start editing new or
existing code using these styles.
+As an alternative to writing a style definition yourself, you can have
+@ccmode{} @dfn{guess} (at least part of) your style by looking at an
+already formatted piece of your code, @ref{Guessing the Style}.
+
@menu
* Built-in Styles::
* Choosing a Style::
* Adding Styles::
+* Guessing the Style::
* File Styles::
@end menu
-
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@node Built-in Styles, Choosing a Style, Styles, Styles
@comment node-name, next, previous, up
string.
@end defvar
-
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@node Adding Styles, File Styles, Choosing a Style, Styles
+@node Adding Styles, Guessing the Style, Choosing a Style, Styles
@comment node-name, next, previous, up
@subsection Adding and Amending Styles
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
should not be changed directly; use @code{c-add-style} instead.
@end defvar
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Guessing the Style, File Styles, Adding Styles, Styles
+@comment node-name, next, previous, up
+@subsection Guessing the Style
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+Instead of specifying a style, you can get @ccmode{} to @dfn{guess}
+your style by examining an already formatted code buffer. @ccmode{}
+then determines the ''most frequent'' offset (@pxref{c-offsets-alist})
+for each of the syntactic symbols (@pxref{Indentation Engine Basics})
+encountered in the buffer, and the ''most frequent'' value of
+c-basic-offset (@pxref{Customizing Indentation}), then merges the
+current style with these ''guesses'' to form a new style. This
+combined style is known as the @dfn{guessed style}.
+
+To do this, call @code{c-guess} (or one of the other 5 guessing
+commands) on your sample buffer. The analysis of your code may take
+some time.
+
+You can then set the guessed style in any @ccmode{} buffer with
+@code{c-guess-install}. You can display the style with
+@code{c-guess-view}, and preserve it by copying it into your
+@file{.emacs} for future use, preferably after editing it.
+
+@table @asis
+@item @kbd{M-x c-guess-no-install}
+@itemx @kbd{M-x c-guess-buffer-no-install}
+@itemx @kbd{M-x c-guess-region-no-install}
+@findex c-guess-no-install
+@findex c-guess-buffer-no-install
+@findex c-guess-region-no-install
+@findex guess-no-install (c-)
+@findex guess-buffer-no-install (c-)
+@findex guess-region-no-install (c-)
+These commands analyze a part of the current buffer and guess the
+style from it.
+
+The part of the buffer examined is either the region
+(@code{c-guess-region-no-install}), the entire buffer
+(@code{c-guess-buffer-no-install}), or the first
+@code{c-guess-region-max} bytes (@code{c-guess-no-install}).
+
+Each of these commands can be given an optional prefix argument. This
+instructs @ccmode{} to combine the new guesses with the current
+guesses before forming the guessed style.
+@end table
+
+@table @asis
+@item @kbd{M-x c-guess}
+@itemx @kbd{M-x c-guess-buffer}
+@itemx @kbd{M-x c-guess-region}
+@findex c-guess
+@findex c-guess-buffer
+@findex c-guess-region
+@findex guess (c-)
+@findex guess-buffer (c-)
+@findex guess-region (c-)
+These commands analyze a part of the current buffer, guess the style
+from it, then install the guessed style on the buffer. The guessed
+style is given a name based on the buffer's absolute file name, and
+you can then set this style on any @ccmode{} buffer with @kbd{C-c .}.
+
+The part of the buffer examined is either the region
+(@code{c-guess-region}), the entire buffer (@code{c-guess-buffer}), or
+the first @code{c-guess-region-max} bytes (@code{c-guess}).
+
+Each of these commands can be given an optional prefix argument. This
+instructs @ccmode{} to combine the new guesses with the current
+guesses before forming the guessed style.
+@end table
+
+@defopt c-guess-region-max
+@vindex guess-region-max (c-)
+This variable, default 50000, is the size in bytes of the buffer
+portion examined by c-guess and c-guess-no-install. If set to
+@code{nil}, the entire buffer is examined.
+@end defopt
+
+@defopt c-guess-offset-threshold
+@vindex guess-offset-threshold (c-)
+This variable, default 10, is the maximum offset, either outwards or
+inwards, which will be taken into account by the analysis process.
+Any offset bigger than this will be ignored. For no limit, set this
+variable to a large number.
+@end defopt
+
+@table @asis
+@item @kbd{M-x c-guess-install}
+@findex c-guess-install
+@findex guess-install (c-)
+
+Set the current buffer's style to the guessed style. This prompts you
+to enter an optional new style name to give to the guessed style. By
+default, this name is based on the buffer's absolute file name. You
+can then use this style like any other.
+
+@item @kbd{M-x c-guess-view}
+@findex c-guess-view
+@findex guess-view (c-)
+Display the most recently guessed style in a temporary buffer. This
+display is in the form of a @code{c-add-style} form (@pxref{Adding
+Styles}) which can be easily copied to your @file{.emacs}. You will
+probably want to edit it first.
+
+The display of the guessed style contains these elements:
+
+@table @asis
+@item Placeholder Name
+You should replace this with a style name of your own.
+@item Parent Style
+The style current when the guessing began, from which the guessed
+style inherits (@pxref{Config Basics}) the settings which weren't
+guessed.
+@item Guessed Offsets
+These are the core result of the guessing process. Each of them is
+marked by a comment.
+@item Inherited Offsets
+These are syntactic offsets which have been taken over from the parent
+style. To avoid possible future conflicts, you should remove either
+these offsets or the parent style name.
+@end table
+@end table
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-@node File Styles, , Adding Styles, Styles
+@node File Styles, , Guessing the Style, Styles
@comment node-name, next, previous, up
@subsection File Styles
@cindex styles, file local
@end table
@menu
-* Function Symbols::
-* Class Symbols::
-* Conditional Construct Symbols::
-* Switch Statement Symbols::
-* Brace List Symbols::
-* External Scope Symbols::
-* Paren List Symbols::
-* Literal Symbols::
-* Multiline Macro Symbols::
-* Objective-C Method Symbols::
+* Function Symbols::
+* Class Symbols::
+* Conditional Construct Symbols::
+* Switch Statement Symbols::
+* Brace List Symbols::
+* External Scope Symbols::
+* Paren List Symbols::
+* Literal Symbols::
+* Multiline Macro Symbols::
+* Objective-C Method Symbols::
* Java Symbols::
-* Statement Block Symbols::
-* K&R Symbols::
+* Statement Block Symbols::
+* K&R Symbols::
@end menu
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@section Other Special Indentations
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+To configure macros which you invoke without a terminating @samp{;},
+see @xref{Macros with ;}.
+
Here are the remaining odds and ends regarding indentation:
@defopt c-label-minimum-indentation
@cindex preprocessor directives
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+Preprocessor macros in C, C++, and Objective C (introduced by
+@code{#define}) have a syntax different from the main language---for
+example, a macro declaration is not terminated by a semicolon, and if
+it is more than a line long, line breaks in it must be escaped with
+backslashes. @ccmode{} has some commands to manipulate these, see
+@ref{Macro Backslashes}.
+
Normally, the lines in a multi-line macro are indented relative to
each other as though they were code. You can suppress this behavior
by setting the following user option:
@code{cpp-macro-cont}.
@end defopt
+Because a macro can expand into anything at all, near where one is
+invoked @ccmode{} can only indent and fontify code heuristically.
+Sometimes it gets it wrong. Usually you should try to design your
+macros so that they ''look like ordinary code'' when you invoke them.
+However, one situation is so common that @ccmode{} handles it
+specially: that is when certain macros needn't (or mustn't) be
+followed by a @samp{;}. You need to configure @ccmode{} to handle
+these macros properly, see @ref{Macros with ;}.
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@menu
+* Macro Backslashes::
+* Macros with ;::
+@end menu
+
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Macro Backslashes, Macros with ;, Custom Macros, Custom Macros
+@comment node-name, next, previous, up
+@section Customizing Macro Backslashes
+@cindex #define
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
@ccmode{} provides some tools to help keep the line continuation
backslashes in macros neat and tidy. Their precise action is
customized with these variables:
@code{c-backslash-region} (@kbd{C-c C-\}).
@end defopt
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+@node Macros with ;, , Macro Backslashes, Custom Macros
+@comment node-name, next, previous, up
+@section Macros with semicolons
+@cindex macros with semicolons
+@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+Macros which needn't (or mustn't) be followed by a semicolon when you
+invoke them, @dfn{macros with semicolons}, are very common. These can
+cause @ccmode{} to parse the next line wrongly as a
+@code{statement-cont} (@pxref{Function Symbols}) and thus mis-indent
+it.
+
+You can prevent this by specifying which macros have semicolons. It
+doesn't matter whether or not such a macro has a parameter list:
+
+@defopt c-macro-names-with-semicolon
+@vindex macro-names-with-semicolon (c-)
+This buffer-local variable specifies which macros have semicolons.
+After setting its value, you need to call
+@code{c-make-macro-with-semi-re} for it to take effect. It should be
+set to one of these values:
+
+@table @asis
+@item nil
+There are no macros with semicolons.
+@item a list of strings
+Each string is the name of a macro with a semicolon. Only valid
+@code{#define} names are allowed here. For example, to set the
+default value, you could write the following into your @file{.emacs}:
+
+@example
+(setq c-macro-names-with-semicolon
+ '("Q_OBJECT" "Q_PROPERTY" "Q_DECLARE" "Q_ENUMS"))
+@end example
+
+@item a regular expression
+This matches each symbol which is a macro with a semicolon. It must
+not match any string which isn't a valid @code{#define} name. For
+example:
+
+@example
+(setq c-macro-names-with-semicolon
+ "\\<\\(CLEAN_UP_AND_RETURN\\|Q_[[:upper:]]+\\)\\>")
+@end example
+@end table
+@end defopt
+
+@defun c-make-macro-with-semi-re
+@findex make-macro-with-semi-re (c-)
+Call this (non-interactive) function, which sets internal variables,
+each time you change the value of
+@code{c-macro-names-with-semicolon}. It takes no arguments, and its
+return value has no meaning. This function is called by @ccmode{}'s
+initialization code.
+@end defun
+
@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@node Odds and Ends, Sample .emacs File, Custom Macros, Top
@comment node-name, next, previous, up
HCoop / bpt / emacs.git / blobdiff