X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/0f74f7850de124626d556442d22d143d85457816..21fa24820007018632b3719ac6855eef6b688852:/doc/misc/cc-mode.texi diff --git a/doc/misc/cc-mode.texi b/doc/misc/cc-mode.texi index a933916266..8c574be8f2 100644 --- a/doc/misc/cc-mode.texi +++ b/doc/misc/cc-mode.texi @@ -147,10 +147,7 @@ CC Mode @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @comment Define an index for syntactic symbols. -@ifnottex @c In texi2dvi, the @defindex would create an empty cc-mode.ss - @c For Info, unlike tex, @syncodeindex needs a matching @defindex. @defindex ss -@end ifnottex @comment Combine key, syntactic symbol and concept indices into one. @syncodeindex ss cp @@ -159,7 +156,7 @@ CC Mode @copying This manual is for CC Mode in Emacs. -Copyright @copyright{} 1995-2011 Free Software Foundation, Inc. +Copyright @copyright{} 1995-2012 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -190,7 +187,7 @@ developing GNU and promoting software freedom.'' @titlepage @sp 10 -@center @titlefont{CC Mode 5.31} +@center @titlefont{CC Mode 5.32} @sp 2 @center @subtitlefont{A GNU Emacs mode for editing C and C-like languages} @sp 2 @@ -287,11 +284,11 @@ Configuration Basics Styles -* Built-in Styles:: -* Choosing a Style:: -* Adding Styles:: -* Guessing the Style:: -* File Styles:: +* Built-in Styles:: +* Choosing a Style:: +* Adding Styles:: +* Guessing the Style:: +* File Styles:: Customizing Auto-newlines @@ -311,19 +308,19 @@ Indentation Engine Basics 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 @@ -341,6 +338,11 @@ Line-Up Functions * Comment Line-Up:: * Misc Line-Up:: +Customizing Macros + +* Macro Backslashes:: +* Macros with ;:: + @end detailmenu @end menu @@ -373,7 +375,7 @@ was added in version 5.30. This manual describes @ccmode{} @comment The following line must appear on its own, so that the -version 5.31. +version 5.32. @comment Release.py script can update the version number automatically @ccmode{} supports the editing of K&R and ANSI C, C++, Objective-C, @@ -655,6 +657,10 @@ expression, to some statements, or perhaps to whole functions, the 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. @@ -695,7 +701,7 @@ in some circumstances---@code{c-insert-tab-function} then defines precisely what sort of ``whitespace'' this will be. Set the standard Emacs variable @code{indent-tabs-mode} to @code{t} if you want real @samp{tab} characters to be used in the indentation, to @code{nil} if -you want only spaces. @xref{Just Spaces,,, @emacsman{}, +you want only spaces. @xref{Just Spaces,,,@emacsman{}, @emacsmantitle{}}. @defopt c-tab-always-indent @@ -882,6 +888,8 @@ lines. @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 @@ -895,6 +903,15 @@ commands try to leave point at the beginning of a line near the actual 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 @@ -1041,8 +1058,8 @@ set this up for you, so you probably won't have to bother. @cindex Auto Fill mode @cindex paragraph filling Line breaks are by default handled (almost) the same regardless of -whether they are made by auto fill mode (@pxref{Auto Fill,,, -@emacsman{}, @emacsmantitle{}}), by paragraph filling (e.g. with +whether they are made by auto fill mode (@pxref{Auto +Fill,,,@emacsman{}, @emacsmantitle{}}), by paragraph filling (e.g. with @kbd{M-q}), or explicitly with @kbd{M-j} or similar methods. In string literals, the new line gets the same indentation as the previous nonempty line.@footnote{You can change this default by @@ -1153,7 +1170,7 @@ Full details on how these minor modes work are at @ref{Electric Keys}, 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. @@ -1385,7 +1402,7 @@ continuation of the preceding @code{if}. @vindex abbrev-mode @findex abbrev-mode @cindex Abbrev mode -@ccmode{} uses Abbrev mode (@pxref{Abbrevs,,, @emacsman{}, @emacsmantitle{}}) +@ccmode{} uses Abbrev mode (@pxref{Abbrevs,,,@emacsman{}, @emacsmantitle{}}) to accomplish this. It's therefore turned on by default in all language modes except IDL mode, since CORBA IDL doesn't have any statements. @end deffn @@ -2140,7 +2157,7 @@ A space between the function name and opening parenthesis when calling 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 @@ -2180,7 +2197,7 @@ method, ``Top-level commands or the customization interface''. If you make conflicting settings in several of these ways, the way that takes precedence is the one that appears latest in this list: -@itemize @asis +@itemize @w{} @item @table @asis @item Style @@ -2278,14 +2295,14 @@ to create them. A @dfn{file local variable setting} is a setting which applies to an individual source file. You put this in a @dfn{local variables list}, a special block at the end of the source file (@pxref{Specifying File -Variables,,, @emacsman{}}). +Variables,,,@emacsman{}}). @item File Styles A @dfn{file style} is a rarely used variant of the ``style'' mechanism described above, which applies to an individual source file. @xref{File Styles}. You use this by setting certain special variables -in a local variables list (@pxref{Specifying File Variables,,, -@emacsman{}}). +in a local variables list (@pxref{Specifying File +Variables,,,@emacsman{}}). @item Hooks with Styles For ultimate flexibility, you can use hooks and styles together. For @@ -2517,11 +2534,11 @@ As an alternative to writing a style definition yourself, you can have already formatted piece of your code, @ref{Guessing the Style}. @menu -* Built-in Styles:: -* Choosing a Style:: -* Adding Styles:: -* Guessing the Style:: -* File Styles:: +* Built-in Styles:: +* Choosing a Style:: +* Adding Styles:: +* Guessing the Style:: +* File Styles:: @end menu @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @@ -2880,7 +2897,7 @@ these offsets or the parent style name. The Emacs manual describes how you can customize certain variables on a per-file basis by including a @dfn{file local variable} block at the end -of the file (@pxref{File Variables,, Local Variables in Files, @emacsman{}, +of the file (@pxref{File Variables,, Local Variables in Files,@emacsman{}, @emacsmantitle{}}). So far, you've only seen a functional interface for setting styles in @@ -3122,8 +3139,9 @@ results in the current implementation. @end defopt @vindex comment-multi-line -If inside a comment and @code{comment-multi-line} (@pxref{Auto Fill,,, -@emacsman{}, @emacsmantitle{}} is non-@code{nil}, the indentation and +If inside a comment and @code{comment-multi-line} (@pxref{Auto +Fill,,,@emacsman{}, @emacsmantitle{}} is non-@code{nil}, the +indentation and line prefix are preserved. If inside a comment and @code{comment-multi-line} is @code{nil}, a new comment of the same type is started on the next line and indented as appropriate for @@ -4246,19 +4264,19 @@ Java. @ref{Java Symbols}. @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 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @@ -5178,7 +5196,7 @@ indentation. @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! This section explains the structure and semantics of the style -variable @code{c-offset-alist}, the principal variable for configuring +variable @code{c-offsets-alist}, the principal variable for configuring indentation. Details of how to set it up, and its relationship to @ccmode{}'s style system are given in @ref{Style Variables}. @@ -6550,6 +6568,9 @@ custom line-up function associated with it. @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 @@ -6601,6 +6622,13 @@ functions to this hook, not remove them. @xref{Style Variables}. @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: @@ -6612,6 +6640,28 @@ is @code{nil}, all lines inside macro definitions are analyzed as @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 @code{#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: @@ -6653,6 +6703,62 @@ get aligned only when you explicitly invoke the command @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 @@ -6666,7 +6772,7 @@ The stuff that didn't fit in anywhere else is documented here. Controls whether a final newline is enforced when the file is saved. The value is an association list that for each language mode specifies the value to give to @code{require-final-newline} (@pxref{Saving -Buffers,,, @lispref{}, @lispreftitle{}}) at mode initialization. If a +Buffers,,,@lispref{}, @lispreftitle{}}) at mode initialization. If a language isn't present on the association list, CC Mode won't touch @code{require-final-newline} in buffers for that language. @@ -6837,7 +6943,7 @@ circumstances, can locate the top-most opening brace much more quickly than 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 @emph{do} conform to -Emacs' recommended style of putting top-level braces in column zero, +Emacs's 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 @code{nil} by default, since the Emacs-friendly styles should be more common (and encouraged!). Note that this variable has no effect @@ -6948,7 +7054,7 @@ Set the variable @code{c-basic-offset}. @xref{Getting Started}. @kindex C-j @emph{Why doesn't the @kbd{RET} key indent the new line?} -Emacs' convention is that @kbd{RET} just adds a newline, and that +Emacs's convention is that @kbd{RET} just adds a newline, and that @kbd{C-j} adds a newline and indents it. You can make @kbd{RET} do this too by adding this to your @code{c-initialization-hook}: