X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/6bf7aab68402fd010eae5d280350bd399014406a..cb4e834e318ccf05d5716180b81f9e1edc364e59:/man/cc-mode.texi diff --git a/man/cc-mode.texi b/man/cc-mode.texi index c515e28c7b..05b7df18b4 100644 --- a/man/cc-mode.texi +++ b/man/cc-mode.texi @@ -1,18 +1,129 @@ \input texinfo +@c Notes to self regarding line handling: +@c +@c Empty lines are often significant before @end directives; avoid them. +@c +@c Empty lines before and after @example directives are significant in +@c info output but not in TeX. Empty lines inside @example directives +@c are significant. + +@c Conventions for formatting examples: +@c o If the example contains empty lines then put the surrounding empty +@c lines inside the @example directives. Put them outside otherwise. +@c o Use @group inside the example only if it shows indentation where +@c the relation between lines inside is relevant. +@c o Format line number columns like this: +@c 1: foo +@c 2: bar +@c ^ one space +@c ^^ two columns, right alignment +@c o Check line lengths in TeX output; they can typically be no longer +@c than 70 chars, 60 if the paragraph is indented. + +@comment TBD: Document the finer details of statement anchoring? @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @comment %**start of header (This is for running Texinfo on a region) @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@comment How to make the various output formats: +@comment (Thanks to Robert Chassell for supplying this information.) +@comment Note that Texinfo 4.7 (or later) is needed. +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@ignore +In each of the following pairs of commands, the first generates a +version with cross references pointing to the GNU Emacs manuals, +the second with them pointing to the XEmacs manuals. + ## Info output + makeinfo cc-mode.texi + makeinfo -DXEMACS cc-mode.texi + + ## DVI output + ## You may need to set up the environment variable TEXINPUTS so + ## that tex can find the file texinfo.tex - See the tex + ## manpage. + texi2dvi cc-mode.texi + texi2dvi -t "@set XEMACS " cc-mode.texi + + ## HTML output. (The --no-split parameter is optional) + makeinfo --html --no-split cc-mode.texi + makeinfo --html --no-split -DXEMACS cc-mode.texi + + ## Plain text output + makeinfo --fill-column=70 --no-split --paragraph-indent=0 \ + --no-headers --output=cc-mode.txt cc-mode.texi + makeinfo --fill-column=70 --no-split --paragraph-indent=0 \ + --no-headers --output=cc-mode.txt -DXEMACS cc-mode.texi + + ## DocBook output + makeinfo --docbook --no-split --paragraph-indent=0 \ + cc-mode.texi + makeinfo --docbook --no-split --paragraph-indent=0 \ + -DXEMACS cc-mode.texi + + ## XML output + makeinfo --xml --no-split --paragraph-indent=0 \ + cc-mode.texi + makeinfo --xml --no-split --paragraph-indent=0 \ + -DXEMACS cc-mode.texi + + #### (You must be in the same directory as the viewed file.) + + ## View DVI output + xdvi cc-mode.dvi & + + ## View HTML output + mozilla cc-mode.html +@end ignore + +@comment No overfull hbox marks in the dvi file. +@finalout + @setfilename ../info/ccmode -@settitle CC MODE Version 5 Documentation +@settitle CC Mode Manual @footnotestyle end -@dircategory Editors -@direntry -* CC mode: (ccmode). The GNU Emacs mode for editing C, C++, Objective-C - and Java code. -@end direntry +@c The following four macros generate the filenames and titles of the +@c main (X)Emacs manual and the Elisp/Lispref manual. Leave the +@c Texinfo variable `XEMACS' unset to generate a GNU Emacs version, set it +@c to generate an XEmacs version, e.g. with +@c "makeinfo -DXEMACS cc-mode.texi". +@ifset XEMACS +@macro emacsman +xemacs +@end macro +@macro emacsmantitle +XEmacs User's Manual +@end macro +@macro lispref +lispref +@end macro +@macro lispreftitle +XEmacs Lisp Reference Manual +@end macro +@end ifset + +@ifclear XEMACS +@macro emacsman +emacs +@end macro +@macro emacsmantitle +GNU Emacs Manual +@end macro +@macro lispref +elisp +@end macro +@macro lispreftitle +GNU Emacs Lisp Reference Manual +@end macro +@end ifclear + + +@macro ccmode +CC Mode +@end macro @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @comment @setchapternewpage odd !! we don't want blank pages !! @@ -21,2205 +132,3139 @@ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@comment +@comment @comment Texinfo manual for CC Mode @comment Generated from the original README file by Krishna Padmasola @comment -@comment -@comment Maintained by Barry A. Warsaw -@comment +@comment +@comment Authors: +@comment Barry A. Warsaw +@comment Martin Stjernholm +@comment Alan Mackenzie +@comment +@comment Maintained by Martin Stjernholm and Alan Mackenzie +@comment @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 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@comment The following line inserts the copyright notice -@comment into the Info file. -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@comment Combine key, syntactic symbol and concept indices into one. +@syncodeindex ss cp +@syncodeindex ky cp -@ifinfo -Copyright @copyright{} 1995,96,97,98 Free Software Foundation, Inc. -@end ifinfo +@copying +This manual is for CC Mode in Emacs. -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@comment !!!The titlepage section does not appear in the Info file.!!! -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +Copyright @copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, +2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@titlepage -@sp 10 +@quotation +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.2 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. +@end quotation +@end copying +@comment Info directory entry for use by install-info. The indentation +@comment here is by request from the FSF folks. +@dircategory Emacs +@direntry +* CC Mode: (ccmode). Emacs mode for editing C, C++, Objective-C, + Java, Pike, AWK, and CORBA IDL code. +@end direntry @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@comment The title is printed in a large font. +@comment TeX title page @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@center @titlefont{CC Mode 5.21} +@titlepage +@sp 10 + +@center @titlefont{CC Mode 5.31} @sp 2 @center @subtitlefont{A GNU Emacs mode for editing C and C-like languages} @sp 2 -@center Barry A. Warsaw - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@comment The following two commands start the copyright page -@comment for the printed manual. This will not appear in the Info file. -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@center Barry A. Warsaw, Martin Stjernholm, Alan Mackenzie @page @vskip 0pt plus 1filll -Copyright @copyright{} 1995,96,97,98 Free Software Foundation, Inc. -@end titlepage +@insertcopying +This manual was generated from $Revision$ of $RCSfile$, which can be +downloaded from +@url{http://cvs.savannah.gnu.org/viewcvs/emacs/emacs/man/cc-mode.texi}. +@end titlepage @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @comment The Top node contains the master menu for the Info file. @comment This appears only in the Info file, not the printed manual. @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Top, Introduction, (dir), (dir) -@comment node-name, next, previous, up +@node Top, Introduction, (dir), (dir) +@comment node-name, next, previous, up +@ifinfo +@top @ccmode{} + +@ccmode{} is a GNU Emacs mode for editing files containing C, C++, +Objective-C, Java, CORBA IDL (and the variants PSDL and CIDL), Pike +and AWK code. It provides syntax-based indentation, font locking, and +has several handy commands and some minor modes to make the editing +easier. It does not provide tools to look up and navigate between +functions, classes etc - there are other packages for that. +@end ifinfo @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @menu * Introduction:: -* Getting Connected:: -* New Indentation Engine:: -* Minor Modes:: -* Commands:: -* Customizing Indentation:: -* Syntactic Symbols:: -* Performance Issues:: -* Frequently Asked Questions:: -* Getting the latest CC Mode release:: -* Sample .emacs File:: +* Overview:: +* Getting Started:: +* Commands:: +* Font Locking:: +* Config Basics:: +* Custom Filling and Breaking:: +* Custom Auto-newlines:: +* Clean-ups:: +* Indentation Engine Basics:: +* Customizing Indentation:: +* Custom Macros:: +* Odds and Ends:: +* Sample .emacs File:: +* Performance Issues:: * Limitations and Known Bugs:: -* Mailing Lists and Submitting Bug Reports:: -* Concept Index:: -* Command Index:: Command Index -* Key Index:: Key Index -* Variable Index:: Variable Index +* FAQ:: +* Updating CC Mode:: +* Mailing Lists and Bug Reports:: +* Command and Function Index:: +* Variable Index:: +* Concept and Key Index:: + +@detailmenu + --- The Detailed Node Listing --- + +Commands + +* Indentation Commands:: +* Comment Commands:: +* Movement Commands:: +* Filling and Breaking:: +* Minor Modes:: +* Electric Keys:: +* Auto-newlines:: +* Hungry WS Deletion:: +* Subword Movement:: +* Other Commands:: + +Font Locking + +* Font Locking Preliminaries:: +* Faces:: +* Doc Comments:: +* AWK Mode Font Locking:: + +Configuration Basics + +* CC Hooks:: +* Style Variables:: +* Styles:: + +Styles + +* Built-in Styles:: +* Choosing a Style:: +* Adding Styles:: +* File Styles:: + +Customizing Auto-newlines + +* Hanging Braces:: +* Hanging Colons:: +* Hanging Semicolons and Commas:: + +Hanging Braces + +* Custom Braces:: + +Indentation Engine Basics + +* Syntactic Analysis:: +* Syntactic Symbols:: +* Indentation Calculation:: + +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:: +* Anonymous Class Symbol:: +* Statement Block Symbols:: +* K&R Symbols:: + +Customizing Indentation + +* c-offsets-alist:: +* Interactive Customization:: +* Line-Up Functions:: +* Custom Line-Up:: +* Other Indentation:: + +Line-Up Functions + +* Brace/Paren Line-Up:: +* List Line-Up:: +* Operator Line-Up:: +* Comment Line-Up:: +* Misc Line-Up:: + +@end detailmenu @end menu @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Introduction, Overview, Top, Top +@comment node-name, next, previous, up +@chapter Introduction @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Introduction, Getting Connected, Top, Top -@comment node-name, next, previous, up -@chapter Introduction -@cindex Introduction - -@macro ccmode -CC Mode -@end macro - @cindex BOCM - -Welcome to @ccmode{}. This is a GNU Emacs mode for editing files -containing C, C++, Objective-C, Java, and CORBA IDL code. This -incarnation of the mode is descendant from @file{c-mode.el} (also called -"Boring Old C Mode" or BOCM @code{:-)}, and @file{c++-mode.el} version -2, which I have been maintaining since 1992. @ccmode{} represents a -significant milestone in the mode's life. It has been fully merged back -with Emacs 19's @file{c-mode.el}. Also a new, more intuitive and -flexible mechanism for controlling indentation has been developed. - -@ccmode{} supports the editing of K&R and ANSI C, @dfn{ARM} -@footnote{``The Annotated C++ Reference Manual'', by Ellis and -Stroustrup.} C++, Objective-C, Java and CORBA's Interface -Definition Language files. In this way, you can -easily set up consistent coding styles for use in editing all C, C++, -Objective-C, Java and IDL programs. @ccmode{} does @emph{not} handle -font-locking (a.k.a. syntax coloring, keyword highlighting) or anything -of that nature, for any of these modes. Font-locking is handled by other -Emacs packages. - -This manual will describe the following: - -@itemize @bullet -@item -How to get started using @ccmode{}. - -@item -How the new indentation engine works. - -@item -How to customize the new indentation engine. - -@end itemize +@cindex history +@cindex awk-mode.el +@cindex c-mode.el +@cindex c++-mode.el + +Welcome to @ccmode{}, a GNU Emacs mode for editing files containing C, +C++, Objective-C, Java, CORBA IDL (and the variants CORBA PSDL and +CIDL), Pike and AWK code. This incarnation of the mode is descended +from @file{c-mode.el} (also called ``Boring Old C Mode'' or BOCM +@t{:-)}, @file{c++-mode.el} version 2, which Barry Warsaw had been +maintaining since 1992, and @file{awk-mode.el}, a long neglected mode +in the (X)Emacs base. + +Late in 1997, Martin Stjernholm joined Barry on the @ccmode{} +Maintainers Team, and implemented the Pike support. In 2000 Martin +took over as the sole maintainer. In 2001 Alan Mackenzie joined the +team, implementing AWK support in version 5.30. @ccmode{} did not +originally contain the font lock support for its languages --- that +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. +@comment Release.py script can update the version number automatically + +@ccmode{} supports the editing of K&R and ANSI C, C++, Objective-C, +Java, CORBA's Interface Definition Language, Pike@footnote{A C-like +scripting language with its roots in the LPC language used in some MUD +engines. See @uref{http://pike.ida.liu.se/}.} and AWK files. In this +way, you can easily set up consistent font locking and coding styles for +use in editing all of these languages, although AWK is not yet as +uniformly integrated as the other languages. @findex c-mode @findex c++-mode @findex objc-mode @findex java-mode @findex idl-mode +@findex pike-mode +@findex awk-mode Note that the name of this package is ``@ccmode{}'', but there is no top level @code{cc-mode} entry point. All of the variables, commands, and -functions in @ccmode{} are prefixed with @code{c-@var{}}, and -@code{c-mode}, @code{c++-mode}, @code{objc-mode}, @code{java-mode}, and -@code{idl-mode} entry points are provided. This file is intended to be -a replacement for @file{c-mode.el} and @file{c++-mode.el}. - -@cindex @file{cc-compat.el} file -This distribution also contains a file -called @file{cc-compat.el} which should ease your transition from BOCM -to @ccmode{}. If you have a BOCM configuration you are really happy -with, and want to postpone learning how to configure @ccmode{}, take a -look at that file. It maps BOCM configuration variables to @ccmode{}'s -new indentation model. It is not actively supported so for the long -run, you should learn how to customize @ccmode{} to support your coding -style. +functions in @ccmode{} are prefixed with @code{c-@var{thing}}, and +@code{c-mode}, @code{c++-mode}, @code{objc-mode}, @code{java-mode}, +@code{idl-mode}, @code{pike-mode}, and @code{awk-mode} entry points are +provided. This package is intended to be a replacement for +@file{c-mode.el}, @file{c++-mode.el} and @file{awk-mode.el}. A special word of thanks goes to Krishna Padmasola for his work in -converting the original @file{README} file to Texinfo format. I'd also -like to thank all the @ccmode{} victims who help enormously during the -early beta stages of @ccmode{}'s development. +converting the original @file{README} file to Texinfo format. I'd +also like to thank all the @ccmode{} victims who help enormously +during the early beta stages of @ccmode{}'s development. +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Overview, Getting Started, Introduction, Top +@comment node-name, next, previous, up@cindex organization of the manual +@chapter Overview of the Manual +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@node Getting Connected, New Indentation Engine, Introduction, Top -@comment node-name, next, previous, up -@chapter Getting Connected -@cindex Getting Connected +@noindent +The manual starts with several introductory chapters (including this +one). -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@noindent +The next chunk of the manual describes the day to day @emph{use} of +@ccmode{} (as contrasted with how to customize it). -If you got this version of @ccmode{} with Emacs or XEmacs, it should -work just fine right out of the box. Note however that you may not have -the latest @ccmode{} release and may want to upgrade your copy. +@itemize @bullet +@item +The chapter ``Commands'' describes in detail how to use (nearly) all +of @ccmode{}'s features. There are extensive cross-references from +here to the corresponding sections later in the manual which tell you +how to customize these features. -If you are upgrading an existing @ccmode{} installation, please see the -@file{README} file for installation details. @ccmode{} may not work -with older versions of Emacs or XEmacs. See the @ccmode{} release notes -Web pages for the latest information on Emacs version and package -compatibility (see @ref{Getting the latest CC Mode release}). +@item +``Font Locking'' describes how ``syntax highlighting'' is applied to +your buffers. It is mainly background information and can be skipped +over at a first reading. +@end itemize -@cindex @file{cc-mode-18.el} file -@emph{Note that @ccmode{} no longer works with Emacs 18!} The -@file{cc-mode-18.el} file is no longer distributed with @ccmode{}. If -you haven't upgraded from Emacs 18 by now, you are out of luck. +@noindent +The next chunk of the manual describes how to @emph{customize} +@ccmode{}. Typically, an overview of a topic is given at the chapter +level, then the sections and subsections describe the material in +increasing detail. -@findex c-version -@findex version (c-) -You can find out what version of @ccmode{} you are using by visiting a C -file and entering @kbd{M-x c-version RET}. You should see this message in -the echo area: -@example +@itemize @bullet +@item +The chapter ``Configuration Basics'' tells you @emph{how} to write +customizations - whether in hooks, in styles, in both, or in neither, +depending on your needs. It describes the @ccmode{} style system and +lists the standard styles that @ccmode{} supplies. -Using CC Mode version 5.XX +@item +The next few chapters describe in detail how to customize the various +features of @ccmode{}. -@end example +@item +Finally, there is a sample @file{.emacs} fragment, which might help you +in creating your own customization. +@end itemize @noindent -where @samp{XX} is the minor release number. - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node New Indentation Engine, Minor Modes, Getting Connected, Top -@comment node-name, next, previous, up - -@chapter New Indentation Engine -@cindex New Indentation Engine -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +The manual ends with ``this and that'', things that don't fit cleanly +into any of the previous chunks. -@ccmode{} has a new indentation engine, providing a simplified, yet -flexible and general mechanism for customizing indentation. It separates -indentation calculation into two steps: first, @ccmode{} analyzes the -line of code being indented to determine the kind of language construct -it's looking at, then it applies user defined offsets to the current -line based on this analysis. +@itemize @bullet +@item +Two chapters discuss the performance of @ccmode{} and known +bugs/limitations. -This section will briefly cover how indentation is calculated in -@ccmode{}. It is important to understand the indentation model -being used so that you will know how to customize @ccmode{} for -your personal coding style. +@item +The FAQ contains a list of common problems and questions. -@menu -* Syntactic Analysis:: -* Indentation Calculation:: -@end menu +@item +The next two chapters tell you how to get in touch with the @ccmode{} +project - whether for updating @ccmode{} or submitting bug reports. +@end itemize +@noindent +Finally, there are the customary indices. @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Syntactic Analysis, Indentation Calculation, , New Indentation Engine -@comment node-name, next, previous,up -@section Syntactic Analysis -@cindex Syntactic Analysis +@node Getting Started, Commands, Overview, Top +@comment node-name, next, previous, up +@chapter Getting Started @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@vindex c-offsets-alist -@vindex offsets-alist (c-) -@cindex relative buffer position -@cindex syntactic symbol -@cindex syntactic component -@cindex syntactic component list -@cindex relative buffer position -The first thing @ccmode{} does when indenting a line of code, is to -analyze the line, determining the @dfn{syntactic component list} of the -construct on that line. A syntactic component consists of a pair -of information (in lisp parlance, a @emph{cons cell}), where the first -part is a @dfn{syntactic symbol}, and the second part is a @dfn{relative -buffer position}. Syntactic symbols describe elements of C code -@footnote{or C++, Objective-C, Java or IDL code. In general, for the rest -of this manual I'll use the term ``C code'' to refer to all the C-like -dialects, unless otherwise noted.}, e.g. @code{statement}, -@code{substatement}, @code{class-open}, @code{class-close}, etc. -@xref{Syntactic Symbols}, for a complete list of currently recognized -syntactic symbols and their semantics. The variable -@code{c-offsets-alist} also contains the list of currently supported -syntactic symbols. - -Conceptually, a line of C code is always indented relative to the -indentation of some line higher up in the buffer. This is represented -by the relative buffer position in the syntactic component. +If you got this version of @ccmode{} with Emacs or XEmacs, it should +work just fine right out of the box. Note however that you might not +have the latest @ccmode{} release and might want to upgrade your copy +(see below). -Here is an example. Suppose we had the following code as the only thing -in a @code{c++-mode} buffer @footnote{The line numbers in this and -future examples don't actually appear in the buffer, of course!}: -@example -@group +You should probably start by skimming through the entire chapter +@ref{Commands} to get an overview of @ccmode{}'s capabilities. - 1: void swap( int& a, int& b ) - 2: @{ - 3: int tmp = a; - 4: a = b; - 5: b = tmp; - 6: @} +After trying out some commands, you may dislike some aspects of +@ccmode{}'s default configuration. Here is an outline of how to +change some of the settings that newcomers to @ccmode{} most often +want to change: -@end group -@end example +@table @asis +@item c-basic-offset +This Lisp variable holds an integer, the number of columns @ccmode{} +indents nested code. To set this value to 6, customize +@code{c-basic-offset} or put this into your @file{.emacs}: -@kindex C-c C-s -@findex c-show-syntactic-information -@findex show-syntactic-information (c-) -We can use the command @kbd{C-c C-s} -(@code{c-show-syntactic-information}) to simply report what the -syntactic analysis is for the current line. Running this command on -line 4 of this example, we'd see in the echo area@footnote{With a universal -argument (i.e. @kbd{C-u C-c C-s}) the analysis is inserted into the -buffer as a comment -on the current line.}: @example - -((statement . 35)) - +(setq c-basic-offset 6) @end example -This tells us that the line is a statement and it is indented relative -to buffer position 35, which happens to be the @samp{i} in @code{int} on -line 3. If you were to move point to line 3 and hit @kbd{C-c C-s}, you -would see: -@example - -((defun-block-intro . 29)) +@item The (indentation) style +The basic ``shape'' of indentation created by @ccmode{}---by default, +this is @code{gnu} style (except for Java and AWK buffers). A list of +the available styles and their descriptions can be found in +@ref{Built-in Styles}. A complete specification of the @ccmode{} +style system, including how to create your own style, can be found in +the chapter @ref{Styles}. To set your style to @code{linux}, either +customize @code{c-default-style} or put this into your @file{.emacs}: +@example +(setq c-default-style '((java-mode . "java") + (awk-mode . "awk") + (other . "linux"))) @end example -This indicates that the @samp{int} line is the first statement in a top -level function block, and is indented relative to buffer position 29, -which is the brace just after the function header. - -Here's another example: -@example -@group - - 1: int add( int val, int incr, int doit ) - 2: @{ - 3: if( doit ) - 4: @{ - 5: return( val + incr ); - 6: @} - 7: return( val ); - 8: @} - -@end group -@end example +@item Electric Indentation +Normally, when you type ``punctuation'' characters such as @samp{;} or +@samp{@{}, @ccmode{} instantly reindents the current line. This can +be disconcerting until you get used to it. To disable @dfn{electric +indentation} in the current buffer, type @kbd{C-c C-l}. Type the same +thing to enable it again. To have electric indentation disabled by +default, put the following into your @file{.emacs} file@footnote{There +is no ``easy customization'' facility for making this change.}: -@noindent -Hitting @kbd{C-c C-s} on line 4 gives us: @example - -((substatement-open . 46)) - +(setq-default c-electric-flag nil) @end example -@cindex substatement -@cindex substatment block @noindent -which tells us that this is a brace that @emph{opens} a substatement -block. @footnote{A @dfn{substatement} is the line after a -conditional statement, such as @code{if}, @code{else}, @code{while}, -@code{do}, @code{switch}, etc. A @dfn{substatement -block} is a brace block following one of these conditional statements.} - -@cindex comment-only line -Syntactic component lists can contain more than one component, and -individual syntactic components need not have relative buffer positions. -The most common example of this is a line that contains a @dfn{comment -only line}. -@example -@group +Details of of this and other similar ``Minor Modes'' appear in the +section @ref{Minor Modes}. - 1: void draw_list( List& drawables ) - 2: @{ - 3: // call the virtual draw() method on each element in list - 4: for( int i=0; i < drawables.count(), ++i ) - 5: @{ - 6: drawables[i].draw(); - 7: @} - 8: @} +@item Making the @key{RET} key indent the new line +The standard Emacs binding for @key{RET} just adds a new line. If you +want it to reindent the new line as well, rebind the key. Note that +the action of rebinding will fail if the pertinent keymap doesn't yet +exist---we thus need to delay the action until after @ccmode{} has +been loaded. Put the following code into your @file{.emacs}: -@end group +@example +(defun my-make-CR-do-indent () + (define-key c-mode-base-map "\C-m" 'c-context-line-break)) +(add-hook 'c-initialization-hook 'my-make-CR-do-indent) @end example @noindent -Hitting @kbd{C-c C-s} on line 3 of this example gives: -@example +This example demonstrates the use of a very powerful @ccmode{} (and +Emacs) facility, the hook. The use of @ccmode{}'s hooks is described +in @ref{CC Hooks}. +@end table -((comment-intro) (defun-block-intro . 46)) +All these settings should occur in your @file{.emacs} @emph{before} +any @ccmode{} buffers get loaded---in particular, before any call of +@code{desktop-read}. + +As you get to know the mode better, you may want to make more +ambitious changes to your configuration. For this, you should start +reading the chapter @ref{Config Basics}. + +If you are upgrading an existing @ccmode{} installation, please see +the @file{README} file for installation details. In particular, if +you are going to be editing AWK files, @file{README} describes how to +configure your (X)Emacs so that @ccmode{} will supersede the obsolete +@code{awk-mode.el} which might have been supplied with your (X)Emacs. +@ccmode{} might not work with older versions of Emacs or XEmacs. See +the @ccmode{} release notes at @uref{http://cc-mode.sourceforge.net} +for the latest information on Emacs version and package compatibility +(@pxref{Updating CC Mode}). + +@deffn Command c-version +@findex version (c-) +You can find out what version of @ccmode{} you are using by visiting a C +file and entering @kbd{M-x c-version RET}. You should see this message in +the echo area: +@example +Using CC Mode version 5.XX @end example @noindent -and you can see that the syntactic component list contains two syntactic -components. Also notice that the first component, -@samp{(comment-intro)} has no relative buffer position. - +where @samp{XX} is the minor release number. +@end deffn @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Indentation Calculation, , Syntactic Analysis, New Indentation Engine -@comment node-name, next, previous,up -@section Indentation Calculation -@cindex Indentation Calculation +@node Commands, Font Locking, Getting Started, Top +@comment node-name, next, previous, up +@chapter Commands @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@vindex c-offsets-alist -@vindex offsets-alist (c-) -Indentation for a line is calculated using the syntactic -component list derived in step 1 above (see @ref{Syntactic Analysis}). -Each component contributes to the final total indentation of the line in -two ways. +This chapter specifies all of CC Mode's commands, and thus contains +nearly everything you need to know to @emph{use} @ccmode{} (as +contrasted with configuring it). @dfn{Commands} here means both +control key sequences and @dfn{electric keys}, these being characters +such as @samp{;} which, as well as inserting themselves into the +buffer, also do other things. -First, the syntactic symbols are looked up in the @code{c-offsets-alist} -variable, which is an association list of syntactic symbols and the -offsets to apply for those symbols. These offsets are added to a -running total. +You might well want to review +@ifset XEMACS +@ref{Lists,,,@emacsman{}, @emacsmantitle{}}, +@end ifset +@ifclear XEMACS +@ref{Moving by Parens,,,@emacsman{}, @emacsmantitle{}}, +@end ifclear +which describes commands for moving around brace and parenthesis +structures. -Second, if the component has a relative buffer position, @ccmode{} -adds the column number of that position to the running total. By adding -up the offsets and columns for every syntactic component on the list, -the final total indentation for the current line is computed. - -Let's use our two code examples above to see how this works. Here is -our first example again: -@example -@group - 1: void swap( int& a, int& b ) - 2: @{ - 3: int tmp = a; - 4: a = b; - 5: b = tmp; - 6: @} +@menu +* Indentation Commands:: +* Comment Commands:: +* Movement Commands:: +* Filling and Breaking:: +* Minor Modes:: +* Electric Keys:: +* Auto-newlines:: +* Hungry WS Deletion:: +* Subword Movement:: +* Other Commands:: +@end menu -@end group -@end example +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Indentation Commands, Comment Commands, Commands, Commands +@comment node-name, next, previous,up +@section Indentation Commands +@cindex indentation +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +The following commands reindent C constructs. Note that when you +change your coding style, either interactively or through some other +means, your file does @emph{not} automatically get reindented. You +will need to execute one of the following commands to see the effects +of your changes. + +@cindex GNU indent program +Also, variables like @code{c-hanging-*} and @code{c-cleanup-list} +(@pxref{Custom Auto-newlines}) only affect how on-the-fly code is +formatted. Changing the ``hanginess'' of a brace and then +reindenting, will not move the brace to a different line. For this, +you're better off getting an external program like GNU @code{indent}, +which will rearrange brace location, amongst other things. + +Preprocessor directives are handled as syntactic whitespace from other +code, i.e. they can be interspersed anywhere without affecting the +indentation of the surrounding code, just like comments. + +The code inside macro definitions is, by default, still analyzed +syntactically so that you get relative indentation there just as you'd +get if the same code was outside a macro. However, since there is no +hint about the syntactic context, i.e. whether the macro expands to an +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. + +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. + +These commands indent code: + +@table @asis +@item @kbd{@key{TAB}} (@code{c-indent-command}) @kindex TAB -Let's say point is on line 3 and we hit the @kbd{TAB} key to re-indent -the line. Remember that the syntactic component list for that -line is: -@example +@findex c-indent-command +@findex indent-command (c-) +This command indents the current line. That is all you need to know +about it for normal use. -((defun-block-intro . 29)) +@code{c-indent-command} does different things, depending on the +setting of @code{c-syntactic-indentation} (@pxref{Indentation Engine +Basics}): -@end example +@itemize @bullet +@item +When it's non-@code{nil} (which it normally is), the command indents +the line according to its syntactic context. With a prefix argument +(@kbd{C-u @key{TAB}}), it will re-indent the entire +expression@footnote{this is only useful for a line starting with a +comment opener or an opening brace, parenthesis, or string quote.} +that begins at the line's left margin. -@noindent -@ccmode{} looks up @code{defun-block-intro} in the -@code{c-offsets-alist} variable. Let's say it finds the value @samp{4}; -it adds this to the running total (initialized to zero), yielding a -running total indentation of 4 spaces. - -Next @ccmode{} goes to buffer position 29 and asks for the current -column. This brace is in column zero, so @ccmode{} -adds @samp{0} to the running total. Since there is only one syntactic -component on the list for this line, indentation calculation is -complete, and the total indentation for the line -is 4 spaces. +@item +When it's @code{nil}, the command indents the line by an extra +@code{c-basic-offset} columns. A prefix argument acts as a +multiplier. A bare prefix (@kbd{C-u @key{TAB}}) is equivalent to -1, +removing @code{c-basic-offset} columns from the indentation. +@end itemize -Here's another example: -@example -@group +The precise behavior is modified by several variables: With +@code{c-tab-always-indent}, you can make @key{TAB} insert whitespace +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{}, +@emacsmantitle{}}. - 1: int add( int val, int incr, int doit ) - 2: @{ - 3: if( doit ) - 4: @{ - 5: return( val + incr ); - 6: @} - 7: return( val ); - 8: @} +@defopt c-tab-always-indent +@vindex tab-always-indent (c-) +@cindex literal +This variable modifies how @key{TAB} operates. +@itemize @bullet +@item +When it is @code{t} (the default), @key{TAB} simply indents the +current line. +@item +When it is @code{nil}, @key{TAB} (re)indents the line only if point is +to the left of the first non-whitespace character on the line. +Otherwise it inserts some whitespace (a tab or an equivalent number of +spaces - see below) at point. +@item +With some other value, the line is reindented. Additionally, if point +is within a string or comment, some whitespace is inserted. +@end itemize +@end defopt -@end group -@end example +@defopt c-insert-tab-function +@vindex insert-tab-function (c-) +@findex tab-to-tab-stop +When ``some whitespace'' is inserted as described above, what actually +happens is that the function stored in @code{c-insert-tab-function} is +called. Normally, this is @code{insert-tab}, which inserts a real tab +character or the equivalent number of spaces (depending on +@code{indent-tabs-mode}). Some people, however, set +@code{c-insert-tab-function} to @code{tab-to-tab-stop} so as to get +hard tab stops when indenting. +@end defopt +@end table -If we were to hit @kbd{TAB} on line 4 in the above example, the same -basic process is performed, despite the differences in the syntactic -component list. Remember that the list for this line is: -@example +@noindent +The kind of indentation the next five commands do depends on the +setting of @code{c-syntactic-indentation} (@pxref{Indentation Engine +Basics}): +@itemize @bullet +@item +when it is non-@code{nil} (the default), the commands indent lines +according to their syntactic context; +@item +when it is @code{nil}, they just indent each line the same amount as +the previous non-blank line. The commands that indent a region aren't +very useful in this case. +@end itemize -((substatement-open . 46)) +@table @asis +@item @kbd{C-j} (@code{newline-and-indent}) +@kindex C-j +@findex newline-and-indent +Inserts a newline and indents the new blank line, ready to start +typing. This is a standard (X)Emacs command. -@end example +@item @kbd{C-M-q} (@code{c-indent-exp}) +@kindex C-M-q +@findex c-indent-exp +@findex indent-exp (c-) +Indents an entire balanced brace or parenthesis expression. Note that +point must be on the opening brace or parenthesis of the expression +you want to indent. -Here, @ccmode{} first looks up the @code{substatement-open} symbol -in @code{c-offsets-alist}. Let's say it finds the value @samp{4}. This -yields a running total of 4. @ccmode{} then goes to -buffer position 46, which is the @samp{i} in @code{if} on line 3. This -character is in the fourth column on that line so adding this to the -running total yields an indentation for the line of 8 spaces. +@item @kbd{C-c C-q} (@code{c-indent-defun}) +@kindex C-c C-q +@findex c-indent-defun +@findex indent-defun (c-) +Indents the entire top-level function, class or macro definition +encompassing point. It leaves point unchanged. This function can't be +used to reindent a nested brace construct, such as a nested class or +function, or a Java method. The top-level construct being reindented +must be complete, i.e. it must have both a beginning brace and an ending +brace. + +@item @kbd{C-M-\} (@code{indent-region}) +@kindex C-M-\ +@findex indent-region +Indents an arbitrary region of code. This is a standard Emacs command, +tailored for C code in a @ccmode{} buffer. Note, of course, that point +and mark must delineate the region you want to indent. -Simple, huh? +@item @kbd{C-M-h} (@code{c-mark-function}) +@kindex C-M-h +@findex c-mark-function +@findex mark-function (c-) +While not strictly an indentation command, this is useful for marking +the current top-level function or class definition as the current +region. As with @code{c-indent-defun}, this command operates on +top-level constructs, and can't be used to mark say, a Java method. +@end table -Actually, the mode usually just does The Right Thing without you having -to think about it in this much detail. But when customizing -indentation, it's helpful to understand the general indentation model -being used. +These variables are also useful when indenting code: -@vindex c-echo-syntactic-information-p -@vindex echo-syntactic-information-p (c-) -@cindex TAB -As you configure @ccmode{}, you might want to set the variable -@code{c-echo-syntactic-information-p} to non-@code{nil} so that the -syntactic component list and calculated offset will always be echoed in -the minibuffer when you hit @kbd{TAB}. +@defopt indent-tabs-mode +This is a standard Emacs variable that controls how line indentation +is composed. When it's non-@code{nil}, tabs can be used in a line's +indentation, otherwise only spaces are used. +@end defopt +@defopt c-progress-interval +@vindex progress-interval (c-) +When indenting large regions of code, this variable controls how often a +progress message is displayed. Set this variable to @code{nil} to +inhibit the progress messages, or set it to an integer which is how +often (in seconds) progress messages are to be displayed. +@end defopt @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Minor Modes, Commands, New Indentation Engine, Top -@comment node-name, next, previous,up - -@chapter Minor Modes -@cindex Minor Modes +@node Comment Commands, Movement Commands, Indentation Commands, Commands +@comment node-name, next, previous, up +@section Comment Commands +@cindex comments (insertion of) @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@ccmode{} contains two minor-mode-like features that you should -find useful while you enter new C code. The first is called -@dfn{auto-newline} mode, and the second is called @dfn{hungry-delete} -mode. These minor modes can be toggled on and off independently, and -@ccmode{} can be configured so that it starts up with any -combination of these minor modes. By default, both of these minor modes -are turned off. +@table @asis +@item @kbd{C-c C-c} (@code{comment-region}) +@kindex C-c C-c +@findex comment-region +This command comments out the lines that start in the region. With a +negative argument, it does the opposite - it deletes the comment +delimiters from these lines. @xref{Multi-Line Comments,,, emacs, GNU +Emacs Manual}, for fuller details. @code{comment-region} isn't +actually part of @ccmode{} - it is given a @ccmode{} binding for +convenience. + +@item @kbd{M-;} (@code{comment-dwim} or @code{indent-for-comment} @footnote{The name of this command varies between (X)Emacs versions.}) +@kindex M-; +@findex comment-dwim +@findex indent-for-comment +Insert a comment at the end of the current line, if none is there +already. Then reindent the comment according to @code{comment-column} +@ifclear XEMACS +(@pxref{Options for Comments,,, emacs, GNU Emacs Manual}) +@end ifclear +@ifset XEMACS +(@pxref{Comments,,, xemacs, XEmacs User's Manual}) +@end ifset +and the variables below. Finally, position the point after the +comment starter. @kbd{C-u M-;} kills any comment on the current line, +together with any whitespace before it. This is a standard Emacs +command, but @ccmode{} enhances it a bit with two variables: + +@defopt c-indent-comment-alist +@vindex indent-comment-alist (c-) +@vindex comment-column +This style variable allows you to vary the column that @kbd{M-;} puts +the comment at, depending on what sort of code is on the line, and +possibly the indentation of any similar comment on the preceding line. +It is an association list that maps different types of lines to +actions describing how they should be handled. If a certain line type +isn't present on the list then the line is indented to the column +specified by @code{comment-column}. + +See the documentation string for for a full description of this +variable (use @kbd{C-h v c-indent-comment-alist}). +@end defopt + +@defopt c-indent-comments-syntactically-p +@vindex indent-comments-syntactically-p (c-) +Normally, when this style variable is @code{nil}, @kbd{M-;} will +indent comment-only lines according to @code{c-indent-comment-alist}, +just as it does with lines where other code precede the comments. +However, if you want it to act just like @key{TAB} for comment-only +lines you can get that by setting +@code{c-indent-comments-syntactically-p} to non-@code{nil}. + +If @code{c-indent-comments-syntactically-p} is non-@code{nil} then +@code{c-indent-comment-alist} won't be consulted at all for comment-only +lines. +@end defopt +@end table -The state of the minor modes is always reflected in the minor mode list -on the modeline of the @ccmode{} buffer. When auto-newline mode is -enabled, you will see @samp{C/a} on the mode line @footnote{Remember -that the @samp{C} could be replaced with @samp{C++}, @samp{ObjC}, -@samp{Java} or @samp{IDL}.}. When hungry delete mode is enabled you -would see @samp{C/h} and when both modes are enabled, you'd see -@samp{C/ah}. +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Movement Commands, Filling and Breaking, Comment Commands, Commands +@comment node-name, next, previous, up +@section Movement Commands +@cindex movement +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@kindex C-c C-a -@kindex C-c C-d -@kindex C-c C-t -@findex c-toggle-hungry-state -@findex c-toggle-auto-state -@findex c-toggle-auto-hungry-state -@findex toggle-hungry-state (c-) -@findex toggle-auto-state (c-) -@findex toggle-auto-hungry-state (c-) -@ccmode{} provides keybindings which allow you to toggle the minor -modes on the fly while editing code. To toggle just the auto-newline -state, hit @kbd{C-c C-a} (@code{c-toggle-auto-state}). When you do -this, you should see the @samp{a} indicator either appear or disappear -on the modeline. Similarly, to toggle just the hungry-delete state, use -@kbd{C-c C-d} (@code{c-toggle-hungry-state}), and to toggle both states, -use @kbd{C-c C-t} (@code{c-toggle-auto-hungry-state}). - -To set up the auto-newline and hungry-delete states to your preferred -values, you would need to add some lisp to your @file{.emacs} file that -called one of the @code{c-toggle-*-state} functions directly. When -called programmatically, each function takes a numeric value, where -a positive number enables the minor mode, a negative number disables the -mode, and zero toggles the current state of the mode. - -So for example, if you wanted to enable both auto-newline and -hungry-delete for all your C file editing, you could add the following -to your @file{.emacs} file: -@example +@ccmode{} contains some useful commands for moving around in C code. -(add-hook 'c-mode-common-hook - '(lambda () (c-toggle-auto-hungry-state 1))) +@table @asis +@item @kbd{C-M-a} +@itemx @kbd{C-M-e} +@findex c-beginning-of-defun +@findex c-end-of-defun -@end example +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 +also count as ``functions'' here. To move over several functions, you +can give these commands a repeat count. + +The start of a function is at its header. The end of the function is +after its closing brace, or after the semicolon of a construct (such +as a @code{struct}) which doesn't end at the brace. These two +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. + +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 +must be in column zero. See @ref{Defuns,,,@emacsman{}, +@emacsmantitle{}}, for more information. + +@item @kbd{C-M-a} (AWK Mode) (@code{c-awk-beginning-of-defun}) +@itemx @kbd{C-M-e} (AWK Mode) (@code{c-awk-end-of-defun}) +@kindex C-M-a (AWK Mode) +@kindex C-M-e (AWK Mode) +@findex c-awk-beginning-of-defun +@findex awk-beginning-of-defun (c-) +@findex c-awk-end-of-defun +@findex awk-end-of-defun (c-) +Move to the beginning or end of the current or next AWK defun. These +commands can take prefix-arguments, their functionality being entirely +equivalent to @code{beginning-of-defun} and @code{end-of-defun}. + +AWK Mode @dfn{defuns} are either pattern/action pairs (either of which +might be implicit) or user defined functions. Having the @samp{@{} and +@samp{@}} (if there are any) in column zero, as is suggested for some +modes, is neither necessary nor helpful in AWK mode. + +@item @kbd{M-a} (@code{c-beginning-of-statement}) +@itemx @kbd{M-e} (@code{c-end-of-statement}) +@kindex M-a +@kindex M-e +@findex c-beginning-of-statement +@findex c-end-of-statement +@findex beginning-of-statement (c-) +@findex end-of-statement (c-) +Move to the beginning or end of the innermost C statement. If point +is already there, move to the next beginning or end of a statement, +even if that means moving into a block. (Use @kbd{C-M-b} or +@kbd{C-M-f} to move over a balanced block.) A prefix argument @var{n} +means move over @var{n} statements. + +If point is within or next to a comment or a string which spans more +than one line, these commands move by sentences instead of statements. + +When called from a program, these functions take three optional +arguments: the repetition count, a buffer position limit which is the +farthest back to search for the syntactic context, and a flag saying +whether to do sentence motion in or near comments and multiline +strings. + +@item @kbd{C-c C-u} (@code{c-up-conditional}) +@kindex C-c C-u +@findex c-up-conditional +@findex up-conditional (c-) +Move back to the containing preprocessor conditional, leaving the mark +behind. A prefix argument acts as a repeat count. With a negative +argument, move forward to the end of the containing preprocessor +conditional. + +@samp{#elif} is treated like @samp{#else} followed by @samp{#if}, so the +function stops at them when going backward, but not when going +forward. + +This key sequence is not bound in AWK Mode, which doesn't have +preprocessor statements. + +@item @kbd{M-x c-up-conditional-with-else} +@findex c-up-conditional-with-else +@findex up-conditional-with-else (c-) +A variety of @code{c-up-conditional} that also stops at @samp{#else} +lines. Normally those lines are ignored. + +@item @kbd{M-x c-down-conditional} +@findex c-down-conditional +@findex down-conditional (c-) +Move forward into the next nested preprocessor conditional, leaving +the mark behind. A prefix argument acts as a repeat count. With a +negative argument, move backward into the previous nested preprocessor +conditional. + +@samp{#elif} is treated like @samp{#else} followed by @samp{#if}, so the +function stops at them when going forward, but not when going backward. + +@item @kbd{M-x c-down-conditional-with-else} +@findex c-down-conditional-with-else +@findex down-conditional-with-else (c-) +A variety of @code{c-down-conditional} that also stops at @samp{#else} +lines. Normally those lines are ignored. + +@item @kbd{C-c C-p} (@code{c-backward-conditional}) +@itemx @kbd{C-c C-n} (@code{c-forward-conditional}) +@kindex C-c C-p +@kindex C-c C-n +@findex c-backward-conditional +@findex c-forward-conditional +@findex backward-conditional (c-) +@findex forward-conditional (c-) +Move backward or forward across a preprocessor conditional, leaving +the mark behind. A prefix argument acts as a repeat count. With a +negative argument, move in the opposite direction. +These key sequences are not bound in AWK Mode, which doesn't have +preprocessor statements. -@cindex electric characters +@item @kbd{M-x c-backward-into-nomenclature} +@itemx @kbd{M-x c-forward-into-nomenclature} +@findex c-backward-into-nomenclature +@findex c-forward-into-nomenclature +@findex backward-into-nomenclature (c-) +@findex forward-into-nomenclature (c-) +A popular programming style, especially for object-oriented languages +such as C++ is to write symbols in a mixed case format, where the +first letter of each word is capitalized, and not separated by +underscores. E.g. @samp{SymbolsWithMixedCaseAndNoUnderlines}. -@menu -* Auto-newline insertion:: -* Hungry-deletion of whitespace:: -* Auto-fill mode interaction:: -@end menu +These commands move backward or forward to the beginning of the next +capitalized word. With prefix argument @var{n}, move @var{n} times. +If @var{n} is negative, move in the opposite direction. -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Auto-newline insertion, Hungry-deletion of whitespace, , Minor Modes -@comment node-name, next, previous,up +Note that these two commands have been superseded by +@code{c-subword-mode}, which you should use instead. @xref{Subword +Movement}. They might be removed from a future release of @ccmode{}. +@end table -@section Auto-newline insertion -@cindex Auto-newline insertion +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Filling and Breaking, Minor Modes, Movement Commands, Commands +@comment node-name, next, previous, up +@section Filling and Line Breaking Commands +@cindex text filling +@cindex line breaking +@cindex comment handling @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@cindex electric commands -Auto-newline minor mode works by enabling certain @dfn{electric -commands}. Electric commands are typically bound to special characters -such as the left and right braces, colons, semi-colons, etc., which when -typed, perform some magic formatting in addition to inserting the typed -character. As a general rule, electric commands are only electric when -the following conditions apply: - -@itemize @bullet -@item -Auto-newline minor mode is enabled, as evidenced by a @samp{C/a} or -@samp{C/ah} indicator on the modeline. - -@cindex literal -@cindex syntactic whitespace -@item -The character was not typed inside of a literal @footnote{A -@dfn{literal} is defined as any comment, string, or C preprocessor macro -definition. These constructs are also known as @dfn{syntactic -whitespace} since they are usually ignored when scanning C code.}. - -@item -@kindex C-u -No numeric argument was supplied to the command (i.e. it was typed as -normal, with no @kbd{C-u} prefix). - -@end itemize +Since there's a lot of normal text in comments and string literals, +@ccmode{} provides features to edit these like in text mode. The goal +is to do it seamlessly, i.e. you can use auto fill mode, sentence and +paragraph movement, paragraph filling, adaptive filling etc. wherever +there's a piece of normal text without having to think much about it. +@ccmode{} keeps the indentation, fixes suitable comment line prefixes, +and so on. + +You can configure the exact way comments get filled and broken, and +where Emacs does auto-filling (see @pxref{Custom Filling and +Breaking}). Typically, the style system (@pxref{Styles}) will have +set this up for you, so you probably won't have to bother. + +@findex auto-fill-mode +@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 +@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 +setting the @code{string} syntactic symbol (@pxref{Syntactic Symbols} +and @pxref{Customizing Indentation})}. + +@table @asis +@item @kbd{M-q} (@code{c-fill-paragraph}) +@kindex M-q +@findex c-fill-paragraph +@findex fill-paragraph (c-) +@cindex Javadoc markup +@cindex Pike autodoc markup +This command fills multiline string literals and both block +and line style comments. In Java buffers, the Javadoc markup words +are recognized as paragraph starters. The line oriented Pike autodoc +markup words are recognized in the same way in Pike mode. + +The formatting of the starters (@code{/*}) and enders (@code{*/}) of +block comments are kept as they were before the filling. I.e., if +either the starter or ender were on a line of its own, then it stays +on its own line; conversely, if the delimiter has comment text on its +line, it keeps at least one word of that text with it on the line. + +This command is the replacement for @code{fill-paragraph} in @ccmode{} +buffers. + +@item @kbd{M-j} (@code{c-indent-new-comment-line}) +@kindex M-j +@findex c-indent-new-comment-line +@findex indent-new-comment-line (c-) +This breaks the current line at point and indents the new line. If +point was in a comment, the new line gets the proper comment line +prefix. If point was inside a macro, a backslash is inserted before +the line break. It is the replacement for +@code{indent-new-comment-line}. + +@item @kbd{M-x c-context-line-break} +@findex c-context-line-break +@findex context-line-break (c-) +Insert a line break suitable to the context: If the point is inside a +comment, the new line gets the suitable indentation and comment line +prefix like @code{c-indent-new-comment-line}. In normal code it's +indented like @code{newline-and-indent} would do. In macros it acts +like @code{newline-and-indent} but additionally inserts and optionally +aligns the line ending backslash so that the macro remains unbroken. +@xref{Custom Macros}, for details about the backslash alignment. In a +string, a backslash is inserted only if the string is within a +macro@footnote{In GCC, unescaped line breaks within strings are +valid.}. + +This function is not bound to a key by default, but it's intended to be +used on the @kbd{RET} key. If you like the behavior of +@code{newline-and-indent} on @kbd{RET}, you should consider switching to +this function. @xref{Sample .emacs File}. + +@item @kbd{M-x c-context-open-line} +@findex c-context-open-line +@findex context-open-line (c-) +This is to @kbd{C-o} (@kbd{M-x open-line}) as +@code{c-context-line-break} is to @kbd{RET}. I.e. it works just like +@code{c-context-line-break} but leaves the point before the inserted +line break. +@end table -@menu -* Hanging Braces:: -* Hanging Colons:: -* Hanging Semi-colons and commas:: -* Other electric commands:: -* Clean-ups:: -@end menu @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Hanging Braces, Hanging Colons, , Auto-newline insertion -@comment node-name, next, previous,up - -@subsection Hanging Braces -@cindex Hanging Braces +@node Minor Modes, Electric Keys, Filling and Breaking, Commands +@comment node-name, next, previous, up +@section Minor Modes +@cindex Minor Modes @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@findex c-electric-brace -@findex electric-brace (c-) -@vindex c-hanging-braces-alist -@vindex hanging-braces-alist (c-) -@vindex c-offsets-alist -@vindex offsets-alist (c-) -When you type either an open or close brace (i.e. @kbd{@{} or @kbd{@}}), -the electric command @code{c-electric-brace} gets run. This command has -two electric formatting behaviors. First, it will perform some -re-indentation of the line the brace was typed on, and second, it will -add various newlines before and/or after the typed brace. -Re-indentation occurs automatically whenever the electric behavior is -enabled. If the brace ends up on a line other than the one it was typed -on, then that line is also re-indented. - -@cindex class-open syntactic symbol -@cindex class-close syntactic symbol -@cindex defun-open syntactic symbol -@cindex defun-close syntactic symbol -@cindex inline-open syntactic symbol -@cindex inline-close syntactic symbol -@cindex brace-list-open syntactic symbol -@cindex brace-list-close syntactic symbol -@cindex brace-list-intro syntactic symbol -@cindex brace-list-entry syntactic symbol -@cindex block-open syntactic symbol -@cindex block-close syntactic symbol -@cindex substatement-open syntactic symbol -@cindex statement-case-open syntactic symbol -@cindex extern-lang-open syntactic symbol -@cindex extern-lang-close syntactic symbol -@cindex namespace-open symbol -@cindex namespace-close symbol - -The insertion of newlines is controlled by the -@code{c-hanging-braces-alist} variable. This variable contains a -mapping between syntactic symbols related to braces, and a list of -places to insert a newline. The syntactic symbols that are useful for -this list are: @code{class-open}, @code{class-close}, @code{defun-open}, -@code{defun-close}, @code{inline-open}, @code{inline-close}, -@code{brace-list-open}, @code{brace-list-close}, -@code{brace-list-intro}, @code{brace-list-entry}, @code{block-open}, -@code{block-close}, @code{substatement-open}, -@code{statement-case-open}, -@code{extern-lang-open}, @code{extern-lang-close}, -@code{namespace-open}, and @code{namespace-close}. -@xref{Syntactic Symbols} for a more -detailed description of these syntactic symbols. - -@cindex Custom Indentation Functions -The value associated with each syntactic symbol in this association list -is called an @var{ACTION} which can be either a function or a list. -@xref{Custom Brace and Colon Hanging} for a more detailed discussion of -using a function as a brace hanging @var{ACTION}. - -When the @var{ACTION} is a list, it can contain any combination of the -symbols @code{before} and @code{after}, directing @ccmode{} where to -put newlines in relationship to the brace being inserted. Thus, if the -list contains only the symbol @code{after}, then the brace is said to -@dfn{hang} on the right side of the line, as in: -@example -@group - -// here, open braces always `hang' -void spam( int i ) @{ - if( i == 7 ) @{ - dosomething(i); - @} -@} - - -@end group -@end example - -When the list contains both @code{after} and @code{before}, the braces -will appear on a line by themselves, as shown by the close braces in the -above example. The list can also be empty, in which case no newlines -are added either before or after the brace. - -For example, the default value of @code{c-hanging-braces-alist} is: -@example -@group - -(defvar c-hanging-braces-alist '((brace-list-open) - (substatement-open after) - (block-close . c-snug-do-while) - (extern-lang-open after))) - -@end group -@end example - -@noindent -which says that @code{brace-list-open} braces should both hang on the -right side, and allow subsequent text to follow on the same line as the -brace. Also, @code{substatement-open} and @code{extern-lang-open} -braces should hang on the right side, but subsequent text should follow -on the next line. Here, in the @code{block-close} entry, you also see -an example of using a function as an @var{ACTION}. - -A word of caution: it is not a good idea to hang top-level construct -introducing braces, such as @code{class-open} or @code{defun-open}. -Emacs makes an assumption that such braces will always appear in column -zero, hanging such braces can introduce performance problems. -@xref{Performance Issues} for more information. +@ccmode{} contains several minor-mode-like features that you might +find useful while writing new code or editing old code: + +@table @asis +@item electric mode +When this is enabled, certain visible characters cause reformatting as +they are typed. This is normally helpful, but can be a nuisance when +editing chaotically formatted code. It can also be disconcerting, +especially for users who are new to @ccmode{}. +@item auto-newline mode +This automatically inserts newlines where you'd probably want to type +them yourself, e.g. after typing @samp{@}}s. Its action is suppressed +when electric mode is disabled. +@item hungry-delete mode +This lets you delete a contiguous block of whitespace with a single +key - for example, the newline and indentation just inserted by +auto-newline when you want to back up and write a comment after the +last statement. +@item subword mode +This mode makes basic word movement commands like @kbd{M-f} +(@code{forward-word}) and @kbd{M-b} (@code{backward-word}) treat the +parts of sillycapsed symbols as different words. +E.g. @samp{NSGraphicsContext} is treated as three words @samp{NS}, +@samp{Graphics}, and @samp{Context}. +@item syntactic-indentation mode +When this is enabled (which it normally is), indentation commands such +as @kbd{C-j} indent lines of code according to their syntactic +structure. Otherwise, a line is simply indented to the same level as +the previous one and @kbd{@key{TAB}} adjusts the indentation in steps +of `c-basic-offset'. +@end table +Full details on how these minor modes work are at @ref{Electric Keys}, +@ref{Auto-newlines}, @ref{Hungry WS Deletion}, @ref{Subword Movement}, +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 +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. + +@ccmode{} displays the current state of the first four of these minor +modes on the modeline by appending letters to the major mode's name, +one letter for each enabled minor mode - @samp{l} for electric mode, +@samp{a} for auto-newline mode, @samp{h} for hungry delete mode, and +@samp{w} for subword mode. If all these modes were enabled, you'd see +@samp{C/lahw}@footnote{The @samp{C} would be replaced with the name of +the language in question for the other languages @ccmode{} supports.}. + +Here are the commands to toggle these modes: + +@table @asis +@item @kbd{C-c C-l} (@code{c-toggle-electric-state}) +@kindex C-c C-l +@findex c-toggle-electric-state +@findex toggle-electric-state (c-) +Toggle electric minor mode. When the command turns the mode off, it +also suppresses auto-newline mode. + +@item @kbd{C-c C-a} (@code{c-toggle-auto-newline}) +@kindex C-c C-a +@findex c-toggle-auto-newline +@findex toggle-auto-newline (c-) +Toggle auto-newline minor mode. When the command turns the mode on, +it also enables electric minor mode. -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Hanging Colons, Hanging Semi-colons and commas, Hanging Braces, Auto-newline insertion -@comment node-name, next, previous,up +@item @kbd{M-x c-toggle-hungry-state}@footnote{Prior to @ccmode{} 5.31, this command was bound to @kbd{C-c C-d}.} +@findex c-toggle-hungry-state +@findex toggle-hungry-state (c-) +Toggle hungry-delete minor mode. -@subsection Hanging Colons -@cindex Hanging Colons -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@item @kbd{M-x c-toggle-auto-hungry-state}@footnote{Prior to @ccmode{} 5.31, this command was bound to @kbd{C-c C-t}.} +@findex c-toggle-auto-hungry-state +@findex toggle-auto-hungry-state (c-) +Toggle both auto-newline and hungry delete minor modes. + +@item @kbd{C-c C-w} (@code{M-x c-subword-mode}) +@kindex C-c C-w +@findex c-subword-mode +@findex subword-mode (c-) +Toggle subword mode. + +@item @kbd{M-x c-toggle-syntactic-indentation} +@findex c-toggle-syntactic-indentation +@findex toggle-syntactic-indentation (c-) +Toggle syntactic-indentation mode. +@end table -@vindex hanging-colons-alist (c-) -@vindex c-hanging-colons-alist -Using a mechanism similar to brace hanging (see @ref{Hanging Braces}), -colons can also be made to hang using the variable -@code{c-hanging-colons-alist}. The syntactic symbols appropriate for -this assocation list are: @code{case-label}, @code{label}, -@code{access-label}, @code{member-init-intro}, and @code{inher-intro}. -Note however that for @code{c-hanging-colons-alist}, @var{ACTION}s as -functions are not supported. See also @ref{Custom Brace and Colon -Hanging} for details. - -@cindex Clean-ups -In C++, double-colons are used as a scope operator but because these -colons always appear right next to each other, newlines before and after -them are controlled by a different mechanism, called @dfn{clean-ups} in -@ccmode{}. @xref{Clean-ups} for details. +Common to all the toggle functions above is that if they are called +programmatically, they take an optional numerical argument. A +positive value will turn on the minor mode (or both of them in the +case of @code{c-toggle-auto-hungry-state}) and a negative value will +turn it (or them) off. @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Hanging Semi-colons and commas, Other electric commands, Hanging Colons, Auto-newline insertion -@comment node-name, next, previous,up - -@subsection Hanging Semi-colons and commas -@cindex Hanging Semi-colons and commas +@node Electric Keys, Auto-newlines, Minor Modes, Commands +@comment node-name, next, previous, up +@section Electric Keys and Keywords +@cindex electric characters @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -Semicolons and commas are also electric in @ccmode{}, but since -these characters do not correspond directly to syntactic symbols, a -different mechanism is used to determine whether newlines should be -automatically inserted after these characters. @xref{Customizing -Semi-colons and Commas} for details. +Most punctuation keys provide @dfn{electric} behavior - as well as +inserting themselves they perform some other action, such as +reindenting the line. This reindentation saves you from having to +reindent a line manually after typing, say, a @samp{@}}. A few +keywords, such as @code{else}, also trigger electric action. +You can inhibit the electric behaviour described here by disabling +electric minor mode (@pxref{Minor Modes}). -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Other electric commands, Clean-ups, Hanging Semi-colons and commas, Auto-newline insertion -@comment node-name, next, previous,up +Common to all these keys is that they only behave electrically when +used in normal code (as contrasted with getting typed in a string +literal or comment). Those which cause re-indentation do so only when +@code{c-syntactic-indentation} has a non-@code{nil} value (which it +does by default). -@subsection Other electric commands -@cindex Other electric commands -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +These keys and keywords are: +@c ACM, 2004/8/24: c-electric-pound doesn't check c-s-i: this is more +@c like a bug in the code than a bug in this document. It'll get +@c fixed in the code sometime. +@table @kbd +@item # @kindex # @findex c-electric-pound -@vindex c-electric-pound-behavior @findex electric-pound (c-) +@vindex c-electric-pound-behavior @vindex electric-pound-behavior (c-) -@vindex c-offsets-alist -@vindex offsets-alist (c-) -A few other keys also provide electric behavior. For example -@kbd{#} (@code{c-electric-pound}) is electric when typed as -the first non-whitespace character on a line. In this case, the -variable @code{c-electric-pound-behavior} is consulted for the electric -behavior. This variable takes a list value, although the only element -currently defined is @code{alignleft}, which tells this command to force -the @samp{#} character into column zero. This is useful for entering -C preprocessor macro definitions. +Pound (bound to @code{c-electric-pound}) is electric when typed as the +first non-whitespace character on a line and not within a macro +definition. In this case, the variable @code{c-electric-pound-behavior} +is consulted for the electric behavior. This variable takes a list +value, although the only element currently defined is @code{alignleft}, +which tells this command to force the @samp{#} character into column +zero. This is useful for entering preprocessor macro definitions. + +Pound is not electric in AWK buffers, where @samp{#} starts a comment, +and is bound to @code{self-insert-command} like any typical printable +character. +@c ACM, 2004/8/24: Change this (and the code) to do AWK comment +@c reindentation. +@item * +@kindex * +@itemx / +@kindex / @findex c-electric-star -@findex c-electric-slash @findex electric-star (c-) +@findex c-electric-slash @findex electric-slash (c-) -@cindex comment-only line -Stars and slashes (i.e. @kbd{*} and @kbd{/}, @code{c-electric-star} and -@code{c-electric-slash} respectively) are also electric under -certain circumstances. If a star is inserted as the second character of -a C style block comment on a @dfn{comment-only} line, then the comment -delimiter is indented as defined by @code{c-offsets-alist}. A -comment-only line is defined as a line which contains only a comment, as -in: -@example -@group - -void spam( int i ) -@{ - // this is a comment-only line... - if( i == 7 ) // but this is not - @{ - dosomething(i); - @} -@} - -@end group -@end example - -Likewise, if a slash is inserted as the second slash in a C++ style line -comment (also only on a comment-only line), then the line is indented as -defined by @code{c-offsets-alist}. - -@findex c-electric-lt-gt -@findex electric-lt-gt (c-) +A star (bound to @code{c-electric-star}) or a slash +(@code{c-electric-slash}) causes reindentation when you type it as the +second component of a C style block comment opener (@samp{/*}) or a +C++ line comment opener (@samp{//}) respectively, but only if the +comment opener is the first thing on the line (i.e. there's only +whitespace before it). + +Additionally, you can configure @ccmode{} so that typing a slash at +the start of a line within a block comment will terminate the +comment. You don't need to have electric minor mode enabled to get +this behaviour. @xref{Clean-ups}. + +In AWK mode, @samp{*} and @samp{/} do not delimit comments and are not +electric. + +@item < @kindex < +@itemx > @kindex > -Less-than and greater-than signs (@code{c-electric-lt-gt}) are also -electric, but only in C++ mode. Hitting the second of two @kbd{<} or -@kbd{>} keys re-indents the line if it is a C++ style stream operator. - +@findex c-electric-lt-gt +@findex electric-lt-gt (c-) +A less-than or greater-than sign (bound to @code{c-electric-lt-gt}) is +electric in two circumstances: when it is an angle bracket in a C++ +@samp{template} declaration (and similar constructs in other +languages) and when it is the second of two @kbd{<} or @kbd{>} +characters in a C++ style stream operator. In either case, the line +is reindented. Angle brackets in C @samp{#include} directives are not +electric. + +@item ( +@kindex ( +@itemx ) +@kindex ) +@findex c-electric-paren +@findex electric-paren (c-) +The normal parenthesis characters @samp{(} and @samp{)} (bound to +@code{c-electric-paren}) reindent the current line. This is useful +for getting the closing parenthesis of an argument list aligned +automatically. + +You can also configure @ccmode{} to insert a space automatically +between a function name and the @samp{(} you've just typed, and to +remove it automatically after typing @samp{)}, should the argument +list be empty. You don't need to have electric minor mode enabled to +get these actions. @xref{Clean-ups}. + +@item @{ +@kindex @{ +@itemx @} +@kindex @} +@findex c-electric-brace +@findex electric-brace (c-) +Typing a brace (bound to @code{c-electric-brace}) reindents the +current line. Also, one or more newlines might be inserted if +auto-newline minor mode is enabled. @xref{Auto-newlines}. +Additionally, you can configure @ccmode{} to compact excess whitespace +inserted by auto-newline mode in certain circumstances. +@xref{Clean-ups}. + +@item : +@kindex : +@findex c-electric-colon +@findex electric-colon (c-) +Typing a colon (bound to @code{c-electric-colon}) reindents the +current line. Additionally, one or more newlines might be inserted if +auto-newline minor mode is enabled. @xref{Auto-newlines}. If you +type a second colon immediately after such an auto-newline, by default +the whitespace between the two colons is removed, leaving a C++ scope +operator. @xref{Clean-ups}. + +If you prefer, you can insert @samp{::} in a single operation, +avoiding all these spurious reindentations, newlines, and clean-ups. +@xref{Other Commands}. + +@item ; +@kindex ; +@itemx , +@kindex , +@findex c-electric-semi&comma +@findex electric-semi&comma (c-) +Typing a semicolon or comma (bound to @code{c-electric-semi&comma}) +reindents the current line. Also, a newline might be inserted if +auto-newline minor mode is enabled. @xref{Auto-newlines}. +Additionally, you can configure @ccmode{} so that when auto-newline +has inserted whitespace after a @samp{@}}, it will be removed again +when you type a semicolon or comma just after it. @xref{Clean-ups}. -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Clean-ups, , Other electric commands, Auto-newline insertion -@comment node-name, next, previous,up +@end table -@subsection Clean-ups -@cindex Clean-ups -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@deffn Command c-electric-continued-statement +@findex electric-continued-statement (c-) -@dfn{Clean-ups} are a mechanism complementary to colon and brace -hanging. On the surface, it would seem that clean-ups overlap the -functionality provided by the @code{c-hanging-*-alist} variables, and -similarly, clean-ups are only enabled when auto-newline minor mode is -enabled. Clean-ups are used however to adjust code ``after-the-fact'', -i.e. to eliminate some whitespace that is inserted by electric -commands, or whitespace that contains intervening constructs. +Certain keywords are electric, causing reindentation when they are +preceded only by whitespace on the line. The keywords are those that +continue an earlier statement instead of starting a new one: +@code{else}, @code{while}, @code{catch} (only in C++ and Java) and +@code{finally} (only in Java). -@cindex literal -You can configure @ccmode{}'s clean-ups by setting the variable -@code{c-cleanup-list}, which is a list of clean-up symbols. By default, -@ccmode{} cleans up only the @code{scope-operator} construct, which -is necessary for proper C++ support. Note that clean-ups are only -performed when the construct does not occur within a literal (see -@ref{Auto-newline insertion}), and when there is nothing but whitespace -appearing between the individual components of the construct. - -@vindex c-cleanup-list -@vindex cleanup-list (c-) -There are currently only five specific constructs that @ccmode{} -can clean up, as indicated by these symbols: +An example: -@itemize @bullet -@item -@code{brace-else-brace} --- cleans up @samp{@} else @{} constructs by -placing the entire construct on a single line. Clean-up occurs when the -open brace after the @samp{else} is typed. So for example, this: @example @group - -void spam(int i) -@{ - if( i==7 ) - @{ - dosomething(); - @} - else - @{ - +for (i = 0; i < 17; i++) + if (a[i]) + res += a[i]->offset; +else @end group @end example -@noindent -appears like this after the open brace is typed: -@example -@group -void spam(int i) -@{ - if( i==7 ) @{ - dosomething(); - @} else @{ - -@end group -@end example +Here, the @code{else} should be indented like the preceding @code{if}, +since it continues that statement. @ccmode{} will automatically +reindent it after the @code{else} has been typed in full, since only +then is it possible to decide whether it's a new statement or a +continuation of the preceding @code{if}. -@item -@code{brace-elseif-brace} --- similar to the @code{brace-else-brace} -clean-up, but this cleans up @samp{@} else if (...) @{} constructs. For -example: -@example -@group +@vindex abbrev-mode +@findex abbrev-mode +@cindex Abbrev mode +@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 -void spam(int i) -@{ - if( i==7 ) - @{ - dosomething(); - @} - else if( i==3 ) @{ -@end group -@end example -@noindent -appears like this after the open brace is typed: -@example -@group +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Auto-newlines, Hungry WS Deletion, Electric Keys, Commands +@comment node-name, next, previous, up +@section Auto-newline Insertion +@cindex auto-newline +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -void spam(int i) -@{ - if( i==7 ) @{ - dosomething(); - @} else if( i==3 ) @{ +When you have @dfn{Auto-newline minor mode} enabled (@pxref{Minor +Modes}), @ccmode{} inserts newlines for you automatically (in certain +syntactic contexts) when you type a left or right brace, a colon, a +semicolon, or a comma. Sometimes a newline appears before the +character you type, sometimes after it, sometimes both. -@end group -@end example +Auto-newline only triggers when the following conditions hold: +@itemize @bullet @item -@code{empty-defun-braces} --- cleans up braces following a top-level -function or class definition that contains no body. Clean up occurs -when the closing brace is typed. Thus the following: -@example -@group - -class Spam -@{ -@} - -@end group -@end example -@noindent -is transformed into this when the close brace is typed: -@example -@group - -class Spam -@{@} - -@end group -@end example +Auto-newline minor mode is enabled, as evidenced by the indicator +@samp{a} after the mode name on the modeline (e.g. @samp{C/a} or +@samp{C/la}). @item -@code{defun-close-semi} --- cleans up the terminating semi-colon on -top-level function or class definitions when they follow a close -brace. Clean up occurs when the semi-colon is typed. -So for example, the following: -@example -@group - -class Spam -@{ -@} -; - -@end group -@end example -@noindent -is transformed into this when the semi-colon is typed: - -@example -@group - -class Spam -@{ -@}; - -@end group -@end example +The character was typed at the end of a line, or with only whitespace +after it, and possibly a @samp{\} escaping the newline. @item -@code{list-close-comma} --- cleans up commas following braces in array -and aggregate initializers. Clean up occurs when the comma is typed. +The character is not on its own line already. (This applies only to +insertion of a newline @emph{before} the character.) @item -@code{scope-operator} --- cleans up double colons which may designate a -C++ scope operator split across multiple lines@footnote{Certain C++ -constructs introduce ambiguous situations, so @code{scope-operator} -clean-ups may not always be correct. This usually only occurs when -scoped identifiers appear in switch label tags.}. Clean up occurs when -the second colon is typed. You will always want @code{scope-operator} -in the @code{c-cleanup-list} when you are editing C++ code. +@cindex literal +@cindex syntactic whitespace +The character was not typed inside of a literal @footnote{A +@dfn{literal} is defined as any comment, string, or preprocessor macro +definition. These constructs are also known as @dfn{syntactic +whitespace} since they are usually ignored when scanning C code.}. +@item +No numeric argument was supplied to the command (i.e. it was typed as +normal, with no @kbd{C-u} prefix). @end itemize +You can configure the precise circumstances in which newlines get +inserted (see @pxref{Custom Auto-newlines}). Typically, the style +system (@pxref{Styles}) will have set this up for you, so you probably +won't have to bother. -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Hungry-deletion of whitespace, Auto-fill mode interaction, Auto-newline insertion, Minor Modes -@comment node-name, next, previous,up +Sometimes @ccmode{} inserts an auto-newline where you don't want one, +such as after a @samp{@}} when you're about to type a @samp{;}. +Hungry deletion can help here (@pxref{Hungry WS Deletion}), or you can +activate an appropriate @dfn{clean-up}, which will remove the excess +whitespace after you've typed the @samp{;}. See @ref{Clean-ups} for a +full description. See also @ref{Electric Keys} for a summary of +clean-ups listed by key. -@section Hungry-deletion of whitespace -@cindex Hungry-deletion of whitespace -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -Hungry deletion of whitespace, or as it more commonly called, -@dfn{hungry-delete mode}, is a simple feature that some people find -extremely useful. In fact, you might find yourself wanting -hungry-delete in @strong{all} your editing modes! +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Hungry WS Deletion, Subword Movement, Auto-newlines, Commands +@comment node-name, next, previous, up +@section Hungry Deletion of Whitespace +@cindex hungry-deletion +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +If you want to delete an entire block of whitespace at point, you can +use @dfn{hungry deletion}. This deletes all the contiguous whitespace +either before point or after point in a single operation. +``Whitespace'' here includes tabs and newlines, but not comments or +preprocessor commands. Hungry deletion can markedly cut down on the +number of times you have to hit deletion keys when, for example, +you've made a mistake on the preceding line and have already pressed +@kbd{C-j}. + +Hungry deletion is a simple feature that some people find extremely +useful. In fact, you might find yourself wanting it in @strong{all} +your editing modes! + +Loosely speaking, in what follows, @dfn{@key{DEL}} means ``the +backspace key'' and @dfn{@key{DELETE}} means ``the forward delete +key''. This is discussed in more detail below. + +There are two different ways you can use hungry deletion: + +@table @asis +@item Using @dfn{Hungry Delete Mode} with @kbd{@key{DEL}} and @kbd{C-d} +Here you toggle Hungry Delete minor mode with @kbd{M-x +c-toggle-hungry-state}@footnote{Prior to @ccmode{} 5.31, this command +was bound to @kbd{C-c C-d}. @kbd{C-c C-d} is now the default binding +for @code{c-hungry-delete-forward}.} (@pxref{Minor Modes}.) This +makes @kbd{@key{DEL}} and @kbd{C-d} do backwards and forward hungry +deletion. + +@table @asis +@item @kbd{@key{DEL}} (@code{c-electric-backspace}) @kindex DEL -@kindex Backspace -In a nutshell, when hungry-delete mode is enabled, hitting the -@key{Backspace} key@footnote{I say ``hit the @key{Backspace} key'' but -what I really mean is ``when Emacs receives the @code{BackSpace} key -event''. The difference usually isn't significant to most users, but -advanced users will realize that under window systems such as X, any -physical key (keycap) on the keyboard can be configured to generate any -keysym, and thus any Emacs key event. Also, the use of Emacs on TTYs -will affect which keycap generates which key event. From a pedantic -point of view, here we are only concerned with the key event that -Emacs receives.} will consume all preceding whitespace, including -newlines and tabs. This can really cut down on the number of -@key{Backspace}'s you have to type if, for example you made a mistake on -the preceding line. - @findex c-electric-backspace @findex electric-backspace (c-) +This command is run by default when you hit the @kbd{DEL} key. When +hungry delete mode is enabled, it deletes any amount of whitespace in +the backwards direction. Otherwise, or when used with a prefix +argument or in a literal (@pxref{Auto-newlines}), the command just +deletes backwards in the usual way. (More precisely, it calls the +function contained in the variable @code{c-backspace-function}, +passing it the prefix argument, if any.) + +@item @code{c-backspace-function} @vindex c-backspace-function @vindex backspace-function (c-) - -@findex c-electric-delete -@findex electric-delete (c-) +@findex backward-delete-char-untabify +Hook that gets called by @code{c-electric-backspace} when it doesn't +do an ``electric'' deletion of the preceding whitespace. The default +value is @code{backward-delete-char-untabify} +(@pxref{Deletion,,,@lispref{}, @lispreftitle{}}, the function which +deletes a single character. + +@item @kbd{C-d} (@code{c-electric-delete-forward}) +@kindex C-d +@findex c-electric-delete-forward +@findex electric-delete-forward (c-) +This function, which is bound to @kbd{C-d} by default, works just like +@code{c-electric-backspace} but in the forward direction. When it +doesn't do an ``electric'' deletion of the following whitespace, it +just does @code{delete-char}, more or less. (Strictly speaking, it +calls the function in @code{c-delete-function} with the prefix +argument.) + +@item @code{c-delete-function} @vindex c-delete-function @vindex delete-function (c-) -@cindex literal +@findex delete-char +Hook that gets called by @code{c-electric-delete-forward} when it +doesn't do an ``electric'' deletion of the following whitespace. The +default value is @code{delete-char}. +@end table -@findex backward-delete-char-untabify +@item Using Distinct Bindings +The other (newer and recommended) way to use hungry deletion is to +perform @code{c-hungry-delete-backwards} and +@code{c-hungry-delete-forward} directly through their key sequences +rather than using the minor mode toggling. + +@table @asis +@item @kbd{C-c C-@key{DEL}}, or @kbd{C-c @key{DEL}} (@code{c-hungry-delete-backwards})@footnote{This command was formerly known as @code{c-hungry-backspace}.} +@kindex C-c C- +@kindex C-c +@kindex C-c C-DEL +@kindex C-c DEL +@findex c-hungry-delete-backwards +@findex hungry-delete-backwards (c-) +Delete any amount of whitespace in the backwards direction (regardless +whether hungry-delete mode is enabled or not). This command is bound +to both @kbd{C-c C-@key{DEL}} and @kbd{C-c @key{DEL}}, since the more +natural one, @kbd{C-c C-@key{DEL}}, is sometimes difficult to type at +a character terminal. + +@item @kbd{C-c C-d}, @kbd{C-c C-@key{DELETE}}, or @kbd{C-c @key{DELETE}} (@code{c-hungry-delete-forward}) +@kindex C-c C-d +@kindex C-c C- +@kindex C-c +@findex c-hungry-delete-forward +@findex hungry-delete-forward (c-) +Delete any amount of whitespace in the forward direction (regardless +whether hungry-delete mode is enabled or not). This command is bound +to both @kbd{C-c C-@key{DELETE}} and @kbd{C-c @key{DELETE}} for the +same reason as for @key{DEL} above. +@end table +@end table -By default, when you hit the @key{Backspace} key -@ccmode{} runs the command @code{c-electric-backspace}, which deletes -text in the backwards direction. When deleting a single character, or -when @key{Backspace} is hit in a literal -(see @ref{Auto-newline insertion}), -or when hungry-delete mode is disabled, the function -contained in the @code{c-backspace-function} variable is called with one -argument (the number of characters to delete). This variable is set to -@code{backward-delete-char-untabify} by default. +@kindex +@kindex +When we talk about @kbd{@key{DEL}}, and @kbd{@key{DELETE}} above, we +actually do so without connecting them to the physical keys commonly +known as @key{Backspace} and @key{Delete}. The default bindings to +those two keys depends on the flavor of (X)Emacs you are using. + +@findex c-electric-delete +@findex electric-delete (c-) +@findex c-hungry-delete +@findex hungry-delete (c-) @vindex delete-key-deletes-forward -@findex delete-char +In XEmacs 20.3 and beyond, the @key{Backspace} key is bound to +@code{c-electric-backspace} and the @key{Delete} key is bound to +@code{c-electric-delete}. You control the direction it deletes in by +setting the variable @code{delete-key-deletes-forward}, a standard +XEmacs variable. +@c This variable is encapsulated by XEmacs's (defsubst delete-forward-p ...). +When this variable is non-@code{nil}, @code{c-electric-delete} will do +forward deletion with @code{c-electric-delete-forward}, otherwise it +does backward deletion with @code{c-electric-backspace}. Similarly, +@kbd{C-c @key{Delete}} and @kbd{C-c C-@key{Delete}} are bound to +@code{c-hungry-delete} which is controlled in the same way by +@code{delete-key-deletes-forward}. + +@findex normal-erase-is-backspace-mode + +Emacs 21 and later automatically binds @key{Backspace} and +@key{Delete} to @kbd{DEL} and @kbd{C-d} according to your environment, +and @ccmode{} extends those bindings to @kbd{C-c C-@key{Backspace}} +etc. If you need to change the bindings through +@code{normal-erase-is-backspace-mode} then @ccmode{} will also adapt +its extended bindings accordingly. + +In earlier (X)Emacs versions, @ccmode{} doesn't bind either +@key{Backspace} or @key{Delete} directly. Only the key codes +@kbd{DEL} and @kbd{C-d} are bound, and it's up to the default bindings +to map the physical keys to them. You might need to modify this +yourself if the defaults are unsuitable. + +Getting your @key{Backspace} and @key{Delete} keys properly set up can +sometimes be tricky. The information in @ref{DEL Does Not +Delete,,,emacs, GNU Emacs Manual}, might be helpful if you're having +trouble with this in GNU Emacs. + + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Subword Movement, Other Commands, Hungry WS Deletion, Commands +@comment node-name, next, previous, up +@section Subword Movement and Editing +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -Similarly, hitting the @key{Delete} key runs the command -@code{c-electric-delete}. When deleting a single character, or when -@key{Delete} is hit in a literal, or when hungry-delete mode is -disabled, the function contained in the @code{c-delete-function} -variable is called with one argument (the number of characters to -delete). This variable is set to @code{delete-char} by default. +@cindex nomenclature +@cindex subword +In spite of the GNU Coding Standards, it is popular to name a symbol +by mixing uppercase and lowercase letters, e.g. @samp{GtkWidget}, +@samp{EmacsFrameClass}, or @samp{NSGraphicsContext}. Here we call +these mixed case symbols @dfn{nomenclatures}. Also, each capitalized +(or completely uppercase) part of a nomenclature is called a +@dfn{subword}. Here are some examples: + +@multitable {@samp{NSGraphicsContext}} {@samp{NS}, @samp{Graphics}, and @samp{Context}} +@c This could be converted to @headitem when we require Texinfo 4.7 +@iftex +@item @b{Nomenclature} + @tab @b{Subwords} +@end iftex +@ifnottex +@item Nomenclature + @tab Subwords +@item --------------------------------------------------------- +@end ifnottex +@item @samp{GtkWindow} + @tab @samp{Gtk} and @samp{Window} +@item @samp{EmacsFrameClass} + @tab @samp{Emacs}, @samp{Frame}, and @samp{Class} +@item @samp{NSGraphicsContext} + @tab @samp{NS}, @samp{Graphics}, and @samp{Context} +@end multitable + +The subword minor mode replaces the basic word oriented movement and +editing commands with variants that recognize subwords in a +nomenclature and treat them as separate words: + +@findex c-forward-subword +@findex forward-subword (c-) +@findex c-backward-subword +@findex backward-subword (c-) +@findex c-mark-subword +@findex mark-subword (c-) +@findex c-kill-subword +@findex kill-subword (c-) +@findex c-backward-kill-subword +@findex backward-kill-subword (c-) +@findex c-transpose-subwords +@findex transpose-subwords (c-) +@findex c-capitalize-subword +@findex capitalize-subword (c-) +@findex c-upcase-subword +@findex upcase-subword (c-) +@findex c-downcase-subword +@findex downcase-subword (c-) +@multitable @columnfractions .20 .40 .40 +@c This could be converted to @headitem when we require Texinfo 4.7 +@iftex +@item @b{Key} @tab @b{Word oriented command} @tab @b{Subword oriented command} +@end iftex +@ifnottex +@item Key @tab Word oriented command @tab Subword oriented command +@item ---------------------------------------------------------------------------- +@end ifnottex +@item @kbd{M-f} @tab @code{forward-word} @tab @code{c-forward-subword} +@item @kbd{M-b} @tab @code{backward-word} @tab @code{c-backward-subword} +@item @kbd{M-@@} @tab @code{mark-word} @tab @code{c-mark-subword} +@item @kbd{M-d} @tab @code{kill-word} @tab @code{c-kill-subword} +@item @kbd{M-DEL} @tab @code{backward-kill-word} @tab @code{c-backward-kill-subword} +@item @kbd{M-t} @tab @code{transpose-words} @tab @code{c-transpose-subwords} +@item @kbd{M-c} @tab @code{capitalize-word} @tab @code{c-capitalize-subword} +@item @kbd{M-u} @tab @code{upcase-word} @tab @code{c-upcase-subword} +@item @kbd{M-l} @tab @code{downcase-word} @tab @code{c-downcase-subword} +@end multitable + +Note that if you have changed the key bindings for the word oriented +commands in your @file{.emacs} or a similar place, the keys you have +configured are also used for the corresponding subword oriented +commands. + +Type @kbd{C-c C-w} to toggle subword mode on and off. To make the +mode turn on automatically, put the following code in your +@file{.emacs}: -However, if @code{delete-key-deletes-forward} is @code{nil}, or your -Emacs does not support separation of @key{Backspace} and @key{DEL}, then -@code{c-electric-delete} simply calls @code{c-electric-backspace}. +@example +(add-hook 'c-mode-common-hook + (lambda () (c-subword-mode 1))) +@end example +As a bonus, you can also use @code{c-subword-mode} in non-@ccmode{} +buffers by typing @kbd{M-x c-subword-mode}. @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Auto-fill mode interaction, , Hungry-deletion of whitespace, Minor Modes -@comment node-name, next, previous,up - -@section Auto-fill mode interaction -@cindex Auto-fill mode interaction +@node Other Commands, , Subword Movement, Commands +@comment node-name, next, previous, up +@section Other Commands @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -One other note about minor modes is worth mentioning here. CC Mode now -works much better with auto-fill mode (a standard Emacs minor mode) by -correctly auto-filling both line (e.g. C++ style) and block (e.g. C -style) oriented comments. When @code{auto-fill-mode} is enabled, line -oriented comments will also be auto-filled by inserting a newline at the -line break, and inserting @samp{//} at the start of the next line. +Here are the various other commands that didn't fit anywhere else: -@vindex c-comment-continuation-stars -@vindex comment-continuation-stars (c-) -@vindex comment-line-break-function -When auto-filling block oriented comments, the behavior is dependent on -the value of the variable @code{c-comment-continuation-stars}. When -this variable is @code{nil}, the old behavior for auto-filling C -comments is in effect. In this case, the line is broken by closing the -comment and starting a new comment on the next line. +@table @asis +@item @kbd{C-c .} (@code{c-set-style}) +@kindex C-c . +@findex c-set-style +@findex set-style (c-) +Switch to the specified style in the current buffer. Use like this: -If you set @code{c-comment-continuation-stars} to a string, then a long -C block comment line is broken by inserting a newline at the line break -position, and inserting this string at the beginning of the next comment -line. The default value for @code{c-comment-continuation-stars} is -@samp{* } (a star followed by a single space)@footnote{To get block -comment continuation lines indented under the block comment starter -(e.g. the @samp{/*}), it is not enough to set -@code{c-comment-continuation-stars} to the empty string. You need to do -this, but you also need to set the offset for the @code{c} syntactic -symbol to be zero.}. +@example +@kbd{C-c . @var{style-name} @key{RET}} +@end example +You can use the @key{TAB} in the normal way to do completion on the +style name. Note that all style names are case insensitive, even the +ones you define yourself. -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Commands, Customizing Indentation, Minor Modes, Top -@comment node-name, next, previous,up +Setting a style in this way does @emph{not} automatically reindent your +file. For commands that you can use to view the effect of your changes, +see @ref{Indentation Commands} and @ref{Filling and Breaking}. -@chapter Commands -@cindex Commands -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +For details of the @ccmode{} style system, see @ref{Styles}. +@item @kbd{C-c :} (@code{c-scope-operator}) +@kindex C-c : +@findex c-scope-operator +@findex scope-operator (c-) +In C++, it is also sometimes desirable to insert the double-colon scope +operator without performing the electric behavior of colon insertion. +@kbd{C-c :} does just this. -@menu -* Indentation Commands:: -* Other Commands:: -@end menu +@item @kbd{C-c C-\} (@code{c-backslash-region}) +@kindex C-c C-\ +@findex c-backslash-region +@findex backslash-region (c-) +This function inserts and aligns or deletes end-of-line backslashes in +the current region. These are typically used in multi-line macros. -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Indentation Commands, Other Commands, , Commands -@comment node-name, next, previous,up +With no prefix argument, it inserts any missing backslashes and aligns +them according to the @code{c-backslash-column} and +@code{c-backslash-max-column} variables. With a prefix argument, it +deletes any backslashes. -@section Indentation Commands -@cindex Indentation Commands -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +The function does not modify blank lines at the start of the region. If +the region ends at the start of a line, it always deletes the backslash +(if any) at the end of the previous line. -Various commands are provided which allow you to conveniently re-indent -C constructs. There are several things to -note about these indentation commands. First, when you -change your programming style, either interactively or through some -other means, your file does @emph{not} automatically get re-indented. -When you change style parameters, you will typically need to reformat -the line, expression, or buffer to see the effects of your changes. +To customize the precise workings of this command, @ref{Custom Macros}. +@end table -@cindex c-hanging- functions -@findex c-hanging-braces-alist -@findex hanging-braces-alist (c-) -Second, changing some variables have no effect on existing code, even -when you do re-indent. For example, the @code{c-hanging-*} variables -and @code{c-cleanup-list} only affect new code as it is typed in -on-the-fly, so changing @code{c-hanging-braces-alist} and re-indenting -the buffer will not adjust placement of braces already in the file. +@noindent +The recommended line breaking function, @code{c-context-line-break} +(@pxref{Filling and Breaking}), is especially nice if you edit +multiline macros frequently. When used inside a macro, it +automatically inserts and adjusts the mandatory backslash at the end +of the line to keep the macro together, and it leaves the point at the +right indentation column for the code. Thus you can write code inside +macros almost exactly as you can elsewhere, without having to bother +with the trailing backslashes. + +@table @asis +@item @kbd{C-c C-e} (@code{c-macro-expand}) +@kindex C-c C-e +@findex c-macro-expand +@findex macro-expand (c-) +This command expands C, C++, Objective C or Pike macros in the region, +using an appropriate external preprocessor program. Normally it +displays its output in a temporary buffer, but if you give it a prefix +arg (with @kbd{C-u C-c C-e}) it will overwrite the original region +with the expansion. + +The command does not work in any of the other modes, and the key +sequence is not bound in these other modes. + +@code{c-macro-expand} isn't actually part of @ccmode{}, even though it +is bound to a @ccmode{} key sequence. If you need help setting it up +or have other problems with it, you can either read its source code or +ask for help in the standard (X)Emacs forums. +@end table -@vindex c-progress-interval -@vindex progress-interval (c-) -Third, re-indenting large portions of code is currently rather -inefficient. Improvements have been made since previous releases of -@ccmode{}, and much more radical improvements are planned, but for now -you need to be aware of this @footnote{In particular, I have had people -complain about the speed with which @code{lex(1)} output is re-indented. -Lex, yacc, and other code generators usually output some pretty -perversely formatted code. @emph{Don't} try to indent this stuff!}. -Some provision has been made to at least inform you as to the progress -of the re-indentation. The variable @code{c-progress-interval} controls -how often a progress message is displayed. Set this variable to -@code{nil} to inhibit progress messages, including messages normally -printed when indentation is started and completed. - -Also, except as noted below, re-indentation is always driven by the -same mechanisms that control on-the-fly indentation of code. @xref{New -Indentation Engine} for details. +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Font Locking, Config Basics, Commands, Top +@comment node-name, next, previous, up +@chapter Font Locking +@cindex font locking +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@findex c-indent-command -@findex indent-command (c-) -@vindex c-tab-always-indent -@vindex tab-always-indent (c-) -@kindex TAB -@cindex literal -@vindex indent-tabs-mode -@vindex c-insert-tab-function -@vindex insert-tab-function (c-) -@findex tab-to-tab-stop -To indent a single line of code, use @kbd{TAB} -(@code{c-indent-command}). The behavior of this command is controlled -by the variable @code{c-tab-always-indent}. When this variable is -@code{t}, @kbd{TAB} always just indents the current line. When -@code{nil}, the line is indented only if point is at the left margin, or -on or before the first non-whitespace character on the line, otherwise -@emph{something else happens}@footnote{Actually what happens is that the -function stored in @code{c-insert-tab-function} is called. -Normally this just inserts a real tab character, or the equivalent -number of spaces, depending on the setting of the variable -@code{indent-tabs-mode}. If you preferred, you could set -@code{c-insert-tab-function} to @code{tab-to-tab-stop} for example.}. -If the value of @code{c-tab-always-indent} is something other than -@code{t} or @code{nil} (e.g. @code{'other}), then a real tab -character@footnote{The caveat about @code{indent-tabs-mode} in the -previous footnote also applies here.} is inserted only when point is -inside a literal (see @ref{Auto-newline insertion}), otherwise the line -is indented. - -@kindex M-C-q -@findex c-indent-exp -@findex indent-exp (c-) -To indent an entire balanced brace or parenthesis expression, use -@kbd{M-C-q} (@code{c-indent-exp}). Note that point should be on -the opening brace or parenthesis of the expression you want to indent. +@cindex Font Lock mode -@kindex C-c C-q -@findex c-indent-defun -@findex indent-defun (c-) -Another very convenient keystroke is @kbd{C-c C-q} -(@code{c-indent-defun}) when re-indents the entire top-level function or -class definition that encompasses point. It leaves point at the -same position within the buffer. +@ccmode{} provides font locking for its supported languages by +supplying patterns for use with Font Lock mode. This means that you +get distinct faces on the various syntactic parts such as comments, +strings, keywords and types, which is very helpful in telling them +apart at a glance and discovering syntactic errors. @xref{Font +Lock,,, emacs, GNU Emacs Manual}, for ways to enable font locking in +@ccmode{} buffers. -@kindex M-C-\ -@findex indent-region -To indent any arbitrary region of code, use @kbd{M-C-\} -(@code{indent-region}). This is a standard Emacs command, specially -tailored for C code in a @ccmode{} buffer. Note that of course, -point and mark must delineate the region you -want to indent. +@strong{Please note:} The font locking in AWK mode is currently not +integrated with the rest of @ccmode{}. Only the last section of this +chapter, @ref{AWK Mode Font Locking}, applies to AWK. The other +sections apply to the other languages. + +@menu +* Font Locking Preliminaries:: +* Faces:: +* Doc Comments:: +* AWK Mode Font Locking:: +@end menu -@kindex M-C-h -@findex c-mark-function -@findex mark-function (c-) -While not strictly an indentation function, @kbd{M-C-h} -(@code{c-mark-function}) is useful for marking the current top-level -function or class definition as the current region. @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Other Commands, , Indentation Commands, Commands -@comment node-name, next, previous,up +@node Font Locking Preliminaries, Faces, Font Locking, Font Locking +@comment node-name, next, previous, up +@section Font Locking Preliminaries +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +The font locking for most of the @ccmode{} languages were provided +directly by the Font Lock package prior to version 5.30 of @ccmode{}. +In the transition to @ccmode{} the patterns have been reworked +completely and are applied uniformly across all the languages except AWK +mode, just like the indentation rules (although each language still has +some peculiarities of its own, of course). Since the languages +previously had completely separate font locking patterns, this means +that it's a bit different in most languages now. + +The main goal for the font locking in @ccmode{} is accuracy, to provide +a dependable aid in recognizing the various constructs. Some, like +strings and comments, are easy to recognize while others, like +declarations and types, can be very tricky. @ccmode{} can go to great +lengths to recognize declarations and casts correctly, especially when +the types aren't recognized by standard patterns. This is a fairly +demanding analysis which can be slow on older hardware, and it can +therefore be disabled by choosing a lower decoration level with the +variable @code{font-lock-maximum-decoration} (@pxref{Font Lock,,, +emacs, GNU Emacs Manual}). + +@vindex font-lock-maximum-decoration + +The decoration levels are used as follows: + +@enumerate +@comment 1 +@item +Minimal font locking: Fontify only comments, strings and preprocessor +directives (in the languages that use cpp). + +@comment 2 +@item +Fast font locking: In addition to level 1, fontify keywords, simple +types and declarations that are easy to recognize. The variables +@code{*-font-lock-extra-types} (where @samp{*} is the name of the +language) are used to recognize types (see below). Documentation +comments like Javadoc are fontified according to +@code{c-doc-comment-style} (@pxref{Doc Comments}). + +Use this if you think the font locking is too slow. It's the closest +corresponding level to level 3 in the old font lock patterns. + +@comment 3 +@item +Accurate font locking: Like level 2 but uses a different approach that +can recognize types and declarations much more accurately. The +@code{*-font-lock-extra-types} variables are still used, but user +defined types are recognized correctly anyway in most cases. Therefore +those variables should be fairly restrictive and not contain patterns +that are uncertain. + +@cindex Lazy Lock mode +@cindex Just-in-time Lock mode + +This level is designed for fairly modern hardware and a font lock +support mode like Lazy Lock or Just-in-time Lock mode that only +fontifies the parts that are actually shown. Fontifying the whole +buffer at once can easily get bothersomely slow even on contemporary +hardware. +@c ACM, 2005/8/28: There should be a page in the (X)Emacs manual +@c describing these support modes. There wasn't in the +@c fourteenth edition of the Emacs manual (released with Emacs 21.3). +@c There might be one in the Emacs CVS for 22.1. +@end enumerate + +@cindex user defined types +@cindex types, user defined + +Since user defined types are hard to recognize you can provide +additional regexps to match those you use: + +@defopt c-font-lock-extra-types +@defoptx c++-font-lock-extra-types +@defoptx objc-font-lock-extra-types +@defoptx java-font-lock-extra-types +@defoptx idl-font-lock-extra-types +@defoptx pike-font-lock-extra-types +For each language there's a variable @code{*-font-lock-extra-types}, +where @samp{*} stands for the language in question. It contains a list +of regexps that matches identifiers that should be recognized as types, +e.g. @samp{\\sw+_t} to recognize all identifiers ending with @samp{_t} +as is customary in C code. Each regexp should not match more than a +single identifier. + +The default values contain regexps for many types in standard runtime +libraries that are otherwise difficult to recognize, and patterns for +standard type naming conventions like the @samp{_t} suffix in C and C++. +Java, Objective-C and Pike have as a convention to start class names +with capitals, so there are patterns for that in those languages. + +Despite the names of these variables, they are not only used for +fontification but in other places as well where @ccmode{} needs to +recognize types. +@end defopt -@section Other Commands -@cindex Other Commands + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Faces, Doc Comments, Font Locking Preliminaries, Font Locking +@comment node-name, next, previous, up +@section Faces +@cindex faces @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@ccmode{} contains other useful command for moving around in C -code. +@ccmode{} attempts to use the standard faces for programming languages +in accordance with their intended purposes as far as possible. No extra +faces are currently provided, with the exception of a replacement face +@code{c-invalid-face} for emacsen that don't provide +@code{font-lock-warning-face}. -@table @code -@findex c-beginning-of-defun -@findex beginning-of-defun (c-) -@findex beginning-of-defun -@item M-x c-beginning-of-defun -Moves point back to the least-enclosing brace. This function is -analogous to the Emacs built-in command @code{beginning-of-defun}, -except it eliminates the constraint that the top-level opening brace -must be in column zero. See @code{beginning-of-defun} for more -information. - -Depending on the coding style being used, you might prefer -@code{c-beginning-of-defun} to @code{beginning-of-defun}. If so, -consider binding @kbd{C-M-a} to the former instead. For backwards -compatibility reasons, the default binding remains in effect. +@itemize @bullet +@item +@vindex font-lock-comment-face +Normal comments are fontified in @code{font-lock-comment-face}. -@findex c-end-of-defun -@findex end-of-defun (c-) -@findex end-of-defun -@item M-x c-end-of-defun -Moves point to the end of the current top-level definition. This -function is analogous to the Emacs built-in command @code{end-of-defun}, -except it eliminates the constraint that the top-level opening brace of -the defun must be in column zero. See @code{beginning-of-defun} for more -information. - -Depending on the coding style being used, you might prefer -@code{c-end-of-defun} to @code{end-of-defun}. If so, -consider binding @kbd{C-M-e} to the former instead. For backwards -compatibility reasons, the default binding remains in effect. +@item +@vindex font-lock-doc-face +@vindex font-lock-doc-string-face +@vindex font-lock-comment-face +Comments that are recognized as documentation (@pxref{Doc Comments}) +get @code{font-lock-doc-face} (Emacs) or +@code{font-lock-doc-string-face} (XEmacs) if those faces exist. If +they don't then @code{font-lock-comment-face} is used. -@kindex C-c C-u -@findex c-up-conditional -@findex up-conditional (c-) -@item C-c C-u (c-up-conditional) -Move point back to the containing preprocessor conditional, leaving the -mark behind. A prefix argument acts as a repeat count. With a negative -argument, move point forward to the end of the containing -preprocessor conditional. When going backwards, @code{#elif} is treated -like @code{#else} followed by @code{#if}. When going forwards, -@code{#elif} is ignored.@refill +@item +@vindex font-lock-string-face +String and character literals are fontified in +@code{font-lock-string-face}. -@kindex C-c C-p -@findex c-backward-conditional -@findex backward-conditional (c-) -@item C-c C-p (c-backward-conditional) -Move point back over a preprocessor conditional, leaving the mark -behind. A prefix argument acts as a repeat count. With a negative -argument, move forward. +@item +@vindex font-lock-keyword-face +Keywords are fontified with @code{font-lock-keyword-face}. -@kindex C-c C-n -@findex c-forward-conditional -@findex forward-conditional (c-) -@item C-c C-n (c-forward-conditional) -Move point forward across a preprocessor conditional, leaving the mark -behind. A prefix argument acts as a repeat count. With a negative -argument, move backward. +@item +@vindex font-lock-function-name-face +@code{font-lock-function-name-face} is used for function names in +declarations and definitions, and classes in those contexts. It's also +used for preprocessor defines with arguments. -@kindex ESC a -@findex c-beginning-of-statement -@findex beginning-of-statement (c-) -@item M-a (c-beginning-of-statement) -Move point to the beginning of the innermost C statement. If point is -already at the beginning of a statement, it moves to the beginning of -the closest preceding statement, even if that means moving into a block -(you can use @kbd{M-C-b} to move over a balanced block). With prefix -argument @var{n}, move back @var{n} @minus{} 1 statements. - -If point is within a comment, or next to a comment, this command moves -by sentences instead of statements. - -When called from a program, this function takes three optional -arguments: the numeric prefix argument, a buffer position limit (used as -a starting point for syntactic parsing and as a limit for backward -movement), and a flag to indicate whether movement should be by -statements (if @code{nil}) or sentence (if non-@code{nil}). - -@kindex ESC e -@findex c-end-of-statement -@findex end-of-statement (c-) -@item M-e (c-end-of-statement) -Move point to the end of the innermost C statement. If point is at the -end of a statement, move to the end of the next statement, even if it's -inside a nested block (use @kbd{M-C-f} to move to the other side of the -block). With prefix argument @var{n}, move forward @var{n} @minus{} 1 -statements. - -If point is within a comment, or next to a comment, this command moves -by sentences instead of statements. - -When called from a program, this function takes three optional -arguments: the numeric prefix argument, a buffer position limit (used as -a starting point for syntactic parsing and as a limit for backward -movement), and a flag to indicate whether movement should be by -statements (if @code{nil}) or sentence (if non-@code{nil}). +@item +@vindex font-lock-variable-name-face +Variables in declarations and definitions, and other identifiers in such +variable contexts, get @code{font-lock-variable-name-face}. It's also +used for preprocessor defines without arguments. -@findex c-forward-into-nomenclature -@findex forward-into-nomenclature (c-) -@item M-x c-forward-into-nomenclature -A popular programming style, especially for object-oriented languages -such as C++ is to write symbols in a mixed case format, where the first -letter of each word is capitalized, and not separated by underscores. -E.g. @samp{SymbolsWithMixedCaseAndNoUnderlines}. +@item +@vindex font-lock-constant-face +@vindex font-lock-reference-face +Builtin constants are fontified in @code{font-lock-constant-face} if it +exists, @code{font-lock-reference-face} otherwise. As opposed to the +preceding two faces, this is used on the names in expressions, and it's +not used in declarations, even if there happen to be a @samp{const} in +them somewhere. -This command moves point forward to next capitalized word. With prefix -argument @var{n}, move @var{n} times. +@item +@vindex font-lock-type-face +@code{font-lock-type-face} is put on types (both predefined and user +defined) and classes in type contexts. -@findex c-backward-into-nomenclature -@findex backward-into-nomenclature (c-) -@item M-x c-backward-into-nomenclature -Move point backward to beginning of the next capitalized -word. With prefix argument @var{n}, move @var{n} times. If -@var{n} is negative, move forward. +@item +@vindex font-lock-constant-face +@vindex font-lock-reference-face +Label identifiers get @code{font-lock-constant-face} if it exists, +@code{font-lock-reference-face} otherwise. -@kindex C-c : -@findex c-scope-operator -@findex scope-operator (c-) -@item C-c : (c-scope-operator) -In C++, it is also sometimes desirable to insert the double-colon scope -operator without performing the electric behavior of colon insertion. -@kbd{C-c :} does just this. +@item +Name qualifiers and identifiers for scope constructs are fontified like +labels. -@kindex ESC q -@findex fill-paragraph -@vindex c-hanging-comment-starter-p -@vindex c-hanging-comment-ender-p -@vindex hanging-comment-starter-p (c-) -@vindex hanging-comment-ender-p (c-) -@item M-q (fill-paragraph) -The command is used to fill a block style (C) or line style (C++) -comment, in much the same way that text in the various text modes can be -filled@footnote{You should not use specialized filling packages such as -@code{filladapt} with CC Mode. They don't work as well for filling as -@code{c-fill-paragraph}}. You should never attempt to fill non-comment -code sections; you'll end up with garbage! Two variables control how C -style block comments are filled, specifically how the comment start and -end delimiters are handled. - -The variable @code{c-hanging-comment-starter-p} controls whether comment -start delimiters which appear on a line by themselves, end up on a line -by themselves after the fill. When the value is @code{nil}, the comment -starter will remain on its own line@footnote{It will not be placed on a -separate line if it is not already on a separate line.}. Otherwise, -text on the next line will be put on the same line as the comment -starter. This is called @dfn{hanging} because the following text hangs -on the line with the comment starter@footnote{This variable is @code{t} -by default, except in @code{java-mode}. Hanging comment starters mess -up Javadoc style comments.} - -The variable @code{c-hanging-comment-ender-p} controls the analogous -behavior for the block comment end delimiter. When the value is -@code{nil}, the comment ender will remain on its own line after the -file@footnote{The same caveat as above holds true.}. Otherwise, the -comment end delimiter will be placed at the end of the previous line. +@item +Special markup inside documentation comments are also fontified like +labels. -@end table +@item +@vindex font-lock-preprocessor-face +@vindex font-lock-builtin-face +@vindex font-lock-reference-face +Preprocessor directives get @code{font-lock-preprocessor-face} if it +exists (i.e. XEmacs). In Emacs they get @code{font-lock-builtin-face} +or @code{font-lock-reference-face}, for lack of a closer equivalent. -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Customizing Indentation, Syntactic Symbols, Commands, Top -@comment node-name, next, previous,up +@item +@vindex font-lock-warning-face +@vindex c-invalid-face +@vindex invalid-face (c-) +Some kinds of syntactic errors are fontified with +@code{font-lock-warning-face} in Emacs. In older XEmacs versions +there's no corresponding standard face, so there a special +@code{c-invalid-face} is used, which is defined to stand out sharply by +default. + +Note that it's not used for @samp{#error} or @samp{#warning} directives, +since those aren't syntactic errors in themselves. +@end itemize -@chapter Customizing Indentation -@cindex Customizing Indentation + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Doc Comments, AWK Mode Font Locking, Faces, Font Locking +@comment node-name, next, previous, up +@section Documentation Comments +@cindex documentation comments @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@vindex c-offsets-alist -@vindex offsets-alist (c-) -@cindex c-set-offset -@cindex set-offset (c-) -The variable @code{c-offsets-alist} contains the mappings between -syntactic symbols and the offsets to apply for those symbols. You -should never modify this variable directly though. Use the function -@code{c-set-offset} instead (see below for details). - -The @code{c-offsets-alist} variable is where you customize all your -indentations. You simply need to decide what additional offset you want -to add for every syntactic symbol. You can use the command @kbd{C-c -C-o} (@code{c-set-offset}) as the way to set offsets, both interactively -and from your mode hook. Also, you can set up @emph{styles} of -indentatio. Most likely, you'll -find one of the pre-defined styles will suit your needs, but if not, -this section will describe how to set up basic editing configurations. -@xref{Styles} for an explanation of how to set up named styles. - -@cindex c-basic-offset -@cindex basic-offset (c-) -As mentioned previously, the variable @code{c-offsets-alist} is an -association list of syntactic symbols and the offsets to be applied for -those symbols. In fact, these offset values can be any of an integer, a -function or lambda expression, a variable name, or one of the following -symbols: @code{+}, @code{-}, @code{++}, @code{--}, @code{*}, or -@code{/}. These symbols describe offset in multiples of the value of -the variable @code{c-basic-offset}. By defining a style's indentation -in terms of this fundamental variable, you can change the amount of -whitespace given to an indentation level while leaving the same -relationship between levels. Here are the values that the special -symbols correspond to: +There are various tools to supply documentation in the source as +specially structured comments, e.g. the standard Javadoc tool in Java. +@ccmode{} provides an extensible mechanism to fontify such comments and +the special markup inside them. + +@defopt c-doc-comment-style +@vindex doc-comment-style (c-) +This is a style variable that specifies which documentation comment +style to recognize, e.g. @code{javadoc} for Javadoc comments. + +The value may also be a list of styles, in which case all of them are +recognized simultaneously (presumably with markup cues that don't +conflict). + +The value may also be an association list to specify different comment +styles for different languages. The symbol for the major mode is then +looked up in the alist, and the value of that element is interpreted as +above if found. If it isn't found then the symbol `other' is looked up +and its value is used instead. + +The default value for @code{c-doc-comment-style} is +@w{@code{((java-mode . javadoc) (pike-mode . autodoc) (c-mode . gtkdoc))}}. + +Note that @ccmode{} uses this variable to set other variables that +handle fontification etc. That's done at mode initialization or when +you switch to a style which sets this variable. Thus, if you change it +in some other way, e.g. interactively in a CC Mode buffer, you will need +to do @kbd{M-x java-mode} (or whatever mode you're currently using) to +reinitialize. + +@findex c-setup-doc-comment-style +@findex setup-doc-comment-style (c-) +Note also that when @ccmode{} starts up, the other variables are +modified before the mode hooks are run. If you change this variable in +a mode hook, you'll have to call @code{c-setup-doc-comment-style} +afterwards to redo that work. +@end defopt + +@ccmode{} currently provides handing of the following doc comment +styles: @table @code +@item javadoc +@cindex Javadoc markup +Javadoc comments, the standard tool in Java. -@item + -@code{c-basic-offset} times 1 -@item - -@code{c-basic-offset} times -1 -@item ++ -@code{c-basic-offset} times 2 -@item -- -@code{c-basic-offset} times -2 -@item * -@code{c-basic-offset} times 0.5 -@item / -@code{c-basic-offset} times -0.5 +@item autodoc +@cindex Pike autodoc markup +For Pike autodoc markup, the standard in Pike. +@item gtkdoc +@cindex GtkDoc markup +For GtkDoc markup, widely used in the Gnome community. @end table -@vindex c-style-variables-are-local-p -@vindex style-variables-are-local-p (c-) -@noindent -So, for example, because most of the default offsets are defined in -terms of @code{+}, @code{-}, and @code{0}, if you like the general -indentation style, but you use 4 spaces instead of 2 spaces per level, -you can probably achieve your style just by changing -@code{c-basic-offset} like so (in your @file{.emacs} file): -@example +The above is by no means complete. If you'd like to see support for +other doc comment styles, please let us know (@pxref{Mailing Lists and +Bug Reports}). -(setq c-basic-offset 4) +You can also write your own doc comment fontification support to use +with @code{c-doc-comment-style}: Supply a variable or function +@code{*-font-lock-keywords} where @samp{*} is the name you want to use +in @code{c-doc-comment-style}. If it's a variable, it's prepended to +@code{font-lock-keywords}. If it's a function, it's called at mode +initialization and the result is prepended. For an example, see +@code{javadoc-font-lock-keywords} in @file{cc-fonts.el}. -@end example +If you add support for another doc comment style, please consider +contributing it - send a note to @email{bug-cc-mode@@gnu.org}. -@noindent -This would change -@example -@group -int add( int val, int incr, int doit ) -@{ - if( doit ) - @{ - return( val + incr ); - @} - return( val ); -@} +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node AWK Mode Font Locking, , Doc Comments, Font Locking +@comment node-name, next, previous, up +@section AWK Mode Font Locking +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@end group -@end example -@noindent -to -@example -@group +The general appearance of font-locking in AWK mode is much like in any +other programming mode. @xref{Faces For Font Lock,,,elisp, GNU Emacs +Lisp Reference Manual}. -int add( int val, int incr, int doit ) -@{ - if( doit ) - @{ - return( val + incr ); - @} - return( val ); -@} +The following faces are, however, used in a non-standard fashion in +AWK mode: -@end group -@end example +@table @asis +@item @code{font-lock-variable-name-face} +This face was intended for variable declarations. Since variables are +not declared in AWK, this face is used instead for AWK system +variables (such as @code{NF}) and ``Special File Names'' (such as +@code{"/dev/stderr"}). +@item @code{font-lock-builtin-face} (Emacs)/@code{font-lock-preprocessor-face} (XEmacs) +This face is normally used for preprocessor directives in @ccmode{}. +There are no such things in AWK, so this face is used instead for +standard functions (such as @code{match}). -To change indentation styles more radically, you will want to change the -value associated with the syntactic symbols in the -@code{c-offsets-alist} variable. First, I'll show you how to do that -interactively, then I'll describe how to make changes to your -@file{.emacs} file so that your changes are more permanent. +@item @code{font-lock-string-face} +As well as being used for strings, including localizable strings, +(delimited by @samp{"} and @samp{_"}), this face is also used for AWK +regular expressions (delimited by @samp{/}). -@menu -* Interactive Customization:: -* Permanent Customization:: -* Styles:: -* Advanced Customizations:: -@end menu +@item @code{font-lock-warning-face} (Emacs)/@code{c-invalid-face} (XEmacs) +This face highlights the following syntactically invalid AWK +constructs: + +@itemize @bullet +@item +An unterminated string or regular expression. Here the opening +delimiter (@samp{"} or @samp{/} or @samp{_"}) is displayed in +@code{font-lock-warning-face}. This is most noticeable when typing in a +new string/regular expression into a buffer, when the warning-face +serves as a continual reminder to terminate the construct. + +AWK mode fontifies unterminated strings/regular expressions +differently from other modes: Only the text up to the end of the line +is fontified as a string (escaped newlines being handled correctly), +rather than the text up to the next string quote. + +@item +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. + +@item +Whitespace following the @samp{\} in what otherwise looks like an +escaped newline. The @samp{\} is highlighted. +@end itemize +@end table -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Interactive Customization, Permanent Customization, , Customizing Indentation -@comment node-name, next, previous,up -@section Interactive Customization -@cindex Interactive Customization +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Config Basics, Custom Filling and Breaking, Font Locking, Top +@comment node-name, next, previous, up +@chapter Configuration Basics @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -As an example of how to customize indentation, let's change the -style of this example@footnote{In this an subsequent examples, the -original code is formatted using the @samp{gnu} style unless otherwise -indicated. @xref{Styles}.}: -@example -@group +@cindex Emacs Initialization File +@cindex Configuration +You configure @ccmode{} by setting Lisp variables and calling (and +perhaps writing) Lisp functions@footnote{DON'T PANIC!!! This isn't +difficult.}, which is usually done by adding code to an Emacs +initialization file. This file might be @file{site-start.el} or +@file{.emacs} or @file{init.el} or @file{default.el} or perhaps some +other file. @xref{Init File,,,@emacsman{}, @emacsmantitle{}}. For +the sake of conciseness, we just call this file ``your @file{.emacs}'' +throughout the rest of the manual. + +Several of these variables (currently 16), are known collectively as +@dfn{style variables}. @ccmode{} provides a special mechanism, known +as @dfn{styles} to make it easier to set these variables as a group, +to ``inherit'' settings from one style into another, and so on. Style +variables remain ordinary Lisp variables, whose values can be read and +changed independently of the style system. @xref{Style Variables}. + +There are several ways you can write the code, depending on the +precise effect you want---they are described further down on this page. +If you are new to @ccmode{}, we suggest you begin with the simplest +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 +@item +@table @asis +@item Style +@itemx Top-level command or ``customization interface'' +@itemx Hook +@itemx File Style +@end table +@end itemize -1: int add( int val, int incr, int doit ) -2: @{ -3: if( doit ) -4: @{ -5: return( val + incr ); -6: @} -7: return( val ); -8: @} +Here is a summary of the different ways of writing your configuration +settings: -@end group +@table @asis +@item Top-level commands or the ``customization interface'' +Most simply, you can write @code{setq} and similar commands at the top +level of your @file{.emacs} file. When you load a @ccmode{} buffer, +it initializes its configuration from these global values (at least, +for those settings you have given values to), so it makes sense to +have these @code{setq} commands run @emph{before} @ccmode{} is first +initialized---in particular, before any call to @code{desktop-read} +(@pxref{Saving Emacs Sessions,,, emacs, GNU Emacs Manual}). For +example, you might set c-basic-offset thus: + +@example +(setq c-basic-offset 4) @end example -@noindent -to: + +You can use the more user friendly Customization interface instead, +but this manual does not cover in detail how that works. To do this, +start by typing @kbd{M-x customize-group @key{RET} c @key{RET}}. +@xref{Easy Customization,,,@emacsman{}, @emacsmantitle{}}. +@c The following note really belongs in the Emacs manual. +Emacs normally writes the customizations at the end of your +@file{.emacs} file. If you use @code{desktop-read}, you should edit +your @file{.emacs} to place the call to @code{desktop-read} @emph{after} +the customizations. + +The first initialization of @ccmode{} puts a snapshot of the +configuration settings into the special style @code{user}. +@xref{Built-in Styles}. + +For basic use of Emacs, either of these ways of configuring is +adequate. However, the settings are then the same in all @ccmode{} +buffers and it can be clumsy to communicate them between programmers. +For more flexibility, you'll want to use one (or both) of @ccmode{}'s +more sophisticated facilities, hooks and styles. + +@item Hooks +An Emacs @dfn{hook} is a place to put Lisp functions that you want +Emacs to execute later in specific circumstances. +@xref{Hooks,,,@lispref{}, @lispreftitle{}}. @ccmode{} supplies a main +hook and a language-specific hook for each language it supports - any +functions you put onto these hooks get executed as the last part of a +buffer's initialization. Typically you put most of your customization +within the main hook, and use the language-specific hooks to vary the +customization settings between language modes. For example, if you +wanted different (non-standard) values of @code{c-basic-offset} in C +Mode and Java Mode buffers, you could do it like this: + @example @group +(defun my-c-mode-hook () + (setq c-basic-offset 3)) +(add-hook 'c-mode-hook 'my-c-mode-hook) -1: int add( int val, int incr, int doit ) -2: @{ -3: if( doit ) -4: @{ -5: return( val + incr ); -6: @} -7: return( val ); -8: @} - +(defun my-java-mode-hook () + (setq c-basic-offset 6)) +(add-hook 'java-mode-hook 'my-java-mode-hook) @end group @end example -In other words, we want to change the indentation of braces that open a -block following a condition so that the braces line up under the -conditional, instead of being indented. Notice that the construct we -want to change starts on line 4. To change the indentation of a line, -we need to see which syntactic components affect the offset calculations -for that line. Hitting @kbd{C-c C-s} on line 4 yields: -@example +See @ref{CC Hooks} for more details on the use of @ccmode{} hooks. -((substatement-open . 44)) +@item Styles +A @ccmode{} @dfn{style} is a coherent collection of customizations +with a name. At any time, exactly one style is active in each +@ccmode{} buffer, either the one you have selected or a default. +@ccmode{} is delivered with several existing styles. Additionally, +you can create your own styles, possibly based on these existing +styles. If you worked in a programming team called the ``Free +Group'', which had its own coding standards, you might well have this +in your @file{.emacs} file: +@example +(setq c-default-style '((java-mode . "java") + (awk-mode . "awk") + (other . "free-group-style"))) @end example -@findex c-set-offset -@findex set-offset (c-) -@kindex C-c C-o -@noindent -so we know that to change the offset of the open brace, we need to -change the indentation for the @code{substatement-open} syntactic -symbol. To do this interactively, just hit @kbd{C-c C-o} -(@code{c-set-offset}). This prompts you for the syntactic symbol to -change, providing a reasonable default. In this case, the default is -@code{substatement-open}, which is just the syntactic symbol we want to -change! +See @ref{Styles} for fuller details on using @ccmode{} styles and how +to create them. -After you hit return, @ccmode{} will then prompt you for the new -offset value, with the old value as the default. The default in this -case is @samp{+}, but we want no extra indentation so enter -@samp{0} and @kbd{RET}. This will associate the offset 0 with the -syntactic symbol @code{substatement-open} in the @code{c-offsets-alist} -variable. +@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. To use +it, you set certain Emacs local variables in a special block at the +end of the source file. @xref{File Styles}. + +@item Hooks with Styles +For ultimate flexibility, you can use hooks and styles together. For +example, if your team were developing a product which required a +Linux driver, you'd probably want to use the ``linux'' style for the +driver, and your own team's style for the rest of the code. You +could achieve this with code like this in your @file{.emacs}: -@findex c-indent-defun -@findex indent-defun (c-) -@kindex C-c C-q -To check your changes quickly, just hit @kbd{C-c C-q} -(@code{c-indent-defun}) to reindent the entire function. The example -should now look like: @example @group +(defun my-c-mode-hook () + (c-set-style + (if (and (buffer-file-name) + (string-match "/usr/src/linux" (buffer-file-name))) + "linux" + "free-group-style"))) +(add-hook 'c-mode-hook 'my-c-mode-hook) +@end group +@end example -1: int add( int val, int incr, int doit ) -2: @{ -3: if( doit ) -4: @{ -5: return( val + incr ); -6: @} -7: return( val ); -8: @} +In a programming team, a hook is a also a good place for each member +to put his own personal preferences. For example, you might be the +only person in your team who likes Auto-newline minor mode. You could +have it enabled by default by placing the following in your +@file{.emacs}: +@example +@group +(defun my-turn-on-auto-newline () + (c-toggle-auto-newline 1)) +(add-hook 'c-mode-common-hook 'my-turn-on-auto-newline) @end group @end example +@end table -Notice how just changing the open brace offset on line 4 is all we -needed to do. Since the other affected lines are indented relative to -line 4, they are automatically indented the way you'd expect. For more -complicated examples, this may not always work. The general approach to -take is to always start adjusting offsets for lines higher up in the -file, then re-indent and see if any following lines need further -adjustments. +@menu +* CC Hooks:: +* Style Variables:: +* Styles:: +@end menu @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Permanent Customization, Styles, Interactive Customization, Customizing Indentation -@comment node-name, next, previous,up - -@section Permanent Customization -@cindex Permanent Customization +@node CC Hooks, Style Variables, Config Basics, Config Basics +@comment node-name, next, previous, up +@section Hooks +@cindex mode hooks @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@vindex c-mode-common-hook -@vindex c-mode-hook -@vindex c++-mode-hook -@vindex objc-mode-hook -@vindex java-mode-hook -@vindex idl-mode-hook -@vindex c-initialization-hook +@c The node name is "CC Hooks" rather than "Hooks" because of a bug in +@c some older versions of Info, e.g. the info.el in GNU Emacs 21.3. +@c If you go to "Config Basics" and hit on the xref to "CC +@c Hooks" the function Info-follow-reference searches for "*Note: CC +@c Hooks" from the beginning of the page. If this node were instead +@c named "Hooks", that search would spuriously find "*Note: +@c Hooks(elisp)" and go to the wrong node. + +@ccmode{} provides several hooks that you can use to customize the +mode for your coding style. The main hook is +@code{c-mode-common-hook}; typically, you'll put the bulk of your +customizations here. In addition, each language mode has its own +hook, allowing you to fine tune your settings individually for the +different @ccmode{} languages, and there is a package initialization +hook. Finally, there is @code{c-special-indent-hook}, which enables +you to solve anomalous indentation problems. It is described in +@ref{Other Indentation}, not here. All these hooks adhere to the +standard Emacs conventions. + +When you open a buffer, @ccmode{} first initializes it with the +currently active style (@pxref{Styles}). Then it calls +@code{c-mode-common-hook}, and finally it calls the language-specific +hook. Thus, any style settings done in these hooks will override +those set by @code{c-default-style}. + +@defvar c-initialization-hook @vindex initialization-hook (c-) -@cindex hooks -To make your changes permanent, you need to add some lisp code to your -@file{.emacs} file, but first you need to decide whether your styles -should be global in every buffer, or local to each specific buffer. - -If you edit primarily one style of code, you may want to make the -@ccmode{} style variables have global values so that every buffer will -share the style settings. This will allow you to set the @ccmode{} -variables at the top level of your @file{.emacs} file, and is the -way @ccmode{} works by default. - -@vindex c-mode-common-hook -@vindex mode-common-hook (c-) -@vindex c-style-variables-are-local-p -@vindex style-variables-are-local-p (c-) -If you edit many different styles of code at -the same time, you might want to make the @ccmode{} style variables -have buffer local values. If you do this, then you will need to set any -@ccmode{} style variables in a hook function (e.g. off of -@code{c-mode-common-hook} instead of at the top level of your -@file{.emacs} file). The recommended way to do this is to set the -variable @code{c-style-variables-are-local-p} to @code{t} -@strong{before} @ccmode{} is loaded into your Emacs session. - -@ccmode{} provides several hooks that you can -use to customize the mode according to your coding style. Each language -mode has its own hook, adhering to standard Emacs major mode -conventions. There is also one general hook and one package -initialization hook: - -@itemize @bullet - -@item -@code{c-mode-hook} --- for C buffers only -@item -@code{c++-mode-hook} --- for C++ buffers only -@item -@code{objc-mode-hook} --- for Objective-C buffers only -@item -@code{java-mode-hook} --- for Java buffers only -@item -@code{idl-mode-hook} --- for IDL buffers only -@item -@code{c-mode-common-hook} --- common across all languages -@item -@code{c-initialization-hook} --- hook run only once per Emacs session, -when @ccmode{} is initialized. +Hook run only once per Emacs session, when @ccmode{} is initialized. +This is a good place to change key bindings (or add new ones) in any +of the @ccmode{} key maps. @xref{Sample .emacs File}. +@end defvar -@end itemize - -The language hooks get run as the last thing when you enter that -language mode. The @code{c-mode-common-hook} is run by all -supported modes @emph{before} the language specific hook, and thus can -contain customizations that are common across all languages. Most of -the examples in this section will assume you are using the common -hook@footnote{The interaction between @code{java-mode} and the hook -variables is slightly different than for the other modes. -@code{java-mode} sets the style (see @ref{Styles}) of the buffer to -@samp{java} @emph{before} running the @code{c-mode-common-hook} or -@code{java-mode-hook}. You need to be aware of this so that style -settings in @code{c-mode-common-hook} don't clobber your Java style.}. +@defvar c-mode-common-hook +@vindex mode-common-hook (c-) +Common hook across all languages. It's run immediately before the +language specific hook. +@end defvar + +@defvar c-mode-hook +@defvarx c++-mode-hook +@defvarx objc-mode-hook +@defvarx java-mode-hook +@defvarx idl-mode-hook +@defvarx pike-mode-hook +@defvarx awk-mode-hook +The language specific mode hooks. The appropriate one is run as the +last thing when you enter that language mode. +@end defvar + +Although these hooks are variables defined in @ccmode{}, you can give +them values before @ccmode{}'s code is loaded---indeed, this is the +only way to use @code{c-initialization-hook}. Their values aren't +overwritten when @ccmode{} gets loaded. Here's a simplified example of what you can add to your @file{.emacs} -file to make the changes described in the previous section -(@ref{Interactive Customization}) more permanent. See the Emacs manuals -for more information on customizing Emacs via hooks. @xref{Sample -.emacs File} for a more complete sample @file{.emacs} file. -@example -@group +file to do things whenever any @ccmode{} language is edited. See the +Emacs manuals for more information on customizing Emacs via hooks. +@xref{Sample .emacs File}, for a more complete sample @file{.emacs} +file. +@example (defun my-c-mode-common-hook () ;; my customizations for all of c-mode and related modes - (c-set-offset 'substatement-open 0) - ;; other customizations can go here + (no-case-fold-search) ) (add-hook 'c-mode-common-hook 'my-c-mode-common-hook) - -@end group @end example -For complex customizations, you will probably want to set up a -@emph{style} that groups all your customizations under a single -name. - @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Styles, Advanced Customizations, Permanent Customization, Customizing Indentation -@comment node-name, next, previous,up +@node Style Variables, Styles, CC Hooks, Config Basics +@comment node-name, next, previous, up +@section Style Variables +@cindex styles +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +@cindex style variables +The variables that @ccmode{}'s style system control are called +@dfn{style variables}. Note that style variables are ordinary Lisp +variables, which the style system initializes; you can change their +values at any time (e.g. in a hook function). The style system can +also also set other variables, to some extent. @xref{Styles}. + +@dfn{Style variables} are handled specially in several ways: -@section Styles -@cindex Styles +@itemize @bullet +@item +Style variables are by default buffer-local variables. However, they +can instead be made global by setting +@code{c-style-variables-are-local-p} to @code{nil} before @ccmode{} is +initialized. + +@item +@vindex c-old-style-variable-behavior +@vindex old-style-variable-behavior (c-) +The default global binding of any style variable (with two exceptions +- see below) is the special symbol @code{set-from-style}. When the +style system initializes a buffer-local copy of a style variable for a +@ccmode{} buffer, if its global binding is still that symbol then it +will be set from the current style. Otherwise it will retain its +global default@footnote{This is a big change from versions of +@ccmode{} earlier than 5.26, where such settings would get overridden +by the style system unless special precautions were taken. That was +changed since it was counterintuitive and confusing, especially to +novice users. If your configuration depends on the old overriding +behavior, you can set the variable +@code{c-old-style-variable-behavior} to non-@code{nil}.}. This +``otherwise'' happens, for example, when you've set the variable with +@code{setq} at the top level of your @file{.emacs} (@pxref{Config +Basics}). + +@item +The style variable @code{c-offsets-alist} (@pxref{c-offsets-alist}) is +an association list with an element for each syntactic symbol. It's +handled a little differently from the other style variables. It's +default global binding is the empty list @code{nil}, rather than +@code{set-from-style}. Before the style system is initialized, you +can add individual elements to @code{c-offsets-alist} by calling +@code{c-set-offset}(@pxref{c-offsets-alist}) just like you would set +other style variables with @code{setq}. Those elements will then +prevail when the style system later initializes a buffer-local copy of +@code{c-offsets-alist}. + +@item +The style variable @code{c-special-indent-hook} is also handled in a +special way. Styles can only add functions to this hook, not remove +them, so any global settings you put on it are always +preserved@footnote{This did not change in version 5.26.}. The value +you give this variable in a style definition can be either a function +or a list of functions. + +@item +The global bindings of the style variables get captured in the special +@code{user} style when the style system is first initialized. +@xref{Built-in Styles}, for details. +@end itemize + +The style variables are:@* +@code{c-indent-comment-alist}, +@code{c-indent-comments-syntactically-p} (@pxref{Indentation +Commands});@* +@code{c-doc-comment-style} (@pxref{Doc Comments});@* +@code{c-block-comment-prefix}, @code{c-comment-prefix-regexp} +(@pxref{Custom Filling and Breaking});@* +@code{c-hanging-braces-alist} (@pxref{Hanging Braces});@* +@code{c-hanging-colons-alist} (@pxref{Hanging Colons});@* +@code{c-hanging-semi&comma-criteria} (@pxref{Hanging Semicolons and +Commas});@* +@code{c-cleanup-list} (@pxref{Clean-ups});@* +@code{c-basic-offset} (@pxref{Customizing Indentation});@* +@code{c-offsets-alist} (@pxref{c-offsets-alist});@* +@code{c-comment-only-line-offset} (@pxref{Comment Line-Up});@* +@code{c-special-indent-hook}, @code{c-label-minimum-indentation} +(@pxref{Other Indentation});@* +@code{c-backslash-column}, @code{c-backslash-max-column} +(@pxref{Custom Macros}). + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Styles, , Style Variables, Config Basics +@comment node-name, next, previous, up +@section Styles +@cindex styles @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +By @dfn{style} we mean the layout of the code---things like how many +columns to indent a block of code, whether an opening brace gets +indented to the level of the code it encloses, or of the construct +that introduces it, or ``hangs'' at the end of a line. + Most people only need to edit code formatted in just a few well-defined and consistent styles. For example, their organization might impose a ``blessed'' style that all its programmers must conform to. Similarly, -people who work on GNU software will have to use the GNU coding style on -C code. Some shops are more lenient, allowing a variety of coding -styles, and as programmers come and go, there could be a number of -styles in use. For this reason, @ccmode{} makes it convenient for -you to set up logical groupings of customizations called @dfn{styles}, -associate a single name for any particular style, and pretty easily -start editing new or existing code using these styles. +people who work on GNU software will have to use the GNU coding style. +Some shops are more lenient, allowing a variety of coding styles, and as +programmers come and go, there could be a number of styles in use. For +this reason, @ccmode{} makes it convenient for you to set up logical +groupings of customizations called @dfn{styles}, associate a single name +for any particular style, and pretty easily start editing new or +existing code using these styles. @menu -* Built-in Styles:: -* Adding Styles:: -* File Styles:: +* Built-in Styles:: +* Choosing a Style:: +* Adding Styles:: +* File Styles:: @end menu @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Built-in Styles, Adding Styles, , Styles -@comment node-name, next, previous,up - -@subsection Built-in Styles -@cindex Built-in Styles +@node Built-in Styles, Choosing a Style, Styles, Styles +@comment node-name, next, previous, up +@subsection Built-in Styles +@cindex styles, built-in @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! If you're lucky, one of @ccmode{}'s built-in styles might be just -what you're looking for. These include: +what you're looking for. These are: -@itemize @bullet +@table @code +@item gnu @cindex GNU style -@item -@code{gnu} --- coding style blessed by the Free Software Foundation -for C code in GNU programs. This is the default style for all newly -created buffers, but you can change this by setting the variable -@code{c-default-style}. +Coding style blessed by the Free Software Foundation +for C code in GNU programs. +@item k&r @cindex K&R style -@item -@code{k&r} --- The classic Kernighan and Ritchie style for C code. +The classic Kernighan and Ritchie style for C code. +@item bsd @cindex BSD style -@item -@code{bsd} --- Also known as ``Allman style'' after Eric Allman. +Also known as ``Allman style'' after Eric Allman. +@item whitesmith @cindex Whitesmith style -@item -@code{whitesmith} --- Popularized by the examples that came with -Whitesmiths C, an early commercial C compiler. +Popularized by the examples that came with Whitesmiths C, an early +commercial C compiler. +@item stroustrup @cindex Stroustrup style -@item -@code{stroustrup} --- The classic Stroustrup style for C++ code. +The classic Stroustrup style for C++ code. +@item ellemtel @cindex Ellemtel style -@item -@code{ellemtel} --- Popular C++ coding standards as defined by -``Programming in C++, Rules and Recommendations'', Erik Nyquist and Mats -Henricson, Ellemtel @footnote{This document is ftp'able from -@code{euagate.eua.ericsson.se}}. - +Popular C++ coding standards as defined by ``Programming in C++, Rules +and Recommendations,'' Erik Nyquist and Mats Henricson, +Ellemtel@footnote{This document is available at +@uref{http://www.doc.ic.ac.uk/lab/cplus/c++.rules/} among other +places.}. +@c N.B. This URL was still valid at 2005/8/28 (ACM). + +@item linux @cindex Linux style -@item -@code{linux} --- C coding standard for Linux development. +C coding standard for Linux (the kernel). +@item python @cindex Python style -@item -@code{python} --- C coding standard for Python extension -modules@footnote{Python is a high level scripting language with a C/C++ -foreign function interface. For more information, see -@code{}.}. +C coding standard for Python extension modules@footnote{Python is a +high level scripting language with a C/C++ foreign function interface. +For more information, see @uref{http://www.python.org/}.}. +@item java @cindex Java style -@cindex java-mode -@item -@code{java} --- The style for editing Java code. Note that this style is -automatically installed when you enter @code{java-mode}. +The style for editing Java code. Note that the default +value for @code{c-default-style} installs this style when you enter +@code{java-mode}. +@item awk +@cindex AWK style +The style for editing AWK code. Note that the default value for +@code{c-default-style} installs this style when you enter +@code{awk-mode}. + +@item user @cindex User style -@cindex .emacs file -@vindex c-default-style -@vindex default-style (c-) -@item -@code{user} --- This is a special style for several reasons. First, if -you customize @ccmode{} by using either the new Custom interface or by -doing @code{setq}'s at the top level of your @file{.emacs} file, these -settings will be captured in the @code{user} style. Also, all other -styles implicitly inherit their settings from @code{user} style. This -means that for any styles you add via @code{c-add-style} (@xref{Adding -Styles}) you need only define the differences between your new style and -@code{user} style. - -Note however that @code{user} style is @emph{not} the default style. -@code{gnu} is the default style for all newly created buffers, but you -can change this by setting variable @code{c-default-style}. Be careful -if you customize @ccmode{} as described above; since your changes will -be captured in the @code{user} style, you will also have to change -@code{c-default-style} to "user" to see the effect of your -customizations. +This is a special style created by you. It consists of the factory +defaults for all the style variables as modified by the customizations +you do either with the Customization interface or by writing +@code{setq}s and @code{c-set-offset}s at the top level of your +@file{.emacs} file (@pxref{Config Basics}). The style system creates +this style as part of its initialization and doesn't modify it +afterwards. +@end table -@end itemize -@findex c-set-style -@findex set-style (c-) -@kindex C-c . -If you'd like to experiment with these built-in styles you can simply -type the following in a @ccmode{} buffer: -@example -@group +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Choosing a Style, Adding Styles, Built-in Styles, Styles +@comment node-name, next, previous, up +@subsection Choosing a Style +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@kbd{C-c . @var{STYLE-NAME} RET} +When you create a new buffer, its style will be set from +@code{c-default-style}. The factory default is the style @code{gnu}, +except in Java and AWK modes where it's @code{java} and @code{awk}. -@end group -@end example -@noindent -@kbd{C-c .} runs the command @code{c-set-style}. Note that all style -names are case insensitive, even the ones you define. +Remember that if you set a style variable with the Customization +interface or at the top level of your @file{.emacs} file before the +style system is initialised (@pxref{Config Basics}), this setting will +override the one that the style system would have given the variable. -Setting a style in this way does @emph{not} automatically re-indent your -file. For commands that you can use to view the effect of your changes, -see @ref{Commands}. +To set a buffer's style interactively, use the command @kbd{C-c .} +(@pxref{Other Commands}). To set it from a file's local variable +list, @ref{File Styles}. -Once you find a built-in style you like, you can make the change -permanent by adding some lisp to your @file{.emacs} file. Let's say for -example that you want to use the @samp{ellemtel} style in all your -files. You would add this: -@example -@group +@defopt c-default-style +@vindex default-style (c-) +This variable specifies which style to install by default in new +buffers. It takes either a style name string, or an association list +of major mode symbols to style names: -(defun my-c-mode-common-hook () - ;; use Ellemtel style for all C like languages - (c-set-style "ellemtel") - ;; other customizations can go here - ) -(add-hook 'c-mode-common-hook 'my-c-mode-common-hook) +@enumerate +@item +When @code{c-default-style} is a string, it must be an existing style +name. This style is then used for all modes. -@end group -@end example +@item +When @code{c-default-style} is an association list, the mode language +is looked up to find a style name string. + +@item +If @code{c-default-style} is an association list where the mode +language mode isn't found then the special symbol @samp{other} is +looked up. If it's found then the associated style is used. -@vindex c-indentation-style +@item +If @samp{other} is not found then the @samp{gnu} style is used. +@end enumerate + +In all cases, the style described in @code{c-default-style} is installed +@emph{before} the language hooks are run, so you can always override +this setting by including an explicit call to @code{c-set-style} in your +language mode hook, or in @code{c-mode-common-hook}. + +The standard value of @code{c-default-style} is @w{@code{((java-mode +. "java") (awk-mode . "awk") (other . "gnu"))}}. +@end defopt + +@defvar c-indentation-style @vindex indentation-style (c-) -Note that for BOCM compatibility, @samp{gnu} is the default -style, and any non-style based customizations you make (i.e. in -@code{c-mode-common-hook} in your -@file{.emacs} file) will be based on @samp{gnu} style unless you do -a @code{c-set-style} as the first thing in your hook. The variable -@code{c-indentation-style} always contains the buffer's current style name, -as a string. +This variable always contains the buffer's current style name, as a +string. +@end defvar @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Adding Styles, File Styles, Built-in Styles, Styles -@comment node-name, next, previous,up - -@subsection Adding Styles -@cindex Adding Styles +@node Adding Styles, File Styles, Choosing a Style, Styles +@comment node-name, next, previous, up +@subsection Adding and Amending Styles @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@vindex c-style-alist -@vindex style-alist (c-) -@findex c-add-style -@findex add-style (c-) If none of the built-in styles is appropriate, you'll probably want to -add a new @dfn{style definition}. Styles are kept in the -@code{c-style-alist} variable, but you should never modify this variable -directly. Instead, @ccmode{} provides the function -@code{c-add-style} that you can use to easily add new styles or change -existing styles. This function takes two arguments, a @var{stylename} -string, and an association list @var{description} of style -customizations. If @var{stylename} is not already in -@code{c-style-alist}, the new style is added, otherwise the style is -changed to the new @var{description}. -This function also takes an optional third argument, which if -non-@code{nil}, automatically applies the new style to the current -buffer. - -@comment TBD: The next paragraph is bogus. I really need to better -@comment document adding styles, including setting up inherited styles. +create a new @dfn{style definition}, possibly based on an existing +style. To do this, put the new style's settings into a list with the +following format - the list can then be passed as an argument to the +function @code{c-add-style}. You can see an example of a style +definition in @ref{Sample .emacs File}. + +@cindex style definition +@c @defvr {List} style definition +@table @asis +@item Structure of a Style Definition List +([@var{base-style}] [(@var{variable} . @var{value}) @dots{}]) + +Optional @var{base-style}, if present, must be a string which is the +name of the @dfn{base style} from which this style inherits. At most +one @var{base-style} is allowed in a style definition. If +@var{base-style} is not specified, the style inherits from the table +of factory default values@footnote{This table is stored internally in +the variable c-fallback-style.} instead. All styles eventually +inherit from this internal table. Style loops generate errors. The +list of pre-existing styles can be seen in @ref{Built-in Styles}. + +The dotted pairs (@var{variable} . @var{value}) each consist of a +variable and the value it is to be set to when the style is later +activated.@footnote{Note that if the variable has been given a value +by the Customization interface or a @code{setq} at the top level of +your @file{.emacs}, this value will override the one the style system +tries to give it. @xref{Config Basics}.} The variable can be either a +@ccmode{} style variable or an arbitrary Emacs variable. In the +latter case, it is @emph{not} made buffer-local by the @ccmode{} style +system. +@c @end defvr + +Two variables are treated specially in the dotted pair list: + +@table @code +@item c-offsets-alist +The value is in turn a list of dotted pairs of the form + +@example +(@r{@var{syntactic-symbol}} . @r{@var{offset}}) +@end example + +as described in @ref{c-offsets-alist}. These are passed to +@code{c-set-offset} so there is no need to set every syntactic symbol +in your style, only those that are different from the inherited style. + +@item c-special-indent-hook +The value is added to @code{c-special-indent-hook} using +@code{add-hook}, so any functions already on it are kept. If the value +is a list, each element of the list is added with @code{add-hook}. +@end table +@end table + +Styles are kept in the @code{c-style-alist} variable, but you +should never modify this variable directly. Instead, @ccmode{} +provides the function @code{c-add-style} for this purpose. + +@defun c-add-style stylename description &optional set-p +@findex add-style (c-) +Add or update a style called @var{stylename}, a string. +@var{description} is the new style definition in the form described +above. If @var{stylename} already exists in @code{c-style-alist} then +it is replaced by @var{description}. (Note, this replacement is +total. The old style is @emph{not} merged into the new one.) +Otherwise, a new style is added. + +If the optional @var{set-p} is non-@code{nil} then the new style is +applied to the current buffer as well. The use of this facility is +deprecated and it might be removed from @ccmode{} in a future release. +You should use @code{c-set-style} instead. The sample @file{.emacs} file provides a concrete example of how a new style can be added and automatically set. @xref{Sample .emacs File}. +@end defun + +@defvar c-style-alist +@vindex style-alist (c-) +This is the variable that holds the definitions for the styles. It +should not be changed directly; use @code{c-add-style} instead. +@end defvar -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node File Styles, , Adding Styles, Styles -@comment node-name, next, previous,up -@subsection File Styles -@cindex File Styles +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node File Styles, , Adding Styles, Styles +@comment node-name, next, previous, up +@subsection File Styles +@cindex styles, file local @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@cindex local variables +@cindex file local variables The Emacs manual describes how you can customize certain variables on a -per-file basis by including a @dfn{Local Variable} block at the end of -the file. So far, you've only seen a functional interface to @ccmode{} -customization, which is highly inconvenient for use in a Local Variable -block. @ccmode{} provides two variables that make it easier for you to -customize your style on a per-file basis. -It works via the standard Emacs hook variable -@code{hack-local-variables-hook}. - -@vindex c-file-style -@vindex file-style (c-) -@vindex c-file-offsets -@vindex file-offsets (c-) +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{}, +@emacsmantitle{}}). -The variable @code{c-file-style} can be set to a style name string. -When the file is visited, @ccmode{} will automatically set the -file's style to this style using @code{c-set-style}. +So far, you've only seen a functional interface for setting styles in +@ccmode{}, and this can't be used here. @ccmode{} fills the gap by +providing two variables for use in a file's local variable list. +Don't use them anywhere else! These allow you to customize the style +on a per-file basis: -@vindex c-offsets-alist -@vindex offsets-alist (c-) -@findex c-set-offset -@findex set-offset (c-) -Another variable, @code{c-file-offsets}, takes an association list -similar to what is allowed in @code{c-offsets-alist}. When the file is -visited, @ccmode{} will automatically institute these offets using -@code{c-set-offset}. +@defvar c-file-style +@vindex file-style (c-) +Set this variable to a style name string in the Local Variables list. +From now on, when you visit the file, @ccmode{} will automatically set +the file's style to this one using @code{c-set-style}. +@end defvar -Note that file style settings (i.e. @code{c-file-style}) are applied -before file offset settings (i.e. @code{c-file-offsets}). Also, if -either of these are set in a file's local variable section, all the -style variable values are made local to that buffer. +@defvar c-file-offsets +@vindex file-offsets (c-) +Set this variable (in the Local Variables list) to an association list +of the same format as @code{c-offsets-alist}. From now on, when you +visit the file, @ccmode{} will automatically institute these offsets +using @code{c-set-offset}. +@end defvar +Note that file style settings (i.e. @code{c-file-style}) are applied +before file offset settings +(i.e. @code{c-file-offsets})@footnote{Also, if either of these are set +in a file's local variable section, all the style variable values are +made local to that buffer, even if +@code{c-style-variables-are-local-p} is @code{nil}. Since this +variable is virtually always non-@code{nil} anyhow, you're unlikely to +notice this effect.}. + +If you set any variables, including style variables, by the file local +variables mechanism, these settings take priority over all other +settings, even those in your mode hooks (@pxref{CC Hooks}). If you +use @code{c-file-style} or @code{c-file-offsets} and also explicitly +set a style variable in a local variable block, the explicit setting +will take priority. @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Advanced Customizations, , Styles, Customizing Indentation -@comment node-name, next, previous,up - -@section Advanced Customizations -@cindex Advanced Customizations +@node Custom Filling and Breaking, Custom Auto-newlines, Config Basics, Top +@comment node-name, next, previous, up +@chapter Customizing Filling and Line Breaking @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@vindex c-style-alist -@vindex style-alist (c-) -@vindex c-basic-offset -@vindex basic-offset (c-) -For most users, @ccmode{} will support their coding styles with -very little need for more advanced customizations. Usually, one of the -standard styles defined in @code{c-style-alist} will do the trick. At -most, perhaps one of the syntactic symbol offsets will need to be -tweaked slightly, or maybe @code{c-basic-offset} will need to be -changed. However, some styles require a more flexible framework for -customization, and one of the real strengths of @ccmode{} is that -the syntactic analysis model provides just such a framework. This allows -you to implement custom indentation calculations for situations not -handled by the mode directly. - -@vindex c-style-variables-are-local-p -@vindex style-variables-are-local-p -Note that the style controlling variables can either have global values, -or can be buffer local (e.g. different in every buffer). If all the C -files you edit tend to have the same style, you might want to keep the -variables global. If you tend to edit files with many different styles, -you will have to make the variables buffer local. The variable -@code{c-style-variables-are-local-p} controls this. - -When @code{c-style-variables-are-local-p} is non-nil, then the style -variables will have a different settable value for each buffer, -otherwise all buffers will share the same values. By default, its value -is @code{nil} (i.e. global values). You @strong{must} set this variable -before @ccmode{} is loaded into your Emacs session, and once the -variables are made buffer local, they cannot be made global again -(unless you restart Emacs of course!) - -@menu -* Custom Indentation Functions:: -* Custom Brace and Colon Hanging:: -* Customizing Semi-colons and Commas:: -* Other Special Indentations:: -@end menu +Since there's a lot of normal text in comments and string literals, +@ccmode{} provides features to edit these like in text mode. It does +this by hooking in on the different line breaking functions and tuning +relevant variables as necessary. + +@vindex c-comment-prefix-regexp +@vindex comment-prefix-regexp (c-) +@cindex comment line prefix +@vindex comment-start +@vindex comment-end +@vindex comment-start-skip +@vindex paragraph-start +@vindex paragraph-separate +@vindex paragraph-ignore-fill-prefix +@vindex adaptive-fill-mode +@vindex adaptive-fill-regexp +@vindex adaptive-fill-first-line-regexp +To make Emacs recognize comments and treat text in them as normal +paragraphs, @ccmode{} makes several standard +variables@footnote{@code{comment-start}, @code{comment-end}, +@code{comment-start-skip}, @code{paragraph-start}, +@code{paragraph-separate}, @code{paragraph-ignore-fill-prefix}, +@code{adaptive-fill-mode}, @code{adaptive-fill-regexp}, and +@code{adaptive-fill-first-line-regexp}.} buffer-local and modifies them +according to the language syntax and the comment line prefix. + +@defopt c-comment-prefix-regexp +@vindex comment-prefix-regexp (c-) +This style variable contains the regexp used to recognize the +@dfn{comment line prefix}, which is the line decoration that starts +every line in a comment. The variable is either the comment line +prefix itself, or (more usually) an association list with different +values for different languages. The symbol for the major mode is +looked up in the alist to get the regexp for the language, and if it +isn't found then the special symbol @samp{other} is looked up instead. + +When a comment line gets divided by @kbd{M-j} or the like, @ccmode{} +inserts the comment line prefix from a neighbouring line at the start +of the new line. The default value of c-comment-prefix-regexp is +@samp{//+\\|\\**}, which matches C++ style line comments like -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Custom Indentation Functions, Custom Brace and Colon Hanging, , Advanced Customizations -@comment node-name, next, previous,up +@example +// blah blah +@end example -@subsection Custom Indentation Functions -@cindex Custom Indentation Functions -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@noindent +with two or more slashes in front of them, and the second and +subsequent lines of C style block comments like -@cindex Custom Indentation Functions -The most flexible way to customize @ccmode{} is by writing @dfn{custom -indentation functions} and associating them with specific syntactic -symbols (see @ref{Syntactic Symbols}). @ccmode{} itself uses custom -indentation functions to provide more sophisticated indentation, for -example when lining up C++ stream operator blocks: @example @group - -1: void main(int argc, char**) -2: @{ -3: cout << "There were " -4: << argc -5: << "arguments passed to the program" -6: << endl; -7: @} - +/* + * blah blah + */ @end group @end example -In this example, lines 4 through 6 are assigned the @code{stream-op} -syntactic symbol. Here, @code{stream-op} has an offset of @code{+}, and -with a @code{c-basic-offset} of 2, you can see that lines 4 through 6 -are simply indented two spaces to the right of line 3. But perhaps we'd -like @ccmode{} to be a little more intelligent so that it aligns -all the @samp{<<} symbols in lines 3 through 6. To do this, we have -to write a custom indentation function which finds the column of first -stream operator on the first line of the statement. Here is sample -lisp code implementing this: +@noindent +with zero or more stars at the beginning of every line. If you change +this variable, please make sure it still matches the comment starter +(i.e. @code{//}) of line comments @emph{and} the line prefix inside +block comments. + +@findex c-setup-paragraph-variables +@findex setup-paragraph-variables (c-) +Also note that since @ccmode{} uses the value of +@code{c-comment-prefix-regexp} to set up several other variables at +mode initialization, there won't be any effect if you just change it +inside a @ccmode{} buffer. You need to call the command +@code{c-setup-paragraph-variables} too, to update those other +variables. That's also the case if you modify +@code{c-comment-prefix-regexp} in a mode hook, since @ccmode{} will +already have set up these variables before calling the hook. +@end defopt + +In comments, @ccmode{} uses @code{c-comment-prefix-regexp} to adapt +the line prefix from the other lines in the comment. + +@vindex adaptive-fill-mode +@cindex Adaptive Fill mode +@ccmode{} uses adaptive fill mode (@pxref{Adaptive Fill,,, emacs, GNU +Emacs Manual}) to make Emacs correctly keep the line prefix when +filling paragraphs. That also makes Emacs preserve the text +indentation @emph{inside} the comment line prefix. E.g. in the +following comment, both paragraphs will be filled with the left +margins of the texts kept intact: + @example @group - -(defun c-lineup-streamop (langelem) - ;; lineup stream operators - (save-excursion - (let* ((relpos (cdr langelem)) - (curcol (progn (goto-char relpos) - (current-column)))) - (re-search-forward "<<\\|>>" (c-point 'eol) 'move) - (goto-char (match-beginning 0)) - (- (current-column) curcol)))) - +/* Make a balanced b-tree of the nodes in the incoming + * stream. But, to quote the famous words of Donald E. + * Knuth, + * + * Beware of bugs in the above code; I have only + * proved it correct, not tried it. + */ @end group @end example -@noindent -Custom indent functions take a single argument, which is a syntactic -component cons cell (see @ref{Syntactic Analysis}). The -function returns an integer offset value that will be added to the -running total indentation for the line. Note that what actually gets -returned is the difference between the column that the first stream -operator is on, and the column of the buffer relative position passed in -the function's argument. Remember that @ccmode{} automatically -adds in the column of the component's relative buffer position and we -don't the column offset added in twice. - -@cindex stream-op syntactic symbol -@findex c-lineup-streamop -@findex lineup-streamop (c-) -Now, to associate the function @code{c-lineup-streamop} with the -@code{stream-op} syntactic symbol, we can add something like the -following to our @code{c++-mode-hook}@footnote{It probably makes more -sense to add this to @code{c++-mode-hook} than @code{c-mode-common-hook} -since stream operators are only relevent for C++.}: + +@findex c-setup-filladapt +@findex setup-filladapt (c-) +@findex filladapt-mode +@vindex filladapt-mode +@cindex Filladapt mode +It's also possible to use other adaptive filling packages, notably Kyle +E. Jones' Filladapt package@footnote{It's available from +@uref{http://www.wonderworks.com/}. As of version 2.12, it does however +lack a feature that makes it work suboptimally when +@code{c-comment-prefix-regexp} matches the empty string (which it does +by default). A patch for that is available from +@uref{http://cc-mode.sourceforge.net/,, the CC Mode web site}.}, +@c 2005/11/22: The above is still believed to be the case. +which handles things like bulleted lists nicely. There's a convenience +function @code{c-setup-filladapt} that tunes the relevant variables in +Filladapt for use in @ccmode{}. Call it from a mode hook, e.g. with +something like this in your @file{.emacs}: + @example +(defun my-c-mode-common-hook () + (c-setup-filladapt) + (filladapt-mode 1)) +(add-hook 'c-mode-common-hook 'my-c-mode-common-hook) +@end example -(c-set-offset 'stream-op 'c-lineup-streamop) +@defopt c-block-comment-prefix +@vindex block-comment-prefix (c-) +@vindex c-comment-continuation-stars +@vindex comment-continuation-stars (c-) +Normally the comment line prefix inserted for a new line inside a +comment is deduced from other lines in it. However there's one +situation when there's no hint about what the prefix should look like, +namely when a block comment is broken for the first time. This style +variable@footnote{In versions before 5.26, this variable was called +@code{c-comment-continuation-stars}. As a compatibility measure, +@ccmode{} still uses the value on that variable if it's set.} is used +then as the comment prefix. It defaults to @samp{* +}@footnote{Actually, this default setting of +@code{c-block-comment-prefix} typically gets overridden by the default +style @code{gnu}, which sets it to blank. You can see the line +splitting effect described here by setting a different style, +e.g. @code{k&r} @xref{Choosing a Style}.}, which makes a comment +@example +/* Got O(n^2) here, which is a Bad Thing. */ @end example -@kindex C-c C-q -Now the function looks like this after re-indenting (using @kbd{C-c -C-q}): +@noindent +break into + @example @group +/* Got O(n^2) here, which + * is a Bad Thing. */ +@end group +@end example + +Note that it won't work to adjust the indentation by putting leading +spaces in @code{c-block-comment-prefix}, since @ccmode{} still uses the +normal indentation engine to indent the line. Thus, the right way to +fix the indentation is by customizing the @code{c} syntactic symbol. It +defaults to @code{c-lineup-C-comments}, which handles the indentation of +most common comment styles, see @ref{Line-Up Functions}. +@end defopt + +@defopt c-ignore-auto-fill +@vindex ignore-auto-fill (c-) +When auto fill mode is enabled, @ccmode{} can selectively ignore it +depending on the context the line break would occur in, e.g. to never +break a line automatically inside a string literal. This variable +takes a list of symbols for the different contexts where auto-filling +never should occur: + +@table @code +@item string +Inside a string or character literal. +@item c +Inside a C style block comment. +@item c++ +Inside a C++ style line comment. +@item cpp +Inside a preprocessor directive. +@item code +Anywhere else, i.e. in normal code. +@end table + +By default, @code{c-ignore-auto-fill} is set to @code{(string cpp +code)}, which means that when auto-fill mode is activated, +auto-filling only occurs in comments. In literals, it's often +desirable to have explicit control over newlines. In preprocessor +directives, the necessary @samp{\} escape character before the newline +is not automatically inserted, so an automatic line break would +produce invalid code. In normal code, line breaks are normally +dictated by some logical structure in the code rather than the last +whitespace character, so automatic line breaks there will produce poor +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 +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 +comments. + +Note that @ccmode{} sets @code{comment-multi-line} to @code{t} at +startup. The reason is that @kbd{M-j} could otherwise produce sequences +of single line block comments for texts that should logically be treated +as one comment, and the rest of the paragraph handling code +(e.g. @kbd{M-q} and @kbd{M-a}) can't cope with that, which would lead to +inconsistent behavior. + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Custom Auto-newlines, Clean-ups, Custom Filling and Breaking, Top +@comment node-name, next, previous, up +@chapter Customizing Auto-newlines +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +@ccmode{} determines whether to insert auto-newlines in two basically +different ways, depending on the character just typed: + +@table @asis +@item Braces and Colons +@ccmode{} first determines the syntactic context of the brace or colon +(@pxref{Syntactic Symbols}), then looks for a corresponding element in +an alist. This element specifies where to put newlines - this is any +combination of before and after the brace or colon. If no alist +element is found, newlines are inserted both before and after a brace, +but none are inserted around a colon. See @ref{Hanging Braces} and +@ref{Hanging Colons}. + +@item Semicolons and Commas +The variable @code{c-hanging-semi&comma-criteria} contains a list of +functions which determine whether to insert a newline after a newly +typed semicolon or comma. @xref{Hanging Semicolons and Commas}. +@end table -1: void main(int argc, char**) -2: @{ -3: cout << "There were " -4: << argc -5: << "arguments passed to the program" -6: << endl; -7: @} +The names of these configuration variables contain @samp{hanging} +because they let you @dfn{hang} the pertinent characters. A character +which introduces a C construct is said to @dfn{hang on the right} when +it appears at the end of a line after other code, being separated by a +line break from the construct it introduces, like the opening brace in: +@example +@group +while (i < MAX) @{ + total += entry[i]; + entry [i++] = 0; +@} @end group @end example -@vindex c-offsets-alist -@vindex offsets-alist (c-) -Custom indentation functions can be as simple or as complex as you like, -and any syntactic symbol that appears in @code{c-offsets-alist} can have -a custom indentation function associated with it. @ccmode{} comes -with several standard custom indentation functions, not all of which are -used by the default styles. +@noindent +A character @dfn{hangs on the left} when it appears at the start of +the line after the construct it closes off, like the above closing +brace. -@itemize @bullet -@findex c-lineup-arglist -@findex lineup-arglist (c-) -@item -@code{c-lineup-arglist} --- lines up function argument lines under the -argument on the previous line. +The next chapter, ``Clean-ups'', describes how to configure @ccmode{} +to remove these automatically added newlines in certain specific +circumstances. @xref{Clean-ups}. -@findex c-lineup-arglist-intro-after-paren -@findex lineup-arglist-intro-after-paren (c-) -@item -@code{c-lineup-arglist-intro-after-paren} --- similar to -@code{c-lineup-arglist}, but works for argument lists that begin with an -open parenthesis followed by a newline. +@menu +* Hanging Braces:: +* Hanging Colons:: +* Hanging Semicolons and Commas:: +@end menu -@findex c-lineup-arglist-close-under-paren -@findex lineup-arglist-close-under-paren (c-) -@item -@code{c-lineup-arglist-close-under-paren} --- set your -@code{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. -@findex c-lineup-close-paren -@findex lineup-close-paren (c-) -@item -@code{c-lineup-close-paren} --- lines up the closing parenthesis under -its corresponding open parenthesis if that one is followed by code. -Otherwise, if the open parenthesis ends its line, no indentation is -added. Works with any @code{@dots{}-close} symbol. +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Hanging Braces, Hanging Colons, Custom Auto-newlines, Custom Auto-newlines +@comment node-name, next, previous, up +@section Hanging Braces +@cindex hanging braces +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@findex c-lineup-streamop -@findex lineup-streamop (c-) -@item -@code{c-lineup-streamop} --- lines up C++ stream operators -(e.g. @samp{<<} and @samp{>>}). +To specify which kinds of braces you want auto-newlines put around, +you set the style variable @code{c-hanging-braces-alist}. Its +structure and semantics are described in this section. Details of how +to set it up, and its relationship to CC Mode's style system are given +in @ref{Style Variables}. -@findex c-lineup-multi-inher -@findex lineup-multi-inher (c-) -@item -@code{c-lineup-multi-inher} --- lines up multiple inheritance lines. +Say you wanted an auto-newline after (but not before) the following +@samp{@{}: -@findex c-indent-one-line-block -@findex indent-one-line-block (c-) -@item -@code{c-indent-one-line-block} --- adds @code{c-basic-offset} to the -indentation if the line is a one line block, otherwise 0. Intended to -be used with any opening brace symbol, e.g. @code{substatement-open}. +@example +if (foo < 17) @{ +@end example -@findex c-lineup-C-comments -@findex lineup-C-comments (c-) -@item -@code{c-lineup-C-comments} --- lines up C block comment continuation -lines. +@noindent +First you need to find the @dfn{syntactic context} of the brace---type +a @key{RET} before the brace to get it on a line of its +own@footnote{Also insert a @samp{\} at the end of the previous line if +you're in AWK Mode.}, then type @kbd{C-c C-s}. That will tell you +something like: -@findex c-lineup-comment -@findex lineup-comment (c-) -@vindex c-comment-only-line-offset -@vindex comment-only-line-offset (c-) -@item -@code{c-lineup-comment} --- lines up comment only lines according to -the variable @code{c-comment-only-line-offset}. +@example +((substatement-open 1061)) +@end example -@findex c-lineup-runin-statements -@findex lineup-runin-statements (c-) -@item -@code{c-lineup-runin-statements} --- lines up @code{statement}s for coding -standards which place the first statement in a block on the same line as -the block opening brace@footnote{Run-in style doesn't really work too -well. You might need to write your own custom indentation functions to -better support this style.}. +@noindent +So here you need to put the entry @code{(substatement-open . (after))} +into @code{c-hanging-braces-alist}. -@findex c-lineup-math -@findex lineup-math (c-) -@item -@code{c-lineup-math} --- lines up math @code{statement-cont} lines under -the previous line after the equals sign. +If you don't want any auto-newlines for a particular syntactic symbol, +put this into @code{c-hanging-braces-alist}: -@findex c-lineup-ObjC-method-call -@findex lineup-ObjC-method-call (c-) -@item -@code{c-lineup-ObjC-method-call} --- for Objective-C code, lines up -selector arguments just after the message receiver. +@example +(brace-entry-open) +@end example -@findex c-lineup-ObjC-method-args -@findex lineup-ObjC-method-args (c-) -@item -@code{c-lineup-ObjC-method-args} --- for Objective-C code, lines up the -colons that separate arguments by aligning colons vertically. +If some brace syntactic symbol is not in @code{c-hanging-brace-alist}, +its entry is taken by default as @code{(before after)}---insert a +newline both before and after the brace. In place of a +``before/after'' list you can specify a function in this alist---this +is useful when the auto newlines depend on the code around the brace. -@findex c-lineup-ObjC-method-args-2 -@findex lineup-ObjC-method-args-2 (c-) -@item -@code{c-lineup-ObjC-method-args-2} --- similar to -@code{c-lineup-ObjC-method-args} but lines up the colon on the current -line with the colon on the previous line. +@defopt c-hanging-braces-alist +@vindex hanging-braces-alist (c-) -@findex c-lineup-dont-change -@findex lineup-dont-change (c-) -@item -@code{c-lineup-dont-change} --- this lineup function returns the -indentation of the current line. Think of it as an identity function -for lineups; it is used for @code{cpp-macro-cont} lines. +This variable is an association list which maps syntactic symbols to +lists of places to insert a newline. @xref{Association +Lists,,,@lispref{}, @lispreftitle{}}. The key of each element is the +syntactic symbol, the associated value is either @code{nil}, a list, +or a function. + +@table @asis +@item The Key - the syntactic symbol +The syntactic symbols that are useful as keys in this list are +@code{brace-list-intro}, @code{statement-cont}, +@code{inexpr-class-open}, @code{inexpr-class-close}, and all the +@code{*-open} and @code{*-close} symbols. @xref{Syntactic Symbols}, +for a more detailed description of these syntactic symbols, except for +@code{inexpr-class-open} and @code{inexpr-class-close}, which aren't +actual syntactic symbols. Elements with any other value as a key get +ignored. + +The braces of anonymous inner classes in Java are given the special +symbols @code{inexpr-class-open} and @code{inexpr-class-close}, so that +they can be distinguished from the braces of normal classes@footnote{The +braces of anonymous classes produce a combination of +@code{inexpr-class}, and @code{class-open} or @code{class-close} in +normal indentation analysis.}. + +Note that the aggregate constructs in Pike mode, @samp{(@{}, @samp{@})}, +@samp{([}, @samp{])}, and @samp{(<}, @samp{>)}, do not count as brace +lists in this regard, even though they do for normal indentation +purposes. It's currently not possible to set automatic newlines on +these constructs. + +@item The associated value - the ``ACTION'' list or function +The value associated with each syntactic symbol in this association +list is called an @var{action}, which can be either a list or a +function which returns a list. @xref{Custom Braces}, for how to use +a function as a brace hanging @var{action}. + +The list @var{action} (or the list returned by @var{action} when it's +a function) contains some combination of the symbols @code{before} and +@code{after}, directing @ccmode{} where to put newlines in +relationship to the brace being inserted. Thus, if the list contains +only the symbol @code{after}, then the brace hangs on the right side +of the line, as in: -@end itemize +@example +// here, open braces always `hang' +void spam( int i ) @{ + if( i == 7 ) @{ + dosomething(i); + @} +@} +@end example -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Custom Brace and Colon Hanging, Customizing Semi-colons and Commas, Custom Indentation Functions, Advanced Customizations -@comment node-name, next, previous,up +When the list contains both @code{after} and @code{before}, the braces +will appear on a line by themselves, as shown by the close braces in +the above example. The list can also be empty, in which case newlines +are added neither before nor after the brace. +@end table + +If a syntactic symbol is missing entirely from +@code{c-hanging-braces-alist}, it's treated in the same way as an +@var{action} with a list containing @code{before} and @code{after}, so +that braces by default end up on their own line. + +For example, the default value of @code{c-hanging-braces-alist} is: + +@example +((brace-list-open) + (brace-entry-open) + (statement-cont) + (substatement-open after) + (block-close . c-snug-do-while) + (extern-lang-open after) + (namespace-open after) + (module-open after) + (composition-open after) + (inexpr-class-open after) + (inexpr-class-close before)) +@end example + +@noindent which says that @code{brace-list-open}, +@code{brace-entry-open} and @code{statement-cont}@footnote{Brace lists +inside statements, such as initializers for static array variables +inside functions in C, are recognized as @code{statement-cont}. All +normal substatement blocks are recognized with other symbols.} braces +should both hang on the right side and allow subsequent text to follow +on the same line as the brace. Also, @code{substatement-open}, +@code{extern-lang-open}, and @code{inexpr-class-open} braces should hang +on the right side, but subsequent text should follow on the next line. +The opposite holds for @code{inexpr-class-close} braces; they won't +hang, but the following text continues on the same line. Here, in the +@code{block-close} entry, you also see an example of using a function as +an @var{action}. In all other cases, braces are put on a line by +themselves. +@end defopt + +@menu +* Custom Braces:: +@end menu -@subsection Custom Brace and Colon Hanging -@cindex Custom Brace and Colon Hanging +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Custom Braces, , Hanging Braces, Hanging Braces +@comment node-name, next, previous, up +@subsection Custom Brace Hanging @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @vindex c-hanging-braces-alist @vindex hanging-braces-alist (c-) +@cindex action functions Syntactic symbols aren't the only place where you can customize -@ccmode{} with the lisp equivalent of callback functions. Brace -``hanginess'' can also be determined by custom functions associated with -syntactic symbols on the @code{c-hanging-braces-alist} variable. -Remember that @var{ACTION}'s are typically a list containing some -combination of the symbols @code{before} and @code{after} (see -@ref{Hanging Braces}). However, an @var{ACTION} can also be a function -which gets called when a brace matching that syntactic symbol is -entered. - -@cindex customizing brace hanging -These @var{ACTION} functions are called with two arguments: the -syntactic symbol for the brace, and the buffer position at which the -brace was inserted. The @var{ACTION} function is expected to return a -list containing some combination of @code{before} and @code{after}. The -function can also return @code{nil}. This return value has the normal -brace hanging semantics. +@ccmode{} with the lisp equivalent of callback functions. Remember +that @var{action}s are usually a list containing some combination of +the symbols @code{before} and @code{after} (@pxref{Hanging Braces}). +For more flexibility, you can instead specify brace ``hanginess'' by +giving a syntactic symbol an @dfn{action function} in +@code{c-hanging-braces-alist}; this function determines the +``hanginess'' of a brace, usually by looking at the code near it. + +@cindex customization, brace hanging +An action function is called with two arguments: the syntactic symbol +for the brace (e.g. @code{substatement-open}), and the buffer position +where the brace has been inserted. Point is undefined on entry to an +action function, but the function must preserve it (e.g. by using +@code{save-excursion}). The return value should be a list containing +some combination of @code{before} and @code{after}, including neither +of them (i.e. @code{nil}). + +@defvar c-syntactic-context +@vindex syntactic-context (c-) +During the call to the indentation or brace hanging @var{action} +function, this variable is bound to the full syntactic analysis list. +This might be, for example, @samp{((block-close 73))}. Don't ever +give @code{c-syntactic-context} a value yourself---this would disrupt +the proper functioning of @ccmode{}. + +This variable is also bound in three other circumstances: +(i)@w{ }when calling a c-hanging-semi&comma-criteria function +(@pxref{Hanging Semicolons and Commas}); (ii)@w{ }when calling a +line-up function (@pxref{Custom Line-Up}); (iii)@w{ }when calling a +c-special-indent-hook function (@pxref{Other Indentation}). +@end defvar As an example, @ccmode{} itself uses this feature to dynamically determine the hanginess of braces which close ``do-while'' constructs: -@example -@group +@example void do_list( int count, char** atleast_one_string ) @{ int i=0; @@ -2228,28 +3273,19 @@ void do_list( int count, char** atleast_one_string ) i++; @} while( i < count ); @} - -@end group @end example -@findex c-snug-do-while -@findex snug-do-while (c-) @ccmode{} assigns the @code{block-close} syntactic symbol to the brace that closes the @code{do} construct, and normally we'd like the line that follows a @code{block-close} brace to begin on a separate line. However, with ``do-while'' constructs, we want the @code{while} clause to follow the closing brace. To do this, we -associate the @code{block-close} symbol with the @var{ACTION} function +associate the @code{block-close} symbol with the @var{action} function @code{c-snug-do-while}: -@example +@example (defun c-snug-do-while (syntax pos) - "Dynamically calculate brace hanginess for do-while statements. -Using this function, `while' clauses that end a `do-while' block will -remain on the same line as the brace that closes that block. - -See `c-hanging-braces-alist' for how to utilize this function as an -ACTION associated with `block-close' syntax." + "Dynamically calculate brace hanginess for do-while statements." (save-excursion (let (langelem) (if (and (eq syntax 'block-close) @@ -2260,78 +3296,113 @@ ACTION associated with `block-close' syntax." (looking-at "\\[^_]"))) '(before) '(before after))))) - @end example +@findex c-snug-do-while +@findex snug-do-while (c-) This function simply looks to see if the brace closes a ``do-while'' clause and if so, returns the list @samp{(before)} indicating that a newline should be inserted before the brace, but not after it. In all other cases, it returns the list @samp{(before after)} so that the brace appears on a line by itself. -@vindex c-syntactic-context -@vindex syntactic-context (c-) -During the call to the brace hanging @var{ACTION} function, the variable -@code{c-syntactic-context} is bound to the full syntactic analysis list. +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Hanging Colons, Hanging Semicolons and Commas, Hanging Braces, Custom Auto-newlines +@comment node-name, next, previous, up +@section Hanging Colons +@cindex hanging colons +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@cindex customizing colon hanging -@vindex c-hanging-colon-alist -@vindex hanging-colon-alist (c-) -Note that for symmetry, colon hanginess should be customizable by -allowing function symbols as @var{ACTION}s on the -@code{c-hanging-colon-alist} variable. Since no use has actually been -found for this feature, it isn't currently implemented! +@cindex customization, colon hanging +@vindex c-hanging-colons-alist +@vindex hanging-colons-alist (c-) -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Customizing Semi-colons and Commas, Other Special Indentations, Custom Brace and Colon Hanging, Advanced Customizations -@comment node-name, next, previous,up +Using a mechanism similar to brace hanging (@pxref{Hanging Braces}), +colons can also be made to hang using the style variable +@code{c-hanging-colons-alist} - When a colon is typed, @ccmode +determines its syntactic context, looks this up in the alist +@code{c-changing-colons-alist} and inserts up to two newlines +accordingly. Here, however, If @ccmode fails to find an entry for a +syntactic symbol in the alist, no newlines are inserted around the +newly typed colon. -@subsection Customizing Semi-colons and Commas -@cindex Customizing Semi-colons and Commas -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@defopt c-hanging-colons-alist +@vindex hanging-colons-alist (c-) -@cindex Customizing Semi-colons and Commas -@vindex c-hanging-semi&comma-criteria -@vindex hanging-semi&comma-criteria (c-) -You can also customize the insertion of newlines after semi-colons and -commas, when the auto-newline minor mode is enabled (see @ref{Minor -Modes}). This is controlled by the variable -@code{c-hanging-semi&comma-criteria}, which contains a list of functions -that are called in the order they appear. Each function is called with -zero arguments, and is expected to return one of the following values: +@table @asis +@item The Key - the syntactic symbol +The syntactic symbols appropriate as keys in this association list +are: @code{case-label}, @code{label}, @code{access-label}, +@code{member-init-intro}, and @code{inher-intro}. @xref{Syntactic +Symbols}. Elements with any other value as a key get ignored. + +@item The associate value - the ``ACTION'' list +The @var{action} here is simply a list containing a combination of the +symbols @code{before} and @code{after}. Unlike in +@code{c-hanging-braces-alist}, functions as @var{actions} are not +supported - there doesn't seem to be any need for them. +@end table +@end defopt -@itemize @bullet -@item -non-@code{nil} --- A newline is inserted, and no more functions from the -list are called. +In C++, double-colons are used as a scope operator but because these +colons always appear right next to each other, newlines before and after +them are controlled by a different mechanism, called @dfn{clean-ups} in +@ccmode{}. @xref{Clean-ups}, for details. -@item -@code{stop} --- No more functions from the list are called, but no -newline is inserted. +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Hanging Semicolons and Commas, , Hanging Colons, Custom Auto-newlines +@comment node-name, next, previous, up +@section Hanging Semicolons and Commas +@cindex hanging semicolons +@cindex hanging commas +@cindex customization, semicolon newlines +@cindex customization, comma newlines +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@item -@code{nil} --- No determination is made, and the next function in the -list is called. +@defopt c-hanging-semi&comma-criteria +@vindex hanging-semi&comma-criteria (c-) +This style variable takes a list of functions; these get called when +you type a semicolon or comma. The functions are called in order +without arguments. When these functions are entered, point is just +after the newly inserted @samp{;} or @samp{,} and they must preserve +point (e.g., by using @code{save-excursion}). During the call, the +variable @code{c-syntactic-context} is bound to the syntactic context +of the current line@footnote{This was first introduced in @ccmode{} +5.31.} @pxref{Custom Braces}. These functions don't insert newlines +themselves, rather they direct @ccmode{} whether or not to do so. +They should return one of the following values: -@end itemize +@table @code +@item t +A newline is to be inserted after the @samp{;} or @samp{,}, and no +more functions from the list are to be called. +@item stop +No more functions from the list are to be called, and no newline is to +be inserted. +@item nil +No determination has been made, and the next function in the list is +to be called. +@end table -If every function in the list is called without a determination being -made, then no newline is added. The default value for this variable is a -list containing a single function which inserts newlines only after -semi-colons which do not appear inside parenthesis lists (i.e. those -that separate @code{for}-clause statements). +Note that auto-newlines are never inserted @emph{before} a semicolon +or comma. If every function in the list is called without a +determination being made, then no newline is added. -@findex c-semi&comma-no-newlines-before-nonblanks +In AWK mode, this variable is set by default to @code{nil}. In the +other modes, the default value is a list containing a single function, +@code{c-semi&comma-inside-parenlist}. This inserts newlines after all +semicolons, apart from those separating @code{for}-clause statements. +@end defopt + +@defun c-semi&comma-no-newlines-before-nonblanks @findex semi&comma-no-newlines-before-nonblanks (c-) -Here's an example of a criteria function, provided by @ccmode{}, that -will prevent newlines from being inserted after semicolons when there is -a non-blank following line. Otherwise, it makes no determination. To -use, add this to the front of the @code{c-hanging-semi&comma-criteria} -list. +This is an example of a criteria function, provided by @ccmode{}. It +prevents newlines from being inserted after semicolons when there is a +non-blank following line. Otherwise, it makes no determination. To +use, add this function to the front of the +@code{c-hanging-semi&comma-criteria} list. @example -@group - (defun c-semi&comma-no-newlines-before-nonblanks () (save-excursion (if (and (eq last-command-char ?\;) @@ -2339,1062 +3410,3176 @@ list. (not (looking-at "^[ \t]*$"))) 'stop nil))) - -@end group @end example +@end defun -@findex c-semi&comma-inside-parenlist -@findex c-semi&comma-no-newlines-for-oneline-inliners +@defun c-semi&comma-inside-parenlist @findex semi&comma-inside-parenlist (c-) +@defunx c-semi&comma-no-newlines-for-oneline-inliners @findex semi&comma-no-newlines-for-oneline-inliners (c-) -The default value of @code{c-hanging-semi&comma-criteria} is a list -containing just the function @code{c-semi&comma-inside-parenlist}, which -suppresses newlines after semicolons inside parenthesis lists -(e.g. @code{for}-loops). In addition to +The function @code{c-semi&comma-inside-parenlist} is what prevents +newlines from being inserted inside the parenthesis list of @code{for} +statements. In addition to @code{c-semi&comma-no-newlines-before-nonblanks} described above, @ccmode{} also comes with the criteria function @code{c-semi&comma-no-newlines-for-oneline-inliners}, which suppresses newlines after semicolons inside one-line inline method definitions -(i.e. in C++ or Java). +(e.g. in C++ or Java). +@end defun -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Other Special Indentations, , Customizing Semi-colons and Commas, Advanced Customizations -@comment node-name, next, previous,up -@subsection Other Special Indentations -@cindex Customizing Semi-colons and Commas +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Clean-ups, Indentation Engine Basics, Custom Auto-newlines, Top +@comment node-name, next, previous, up +@chapter Clean-ups +@cindex clean-ups @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@vindex c-label-minimum-indentation -@vindex label-minimum-indentation (c-) -In @samp{gnu} style (see @ref{Built-in Styles}), a minimum indentation -is imposed on lines inside top-level constructs. This minimum -indentation is controlled by the variable -@code{c-label-minimum-indentation}. The default value for this variable -is 1. +@dfn{Clean-ups} are mechanisms which remove (or exceptionally, add) +whitespace in specific circumstances and are complementary to colon +and brace hanging. You enable a clean-up by adding its symbol into +@code{c-cleanup-list}, e.g. like this: -@vindex c-special-indent-hook -@vindex special-indent-hook (c-) -One other customization variable is available in @ccmode{}: -@code{c-special-indent-hook}. This is a standard hook variable that is -called after every line is indented by @ccmode{}. You can use it -to do any special indentation or line adjustments your style dictates, -such as adding extra indentation to constructors or destructor -declarations in a class definition, etc. Note however, that you should -not change point or mark inside your @code{c-special-indent-hook} -functions (i.e. you'll probably want to wrap your function in a -@code{save-excursion}). - -Setting @code{c-special-indent-hook} in your style definition is handled -slightly differently than other variables. In your style definition, -you should set the value for -@code{c-special-indent-hook} to a function or list of functions, which -will be appended to @code{c-special-indent-hook} using @code{add-hook}. -That way, the current setting for the buffer local value of -@code{c-special-indent-hook} won't be overridden. +@example +(add-to-list 'c-cleanup-list 'space-before-funcall) +@end example -@kindex M-; -@findex indent-for-comment -@vindex c-indent-comments-syntactically-p -@vindex indent-comments-syntactically-p (c-) -@vindex comment-column +On the surface, it would seem that clean-ups overlap the functionality +provided by the @code{c-hanging-*-alist} variables. Clean-ups, +however, are used to adjust code ``after-the-fact'', i.e. to adjust +the whitespace in constructs later than when they were typed. -Normally, the standard Emacs command @kbd{M-;} -(@code{indent-for-comment}) will indent comment only lines to -@code{comment-column}. Some users however, prefer that @kbd{M-;} act -just like @kbd{TAB} for purposes of indenting comment-only lines; -i.e. they want the comments to always indent as they would for normal -code, regardless of whether @kbd{TAB} or @kbd{M-;} were used. This -behavior is controlled by the variable -@code{c-indent-comments-syntactically-p}. When @code{nil} (the -default), @kbd{M-;} indents comment-only lines to @code{comment-column}, -otherwise, they are indented just as they would be if @kbd{TAB} were -typed. +Most of the clean-ups remove automatically inserted newlines, and are +only active when auto-newline minor mode is turned on. Others will +work all the time. Note that clean-ups are only performed when there +is nothing but whitespace appearing between the individual components +of the construct, and (apart from @code{comment-close-slash}) when the +construct does not occur within a literal (@pxref{Auto-newlines}). -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Syntactic Symbols, Performance Issues, Customizing Indentation, Top -@comment node-name, next, previous,up +@defopt c-cleanup-list +@vindex cleanup-list (c-) +@cindex literal -@chapter Syntactic Symbols -@cindex Syntactic Symbols -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +You configure @ccmode{}'s clean-ups by setting the style variable +@code{c-cleanup-list}, which is a list of clean-up symbols. By +default, @ccmode{} cleans up only the @code{scope-operator} construct, +which is necessary for proper C++ support. +@end defopt -@vindex c-offsets-alist -@vindex offsets-alist (c-) +These are the clean-ups that are only active when electric and +auto-newline minor modes are enabled: -Here is a complete list of the recognized syntactic symbols as described -in the @code{c-offsets-alist} variable, along with a brief description. -More detailed descriptions follow below. +@c TBD: Would like to use some sort of @deffoo here; @table indents a +@c bit too much in dvi output. +@table @code +@item brace-else-brace +Clean up @samp{@} else @{} constructs by placing the entire construct on +a single line. Clean up occurs when the open brace after the +@samp{else} is typed. So for example, this: -@itemize @bullet -@item -@code{string} --- inside multi-line string -@item -@code{c} --- inside a multi-line C style block comment -@item -@code{defun-open} --- brace that opens a function definition -@item -@code{defun-close} --- brace that closes a function definition -@item -@code{defun-block-intro} --- the first line in a top-level defun -@item -@code{class-open} --- brace that opens a class definition -@item -@code{class-close} --- brace that closes a class definition -@item -@code{inline-open} --- brace that opens an in-class inline method -@item -@code{inline-close} --- brace that closes an in-class inline method -@item -@code{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 -between them; in C++ and Java, @code{throws} declarations and other -things can appear in this context. -@item -@code{knr-argdecl-intro} --- first line of a K&R C argument declaration -@item -@code{knr-argdecl} --- subsequent lines in a K&R C argument declaration -@item -@code{topmost-intro} --- the first line in a topmost definition -@item -@code{topmost-intro-cont} --- topmost definition continuation lines -@item -@code{member-init-intro} --- first line in a member initialization list -@item -@code{member-init-cont} --- subsequent member initialization list lines -@item -@code{inher-intro} --- first line of a multiple inheritance list -@item -@code{inher-cont} --- subsequent multiple inheritance lines -@item -@code{block-open} --- statement block open brace -@item -@code{block-close} --- statement block close brace -@item -@code{brace-list-open} --- open brace of an enum or static array list -@item -@code{brace-list-close} --- close brace of an enum or static array list -@item -@code{brace-list-intro} --- first line in an enum or static array list -@item -@code{brace-list-entry} --- subsequent lines in an enum or static array list -@item -@code{statement} --- a C statement -@item -@code{statement-cont} --- a continuation of a C statement -@item -@code{statement-block-intro} --- the first line in a new statement block -@item -@code{statement-case-intro} --- the first line in a case `block' -@item -@code{statement-case-open} --- the first line in a case block starting -with brace -@item -@code{substatement} --- the first line after a conditional -@item -@code{substatement-open} --- the brace that opens a substatement block -@item -@code{case-label} --- a case or default label -@item -@code{access-label} --- C++ access control label -@item -@code{label} --- any non-special C label -@item -@code{do-while-closure} --- the `while' that ends a -@code{do}-@code{while} construct -@item -@code{else-clause} --- the `else' of an @code{if}-@code{else} construct -@item -@code{comment-intro} --- a line containing only a comment introduction -@item -@code{arglist-intro} --- the first line in an argument list -@item -@code{arglist-cont} --- subsequent argument list lines when no arguments -follow on the same line as the the arglist opening paren -@item -@code{arglist-cont-nonempty} --- subsequent argument list lines when at -least one argument follows on the same line as the arglist opening paren -@item -@code{arglist-close} --- the solo close paren of an argument list -@item -@code{stream-op} --- lines continuing a stream operator -@item -@code{inclass} --- the line is nested inside a class definition -@item -@code{cpp-macro} --- the start of a C preprocessor macro definition -@item -@code{cpp-macro-cont} --- subsequent lines of a multi-line C -preprocessor macro definition -@item -@code{friend} --- a C++ friend declaration -@item -@code{objc-method-intro} --- the first line of an Objective-C method definition -@item -@code{objc-method-args-cont} --- lines continuing an Objective-C method -definition -@item -@code{objc-method-call-cont} --- lines continuing an Objective-C method call -@item -@code{extern-lang-open} --- brace that opens an external language block -@item -@code{extern-lang-close} --- brace that closes an external language block -@item -@code{inextern-lang} --- analogous to `inclass' syntactic symbol, but -used inside external language blocks (e.g. @code{extern "C" @{}). -@item -@code{namespace-open} --- brace that opens a C++ namespace block. -@item -@code{namespace-close} --- brace that closes a C++ namespace block. +@example +@group +void spam(int i) +@{ + if( i==7 ) @{ + dosomething(); + @} + else + @{ +@end group +@end example + +@noindent +appears like this after the last open brace is typed: + +@example +@group +void spam(int i) +@{ + if( i==7 ) @{ + dosomething(); + @} else @{ +@end group +@end example + +@item brace-elseif-brace +Similar to the @code{brace-else-brace} clean-up, but this cleans up +@samp{@} else if (...) @{} constructs. For example: + +@example +@group +void spam(int i) +@{ + if( i==7 ) @{ + dosomething(); + @} + else if( i==3 ) + @{ +@end group +@end example + +@noindent +appears like this after the last open parenthesis is typed: + +@example +@group +void spam(int i) +@{ + if( i==7 ) @{ + dosomething(); + @} else if( +@end group +@end example + +@noindent +and like this after the last open brace is typed: + +@example +@group +void spam(int i) +@{ + if( i==7 ) @{ + dosomething(); + @} else if( i==3 ) @{ +@end group +@end example + +@item brace-catch-brace +Analogous to @code{brace-elseif-brace}, but cleans up @samp{@} catch +(...) @{} in C++ and Java mode. + +@item empty-defun-braces +Clean up braces following a top-level function or class definition that +contains no body. Clean up occurs when the closing brace is typed. +Thus the following: + +@example +@group +class Spam +@{ +@} +@end group +@end example + +@noindent +is transformed into this when the close brace is typed: + +@example +@group +class Spam +@{@} +@end group +@end example + +@item defun-close-semi +Clean up the terminating semicolon on top-level function or class +definitions when they follow a close brace. Clean up occurs when the +semicolon is typed. So for example, the following: + +@example +@group +class Spam +@{ +... +@} +; +@end group +@end example + +@noindent +is transformed into this when the semicolon is typed: + +@example +@group +class Spam +@{ +... +@}; +@end group +@end example + +@item list-close-comma +Clean up commas following braces in array and aggregate initializers. +Clean up occurs when the comma is typed. The space before the comma +is zapped just like the space before the semicolon in +@code{defun-close-semi}. + +@item scope-operator +Clean up double colons which might designate a C++ scope operator split +across multiple lines@footnote{Certain C++ constructs introduce +ambiguous situations, so @code{scope-operator} clean-ups might not +always be correct. This usually only occurs when scoped identifiers +appear in switch label tags.}. Clean up occurs when the second colon is +typed. You will always want @code{scope-operator} in the +@code{c-cleanup-list} when you are editing C++ code. + +@item one-liner-defun +Clean up a single line of code enclosed by defun braces by removing +the whitespace before and after the code. The clean-up happens when +the closing brace is typed. If the variable +@code{c-max-one-liner-length} is set, the cleanup is only done if the +resulting line would be no longer than the value of that variable. + +For example, consider this AWK code: + +@example +@group +BEGIN @{ + FS = "\t" # use as a field separator +@} +@end group +@end example + +@noindent +It gets compacted to the following when the closing brace is typed: + +@example +@group +BEGIN @{FS = "\t"@} # use as a field separator +@end group +@end example + +@defopt c-max-one-liner-length +@vindex max-one-liner-length (c-) +The maximum length of the resulting line for which the clean-up +@code{one-liner-defun} will be triggered. This length is that of the entire +line, including any leading whitespace and any trailing comment. Its +default value is 80. If the value is zero or @code{nil}, no limit +applies. +@end defopt +@end table + +The following clean-ups are always active when they occur on +@code{c-cleanup-list}, regardless of whether Electric minor mode or +Auto-newline minor mode are enabled: + +@table @code +@item space-before-funcall +Insert a space between the function name and the opening parenthesis +of a function call. This produces function calls in the style +mandated by the GNU coding standards, e.g. @samp{signal@w{ }(SIGINT, +SIG_IGN)} and @samp{abort@w{ }()}. Clean up occurs when the opening +parenthesis is typed. This clean-up should never be active in AWK +Mode, since such a space is syntactically invalid for user defined +functions. + +@item compact-empty-funcall +Clean up any space between the function name and the opening parenthesis +of a function call that has no arguments. This is typically used +together with @code{space-before-funcall} if you prefer the GNU function +call style for functions with arguments but think it looks ugly when +it's only an empty parenthesis pair. I.e. you will get @samp{signal +(SIGINT, SIG_IGN)}, but @samp{abort()}. Clean up occurs when the +closing parenthesis is typed. + +@item comment-close-slash +When inside a block comment, terminate the comment when you type a slash +at the beginning of a line (i.e. immediately after the comment prefix). +This clean-up removes whitespace preceding the slash and if needed, +inserts a star to complete the token @samp{*/}. Type @kbd{C-q /} in this +situation if you just want a literal @samp{/} inserted. +@end table + + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Indentation Engine Basics, Customizing Indentation, Clean-ups, Top +@comment node-name, next, previous, up +@chapter Indentation Engine Basics +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +This chapter will briefly cover how @ccmode{} indents lines of code. +It is helpful to understand the indentation model being used so that +you will know how to customize @ccmode{} for your personal coding +style. All the details are in @ref{Customizing Indentation}. + +@ccmode{} has an indentation engine that provides a flexible and +general mechanism for customizing indentation. When @ccmode{} indents +a line of code, it separates its calculations into two steps: + +@enumerate @item -@code{innamespace} --- analogous to `inextern-lang' syntactic symbol, -but used inside C++ namespace blocks. +@cindex syntactic symbol +@cindex anchor position +It analyzes the line to determine its @dfn{syntactic symbol(s)} (the +kind of language construct it's looking at) and its @dfn{anchor +position} (the position earlier in the file that @ccmode{} will indent +the line relative to). The anchor position might be the location of +an opening brace in the previous line, for example. @xref{Syntactic +Analysis}. @item -@code{template-args-cont} --- C++ template argument list continuations -@end itemize +@cindex offsets +@cindex indentation offset specifications +It looks up the syntactic symbol(s) in the configuration to get the +corresponding @dfn{offset(s)}. The symbol @code{+}, which means +``indent this line one more level'' is a typical offset. @ccmode{} +then applies these offset(s) to the anchor position, giving the +indentation for the line. The different sorts of offsets are +described in @ref{c-offsets-alist}. +@end enumerate + +In exceptional circumstances, the syntax directed indentation +described here may be a nuisance rather than a help. You can disable +it by setting @code{c-syntactic-indentation} to @code{nil}. (To set +the variable interactively, @ref{Minor Modes}). + +@defopt c-syntactic-indentation +@vindex syntactic-indentation (c-) +When this is non-@code{nil} (which it is by default), the indentation +of code is done according to its syntactic structure. When it's +@code{nil}, every line is just indented to the same level as the +previous one, and @kbd{TAB} (@code{c-indent-command}) adjusts the +indentation in steps of @code{c-basic-offset}. The current style +(@pxref{Config Basics}) then has no effect on indentation, nor do any +of the variables associated with indentation, not even +@code{c-special-indent-hook}. +@end defopt + +@menu +* Syntactic Analysis:: +* Syntactic Symbols:: +* Indentation Calculation:: +@end menu + + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Syntactic Analysis, Syntactic Symbols, Indentation Engine Basics, Indentation Engine Basics +@comment node-name, next, previous, up +@section Syntactic Analysis +@cindex syntactic analysis +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +@cindex syntactic element +@cindex syntactic context +The first thing @ccmode{} does when indenting a line of code, is to +analyze the line, determining the @dfn{syntactic context} of the +(first) construct on that line. It's a list of @dfn{syntactic +elements}, where each syntactic element in turn is a list@footnote{In +@ccmode 5.28 and earlier, a syntactic element was a dotted pair; the +cons was the syntactic symbol and the cdr was the anchor position. +For compatibility's sake, the parameter passed to a line-up function +still has this dotted pair form (@pxref{Custom Line-Up}).} Here is a +brief and typical example: + +@example +((defun-block-intro 1959)) +@end example + +@cindex syntactic symbol +@noindent +The first thing inside each syntactic element is always a +@dfn{syntactic symbol}. It describes the kind of construct that was +recognized, e.g. @code{statement}, @code{substatement}, +@code{class-open}, @code{class-close}, etc. @xref{Syntactic Symbols}, +for a complete list of currently recognized syntactic symbols and +their semantics. The remaining entries are various data associated +with the recognized construct - there might be zero or more. + +@cindex anchor position +Conceptually, a line of code is always indented relative to some +position higher up in the buffer (typically the indentation of the +previous line). That position is the @dfn{anchor position} in the +syntactic element. If there is an entry after the syntactic symbol in +the syntactic element list then it's either nil or that anchor position. + +Here is an example. Suppose we had the following code as the only thing +in a C++ buffer @footnote{The line numbers in this and future examples +don't actually appear in the buffer, of course!}: + +@example + 1: void swap( int& a, int& b ) + 2: @{ + 3: int tmp = a; + 4: a = b; + 5: b = tmp; + 6: @} +@end example + +@noindent +We can use @kbd{C-c C-s} (@code{c-show-syntactic-information}) to +report what the syntactic analysis is for the current line: + +@table @asis +@item @kbd{C-c C-s} (@code{c-show-syntactic-information}) +@kindex C-c C-s +@findex c-show-syntactic-information +@findex show-syntactic-information (c-) +This command calculates the syntactic analysis of the current line and +displays it in the minibuffer. The command also highlights the anchor +position(s). +@end table + + Running this command on line 4 of this example, we'd see in the echo +area@footnote{With a universal argument (i.e. @kbd{C-u C-c C-s}) the +analysis is inserted into the buffer as a comment on the current +line.}: + +@example +((statement 35)) +@end example + +@noindent +and the @samp{i} of @code{int} on line 3 would be highlighted. This +tells us that the line is a statement and it is indented relative to +buffer position 35, the highlighted position. If you were to move +point to line 3 and hit @kbd{C-c C-s}, you would see: + +@example +((defun-block-intro 29)) +@end example + +@noindent +This indicates that the @samp{int} line is the first statement in a top +level function block, and is indented relative to buffer position 29, +which is the brace just after the function header. + +Here's another example: + +@example + 1: int add( int val, int incr, int doit ) + 2: @{ + 3: if( doit ) + 4: @{ + 5: return( val + incr ); + 6: @} + 7: return( val ); + 8: @} +@end example + +@noindent +Hitting @kbd{C-c C-s} on line 4 gives us: + +@example +((substatement-open 46)) +@end example + +@cindex substatement +@cindex substatement block +@noindent +which tells us that this is a brace that @emph{opens} a substatement +block. @footnote{A @dfn{substatement} is the line after a +conditional statement, such as @code{if}, @code{else}, @code{while}, +@code{do}, @code{switch}, etc. A @dfn{substatement +block} is a brace block following one of these conditional statements.} + +@cindex comment-only line +Syntactic contexts can contain more than one element, and syntactic +elements need not have anchor positions. The most common example of +this is a @dfn{comment-only line}: + +@example + 1: void draw_list( List& drawables ) + 2: @{ + 3: // call the virtual draw() method on each element in list + 4: for( int i=0; i < drawables.count(), ++i ) + 5: @{ + 6: drawables[i].draw(); + 7: @} + 8: @} +@end example + +@noindent +Hitting @kbd{C-c C-s} on line 3 of this example gives: + +@example +((comment-intro) (defun-block-intro 46)) +@end example + +@noindent +and you can see that the syntactic context contains two syntactic +elements. Notice that the first element, @samp{(comment-intro)}, has no +anchor position. + + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Syntactic Symbols, Indentation Calculation, Syntactic Analysis, Indentation Engine Basics +@comment node-name, next, previous, up +@section Syntactic Symbols +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +@cindex syntactic symbols, brief list +@vindex c-offsets-alist +@vindex offsets-alist (c-) +This section is a complete list of the syntactic symbols which appear +in the @code{c-offsets-alist} style variable, along with brief +descriptions. The previous section (@pxref{Syntactic Analysis}) +states what syntactic symbols are and how the indentation engine uses +them. + +More detailed descriptions of these symbols, together with snippets of +source code to which they apply, appear in the examples in the +subsections below. Note that, in the interests of brevity, the anchor +position associated with most syntactic symbols is @emph{not} +specified. In cases of doubt, type @kbd{C-c C-s} on a pertinent +line---this highlights the anchor position. + +@ssindex -open symbols +@ssindex -close symbols +@ssindex -block-intro symbols +The syntactic symbols which indicate brace constructs follow a general +naming convention. When a line begins with an open or close brace, +its syntactic symbol will contain the suffix @code{-open} or +@code{-close} respectively. The first line within the brace block +construct will contain the suffix @code{-block-intro}. + +@ssindex -intro symbols +@ssindex -cont symbols +In constructs which can span several lines, a distinction is usually +made between the first line that introduces the construct and the +lines that continue it. The syntactic symbols that indicate these +lines will contain the suffixes @code{-intro} or @code{-cont} +respectively. + +The best way to understand how all this works is by looking at some +examples. Remember that you can see the syntax of any source code +line by using @kbd{C-c C-s}. + +@table @code +@item string +Inside a multiline string. @ref{Literal Symbols}. +@item c +Inside a multiline C style block comment. @ref{Literal Symbols}. +@item defun-open +Brace that opens a top-level function definition. @ref{Function +Symbols}. +@item defun-close +Brace that closes a top-level function definition. @ref{Function +Symbols}. +@item defun-block-intro +The first line in a top-level defun. @ref{Function Symbols}. +@item class-open +Brace that opens a class definition. @ref{Class Symbols}. +@item class-close +Brace that closes a class definition. @ref{Class Symbols}. +@item inline-open +Brace that opens an in-class inline method. @ref{Class Symbols}. +@item inline-close +Brace that closes an in-class inline method. @ref{Class Symbols}. +@item 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, @code{throws} declarations and other things +can appear here. @ref{Literal Symbols}. @c @emph{FIXME!!! Can it not +@c go somewhere better?} +@item knr-argdecl-intro +First line of a K&R C argument declaration. @ref{K&R Symbols}. +@item knr-argdecl +Subsequent lines in a K&R C argument declaration. @ref{K&R Symbols}. +@item topmost-intro +The first line in a ``topmost'' definition. @ref{Function Symbols}. +@item topmost-intro-cont +Topmost definition continuation lines. This is only used in the parts +that aren't covered by other symbols such as @code{func-decl-cont} and +@code{knr-argdecl}. @ref{Function Symbols}. +@item member-init-intro +First line in a member initialization list. @ref{Class Symbols}. +@item member-init-cont +Subsequent member initialization list lines. @ref{Class Symbols}. +@item inher-intro +First line of a multiple inheritance list. @ref{Class Symbols}. +@item inher-cont +Subsequent multiple inheritance lines. @ref{Class Symbols}. +@item block-open +Statement block open brace. @ref{Literal Symbols}. +@item block-close +Statement block close brace. @ref{Conditional Construct Symbols}. +@item brace-list-open +Open brace of an enum or static array list. @ref{Brace List Symbols}. +@item brace-list-close +Close brace of an enum or static array list. @ref{Brace List Symbols}. +@item brace-list-intro +First line in an enum or static array list. @ref{Brace List Symbols}. +@item brace-list-entry +Subsequent lines in an enum or static array list. @ref{Brace List +Symbols}. +@item brace-entry-open +Subsequent lines in an enum or static array list where the line begins +with an open brace. @ref{Brace List Symbols}. +@item statement +A statement. @ref{Function Symbols}. +@item statement-cont +A continuation of a statement. @ref{Function Symbols}. +@item statement-block-intro +The first line in a new statement block. @ref{Conditional Construct +Symbols}. +@item statement-case-intro +The first line in a case block. @ref{Switch Statement Symbols}. +@item statement-case-open +The first line in a case block that starts with a brace. @ref{Switch +Statement Symbols}. +@item substatement +The first line after a conditional or loop construct. +@ref{Conditional Construct Symbols}. +@item substatement-open +The brace that opens a substatement block. @ref{Conditional Construct +Symbols}. +@item substatement-label +The first line after a conditional or loop construct if it's a label. +@ref{Conditional Construct Symbols}. +@item case-label +A label in a @code{switch} block. @ref{Switch Statement Symbols}. +@item access-label +C++ access control label. @ref{Class Symbols}. +@item label +Any other label. @ref{Literal Symbols}. +@item do-while-closure +The @code{while} line that ends a @code{do}-@code{while} construct. +@ref{Conditional Construct Symbols}. +@item else-clause +The @code{else} line of an @code{if}-@code{else} construct. +@ref{Conditional Construct Symbols}. +@item catch-clause +The @code{catch} or @code{finally} (in Java) line of a +@code{try}-@code{catch} construct. @ref{Conditional Construct +Symbols}. +@item comment-intro +A line containing only a comment introduction. @ref{Literal Symbols}. +@item arglist-intro +The first line in an argument list. @ref{Paren List Symbols}. +@item arglist-cont +Subsequent argument list lines when no arguments follow on the same +line as the arglist opening paren. @ref{Paren List Symbols}. +@item arglist-cont-nonempty +Subsequent argument list lines when at least one argument follows on +the same line as the arglist opening paren. @ref{Paren List Symbols}. +@item arglist-close +The solo close paren of an argument list. @ref{Paren List Symbols}. +@item stream-op +Lines continuing a stream operator (C++ only). @ref{Literal +Symbols}. @c @emph{FIXME!!! Can this not be moved somewhere better?} +@item inclass +The line is nested inside a class definition. @ref{Class Symbols}. +@item cpp-macro +The start of a preprocessor macro definition. @ref{Literal Symbols}. +@item cpp-define-intro +The first line inside a multiline preprocessor macro if +@code{c-syntactic-indentation-in-macros} is set. @ref{Multiline Macro +Symbols}. +@item cpp-macro-cont +All lines inside multiline preprocessor macros if +@code{c-syntactic-indentation-in-macros} is @code{nil}. +@ref{Multiline Macro Symbols}. +@item friend +A C++ friend declaration. @ref{Class Symbols}. +@item objc-method-intro +The first line of an Objective-C method definition. @ref{Objective-C +Method Symbols}. +@item objc-method-args-cont +Lines continuing an Objective-C method definition. @ref{Objective-C +Method Symbols}. +@item objc-method-call-cont +Lines continuing an Objective-C method call. @ref{Objective-C Method +Symbols}. +@item extern-lang-open +Brace that opens an @code{extern} block (e.g. @code{extern "C" +@{...@}}). @ref{External Scope Symbols}. +@item extern-lang-close +Brace that closes an @code{extern} block. @ref{External Scope +Symbols}. +@item inextern-lang +Analogous to @code{inclass} syntactic symbol, but used inside +@code{extern} blocks. @ref{External Scope Symbols}. +@item namespace-open +@itemx namespace-close +@itemx innamespace +These are analogous to the three @code{extern-lang} symbols above, but +are returned for C++ namespace blocks. @ref{External Scope Symbols}. +@item module-open +@itemx module-close +@itemx inmodule +Analogous to the above, but for CORBA IDL @code{module} blocks. +@ref{External Scope Symbols}. +@item composition-open +@itemx composition-close +@itemx incomposition +Analogous to the above, but for CORBA CIDL @code{composition} blocks. +@ref{External Scope Symbols}. +@item template-args-cont +C++ template argument list continuations. @ref{Class Symbols}. +@item inlambda +Analogous to @code{inclass} syntactic symbol, but used inside lambda +(i.e. anonymous) functions. Only used in Pike mode. @ref{Statement +Block Symbols}. +@item lambda-intro-cont +Lines continuing the header of a lambda function, i.e. between the +@code{lambda} keyword and the function body. Only used in Pike mode. +@ref{Statement Block Symbols}. +@item inexpr-statement +A statement block inside an expression. The gcc C and C++ extension +for this is recognized. It's also used for the special functions that +take a statement block as an argument in Pike. @ref{Statement Block +Symbols}. +@item 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. @ref{Anonymous Class Symbol}. +@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:: +* Anonymous Class Symbol:: +* Statement Block Symbols:: +* K&R Symbols:: +@end menu + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Function Symbols, Class Symbols, Syntactic Symbols, Syntactic Symbols +@comment node-name, next, previous, up +@subsection Function Symbols +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +This example shows a typical function declaration. + +@example + 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: @} +@end example + +@ssindex topmost-intro +@ssindex topmost-intro-cont +@ssindex defun-open +@ssindex defun-close +@ssindex defun-block-intro +Line 1 shows a @code{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 +@code{topmost-intro-cont}. Line 3 shows a @code{defun-open} since it is +the brace that opens a top-level function definition. Line 9 is the +corresponding +@code{defun-close} since it contains the brace that closes the top-level +function definition. Line 4 is a @code{defun-block-intro}, i.e. it is +the first line of a brace-block, enclosed in a +top-level function definition. + +@ssindex statement +@ssindex statement-cont +Lines 5, 6, and 7 are all given @code{statement} syntax since there +isn't much special about them. Note however that line 8 is given +@code{statement-cont} syntax since it continues the statement begun +on the previous line. + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Class Symbols, Conditional Construct Symbols, Function Symbols, Syntactic Symbols +@comment node-name, next, previous, up +@subsection Class related Symbols +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +Here's an example which illustrates some C++ class syntactic symbols: + +@example + 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: @}; +@end example + +@ssindex class-open +@ssindex class-close +As in the previous example, line 1 has the @code{topmost-intro} syntax. +Here however, the brace that opens a C++ class definition on line 4 is +assigned the @code{class-open} syntax. Note that in C++, classes, +structs, and unions are essentially equivalent syntactically (and are +very similar semantically), so replacing the @code{class} keyword in the +example above with @code{struct} or @code{union} would still result in a +syntax of @code{class-open} for line 4 @footnote{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 @code{class} is meaningless in C and Objective-C.}. +Similarly, line 18 is assigned @code{class-close} syntax. + +@ssindex inher-intro +@ssindex inher-cont +Line 2 introduces the inheritance list for the class so it is assigned +the @code{inher-intro} syntax, and line 3, which continues the +inheritance list is given @code{inher-cont} syntax. + +@ssindex access-label +@ssindex inclass +Hitting @kbd{C-c C-s} on line 5 shows the following analysis: + +@example +((inclass 58) (access-label 58)) +@end example + +@noindent +The primary syntactic symbol for this line is @code{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 @code{inclass}. +Similarly, line 6 is given both @code{inclass} and @code{topmost-intro} +syntax: + +@example +((inclass 58) (topmost-intro 60)) +@end example + +@ssindex member-init-intro +@ssindex member-init-cont +Line 7 introduces a C++ member initialization list and as such is given +@code{member-init-intro} syntax. Note that in this case it is +@emph{not} assigned @code{inclass} since this is not considered a +top-level construct. Lines 8 through 10 are all assigned +@code{member-init-cont} since they continue the member initialization +list started on line 7. + +@cindex in-class inline methods +@ssindex inline-open +@ssindex inline-close +Line 11's analysis is a bit more complicated: + +@example +((inclass 58) (inline-open)) +@end example + +This line is assigned a syntax of both @code{inline-open} and +@code{inclass} because it opens an @dfn{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. +However, if the definition of the @code{Bass} constructor appeared +outside the class definition, the construct would be given the +@code{defun-open} syntax, even if the keyword @code{inline} appeared +before the method name, as in: + +@example + 1: class Bass + 2: : public Guitar, + 3: public Amplifiable + 4: @{ + 5: public: + 6: Bass(); + 7: @}; + 8: + 9: inline +10: Bass::Bass() +11: : eString( new BassString( 0.105 )), +12: aString( new BassString( 0.085 )), +13: dString( new BassString( 0.065 )), +14: gString( new BassString( 0.045 )) +15: @{ +16: eString.tune( 'E' ); +17: aString.tune( 'A' ); +18: dString.tune( 'D' ); +19: gString.tune( 'G' ); +20: @} +@end example + +@ssindex friend +Returning to the previous example, line 16 is given @code{inline-close} +syntax, while line 12 is given @code{defun-block-open} syntax, and lines +13 through 15 are all given @code{statement} syntax. Line 17 is +interesting in that its syntactic analysis list contains three +elements: + +@example +((inclass 58) (topmost-intro 380) (friend)) +@end example + +The @code{friend} and @code{inline-open} syntactic symbols are +modifiers that do not have anchor positions. + +@ssindex template-args-cont +Template definitions introduce yet another syntactic symbol: + +@example + 1: ThingManager framework_callbacks; +@end example + +Here, line 1 is analyzed as a @code{topmost-intro}, but lines 2 and 3 +are both analyzed as @code{template-args-cont} lines. + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Conditional Construct Symbols, Switch Statement Symbols, Class Symbols, Syntactic Symbols +@comment node-name, next, previous, up +@subsection Conditional Construct Symbols +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +Here is a (totally contrived) example which illustrates how syntax is +assigned to various conditional constructs: + +@example + 1: void spam( int index ) + 2: @{ + 3: for( int i=0; i 0 ); +15: @} +@end example + +Only the lines that illustrate new syntactic symbols will be discussed. + +@ssindex substatement-open +@ssindex statement-block-intro +@ssindex block-close +Line 4 has a brace which opens a conditional's substatement block. It +is thus assigned @code{substatement-open} syntax, and since line 5 is +the first line in the substatement block, it is assigned +@code{statement-block-intro} syntax. Line 10 contains the brace +that closes the inner substatement block, and is therefore given the +syntax @code{block-close}@footnote{@code{block-open} is used only for +``free-standing'' blocks, and is somewhat rare (@pxref{Literal +Symbols} for an example.)}. Line 13 is treated the same way. + +@ssindex substatement +Lines 6 and 9 are also substatements of conditionals, but since they +don't start blocks they are given @code{substatement} syntax +instead of @code{substatement-open}. + +@ssindex substatement-label +Line 8 contains a label, which is normally given @code{label} syntax. +This one is however a bit special since it's between a conditional and +its substatement. It's analyzed as @code{substatement-label} to let you +handle this rather odd case differently from normal labels. + +@ssindex else-clause +@ssindex catch-clause +Line 7 start with an @code{else} that matches the @code{if} statement on +line 5. It is therefore given the @code{else-clause} syntax and is +anchored on the matching @code{if}. The @code{try}-@code{catch} +constructs in C++ and Java are treated this way too, except that +@code{catch} and (in Java) @code{finally}, are marked with +@code{catch-clause}. + +@ssindex do-while-closure +The @code{while} construct on line 14 that closes a @code{do} +conditional is given the special syntax @code{do-while-closure} if it +appears on a line by itself. Note that if the @code{while} appeared on +the same line as the preceding close brace, that line would still have +@code{block-close} syntax. + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Switch Statement Symbols, Brace List Symbols, Conditional Construct Symbols, Syntactic Symbols +@comment node-name, next, previous, up +@subsection Switch Statement Symbols +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +Switch statements have their own set of syntactic symbols. Here's an +example: + +@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: @} +@end example + +@ssindex case-label +@ssindex statement-case-intro +@ssindex statement-case-open +Here, lines 4, 7, and 10 are all assigned @code{case-label} syntax, +while lines 5 and 8 are assigned @code{statement-case-intro}. Line 11 +is treated slightly differently since it contains a brace that opens a +block --- it is given @code{statement-case-open} syntax. + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Brace List Symbols, External Scope Symbols, Switch Statement Symbols, Syntactic Symbols +@comment node-name, next, previous, up +@subsection Brace List Symbols +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +@cindex brace lists +There are a set of syntactic symbols that are used to recognize +constructs inside of brace lists. A brace list is defined as an +@code{enum} or aggregate initializer list, such as might statically +initialize an array of structs. The three special aggregate constructs +in Pike, @code{(@{ @})}, @code{([ ])} and @code{(< >)}, are treated as +brace lists too. An example: + +@example + 1: static char* ingredients[] = + 2: @{ + 3: "Ham", + 4: "Salt", + 5: NULL + 6: @}; +@end example + +@ssindex brace-list-open +@ssindex brace-list-intro +@ssindex brace-list-close +@ssindex brace-list-entry +Following convention, line 2 in this example is assigned +@code{brace-list-open} syntax, and line 3 is assigned +@code{brace-list-intro} syntax. Likewise, line 6 is assigned +@code{brace-list-close} syntax. Lines 4 and 5 however, are assigned +@code{brace-list-entry} syntax, as would all subsequent lines in this +initializer list. + +@ssindex brace-entry-open +Your static initializer might be initializing nested structures, for +example: + +@example + 1: struct intpairs[] = + 2: @{ + 3: @{ 1, 2 @}, + 4: @{ + 5: 3, + 6: 4 + 7: @} + 8: @{ 1, + 9: 2 @}, +10: @{ 3, 4 @} +11: @}; +@end example + +Here, you've already seen the analysis of lines 1, 2, 3, and 11. On +line 4, things get interesting; this line is assigned +@code{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 @code{brace-list-close} as you'd +expect. Once again, line 8 is assigned as @code{brace-entry-open} as is +line 10. + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node External Scope Symbols, Paren List Symbols, Brace List Symbols, Syntactic Symbols +@comment node-name, next, previous, up +@subsection External Scope Symbols +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +External language definition blocks also have their own syntactic +symbols. In this example: + +@example + 1: extern "C" + 2: @{ + 3: int thing_one( int ); + 4: int thing_two( double ); + 5: @} +@end example + +@ssindex extern-lang-open +@ssindex extern-lang-close +@ssindex inextern-lang +@ssindex inclass +@noindent +line 2 is given the @code{extern-lang-open} syntax, while line 5 is given +the @code{extern-lang-close} syntax. The analysis for line 3 yields: + +@example +((inextern-lang) (topmost-intro 14)) +@end example + +@noindent +where @code{inextern-lang} is a modifier similar in purpose to +@code{inclass}. + +There are various other top level blocks like @code{extern}, and they +are all treated in the same way except that the symbols are named after +the keyword that introduces the block. E.g. C++ namespace blocks get +the three symbols @code{namespace-open}, @code{namespace-close} and +@code{innamespace}. The currently recognized top level blocks are: + +@table @asis +@item @code{extern-lang-open}, @code{extern-lang-close}, @code{inextern-lang} +@code{extern} blocks in C and C++.@footnote{These should logically be +named @code{extern-open}, @code{extern-close} and @code{inextern}, but +that isn't the case for historical reasons.} + +@item @code{namespace-open}, @code{namespace-close}, @code{innamespace} +@ssindex namespace-open +@ssindex namespace-close +@ssindex innamespace +@code{namespace} blocks in C++. + +@item @code{module-open}, @code{module-close}, @code{inmodule} +@ssindex module-open +@ssindex module-close +@ssindex inmodule +@code{module} blocks in CORBA IDL. + +@item @code{composition-open}, @code{composition-close}, @code{incomposition} +@ssindex composition-open +@ssindex composition-close +@ssindex incomposition +@code{composition} blocks in CORBA CIDL. +@end table + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Paren List Symbols, Literal Symbols, External Scope Symbols, Syntactic Symbols +@comment node-name, next, previous, up +@subsection Parenthesis (Argument) List Symbols +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +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: + +@example + 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: @} +@end example + +@ssindex arglist-intro +@ssindex arglist-close +Lines 5 and 12 are assigned @code{arglist-intro} syntax since they are +the first line following the open parenthesis, and lines 7 and 14 are +assigned @code{arglist-close} syntax since they contain the parenthesis +that closes the argument list. + +@ssindex arglist-cont-nonempty +@ssindex arglist-cont +Lines that continue argument lists can be assigned one of two syntactic +symbols. For example, Lines 2 and 17 +are assigned @code{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 @emph{not empty} following the open +parenthesis. Contrast this against lines 6 and 13 which are assigned +@code{arglist-cont} syntax. This is because the parenthesis that opens +their argument lists is the last character on that line. + +Syntactic elements with @code{arglist-intro}, +@code{arglist-cont-nonempty}, and @code{arglist-close} contain two +buffer positions: the anchor position (the beginning of the +declaration or statement) and the position of the open parenthesis. +The latter position can be used in a line-up function (@pxref{Line-Up +Functions}). + +Note that there is no @code{arglist-open} syntax. This is because any +parenthesis that opens an argument list, appearing on a separate line, +is assigned the @code{statement-cont} syntax instead. + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Literal Symbols, Multiline Macro Symbols, Paren List Symbols, Syntactic Symbols +@comment node-name, next, previous, up +@subsection Comment String Label and Macro Symbols +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +A few miscellaneous syntactic symbols that haven't been previously +covered are illustrated by this C++ example: + +@example + 1: void Bass::play( int volume ) + 2: const + 3: @{ + 4: /* this line starts a multiline + 5: * comment. This line should get `c' syntax */ + 6: + 7: char* a_multiline_string = "This line starts a multiline \ + 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: @} +@end example + +The lines to note in this example include: + +@itemize @bullet +@item +@ssindex func-decl-cont +Line 2 is assigned the @code{func-decl-cont} syntax. + +@item +@ssindex comment-intro +Line 4 is assigned both @code{defun-block-intro} @emph{and} +@code{comment-intro} syntax. A syntactic element with +@code{comment-intro} has no anchor point --- It is always accompanied +by another syntactic element which does have one. + +@item +@ssindex c +Line 5 is assigned @code{c} syntax. + +@item +@cindex syntactic whitespace +Line 6 which, even though it contains nothing but whitespace, is +assigned @code{defun-block-intro}. Note that the appearance of the +comment on lines 4 and 5 do not cause line 6 to be assigned +@code{statement} syntax because comments are considered to be +@dfn{syntactic whitespace}, which are ignored when analyzing +code. + +@item +@ssindex string +Line 8 is assigned @code{string} syntax. + +@item +@ssindex label +Line 10 is assigned @code{label} syntax. + +@item +@ssindex block-open +Line 11 is assigned @code{block-open} as well as @code{statement} +syntax. A @code{block-open} syntactic element doesn't have an anchor +position, since it always appears with another syntactic element which +does have one. + +@item +@ssindex cpp-macro +Lines 12 and 14 are assigned @code{cpp-macro} syntax in addition to the +normal syntactic symbols (@code{statement-block-intro} and +@code{statement}, respectively). Normally @code{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. Like @code{comment-intro}, a syntactic element with +@code{cpp-macro} doesn't contain an anchor position. + +@item +@ssindex stream-op +Line 17 is assigned @code{stream-op} syntax. +@end itemize + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Multiline Macro Symbols, Objective-C Method Symbols, Literal Symbols, Syntactic Symbols +@comment node-name, next, previous, up +@subsection Multiline Macro Symbols +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +@cindex multiline macros +@cindex syntactic whitespace +@ssindex cpp-define-intro +@ssindex cpp-macro-cont +Multiline preprocessor macro definitions are normally handled just like +other code, i.e. the lines inside them are indented according to the +syntactic analysis of the preceding lines inside the macro. The first +line inside a macro definition (i.e. the line after the starting line of +the cpp directive itself) gets @code{cpp-define-intro}. In this example: + +@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 +@end example + +@noindent +line 1 is given the syntactic symbol @code{cpp-macro}. The first line +of a cpp directive is always given that symbol. Line 2 is given +@code{cpp-define-intro}, so that you can give the macro body as a whole +some extra indentation. Lines 3 through 5 are then analyzed as normal +code, i.e. @code{substatement} on lines 3 and 4, and @code{else-clause} +on line 5. + +The syntactic analysis inside macros can be turned off with +@code{c-syntactic-indentation-in-macros} (@pxref{Custom Macros}). In +that case, lines 2 through 5 would all be given @code{cpp-macro-cont} +with an anchor position pointing to the @code{#} which starts the cpp +directive@footnote{This is how @ccmode{} 5.28 and earlier analyzed +macros.}. + +@xref{Custom Macros}, for more info about the treatment of macros. + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Objective-C Method Symbols, Anonymous Class Symbol, Multiline Macro Symbols, Syntactic Symbols +@comment node-name, next, previous, up +@subsection Objective-C Method Symbols +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +In Objective-C buffers, there are three additional syntactic symbols +assigned to various message calling constructs. Here's an example +illustrating these: + +@example + 1: - (void)setDelegate:anObject + 2: withStuff:stuff + 3: @{ + 4: [delegate masterWillRebind:self + 5: toDelegate:anObject + 6: withExtraStuff:stuff]; + 7: @} +@end example + +@ssindex objc-method-intro +@ssindex objc-method-args-cont +@ssindex objc-method-call-cont +Here, line 1 is assigned @code{objc-method-intro} syntax, and line 2 is +assigned @code{objc-method-args-cont} syntax. Lines 5 and 6 are both +assigned @code{objc-method-call-cont} syntax. + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Anonymous Class Symbol, Statement Block Symbols, Objective-C Method Symbols, Syntactic Symbols +@comment node-name, next, previous, up +@subsection Anonymous Class Symbol (Java) +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +Java has a concept of anonymous classes which can look something like +this: + +@example + 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: @} +@end example + +@ssindex inexpr-class +The brace following the @code{new} operator opens the anonymous class. +Lines 3 and 6 are assigned the @code{inexpr-class} syntax, besides the +@code{inclass} symbol used in normal classes. Thus, the class will be +indented just like a normal class, with the added indentation given to +@code{inexpr-class}. An @code{inexpr-class} syntactic element doesn't +have an anchor position. + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Statement Block Symbols, K&R Symbols, Anonymous Class Symbol, Syntactic Symbols +@comment node-name, next, previous, up +@subsection Statement Block Symbols +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +There are a few occasions where a statement block might be used inside +an expression. One is in C or C++ code using the gcc extension for +this, e.g: + +@example + 1: int res = (@{ + 2: int y = foo (); int z; + 3: if (y > 0) z = y; else z = - y; + 4: z; + 5: @}); +@end example + +@ssindex inexpr-statement +Lines 2 and 5 get the @code{inexpr-statement} syntax, besides the +symbols they'd get in a normal block. Therefore, the indentation put on +@code{inexpr-statement} is added to the normal statement block +indentation. An @code{inexpr-statement} syntactic element doesn't +contain an anchor position. + +In Pike code, there are a few other situations where blocks occur inside +statements, as illustrated here: + +@example + 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: @} +@end example + +@ssindex inlambda +@ssindex lambda-intro-cont +Lines 4 through 8 contain a lambda function, which @ccmode{} recognizes +by the @code{lambda} keyword. If the function argument list is put +on a line of its own, as in line 5, it gets the @code{lambda-intro-cont} +syntax. The function body is handled as an inline method body, with the +addition of the @code{inlambda} syntactic symbol. This means that line +6 gets @code{inlambda} and @code{inline-open}, and line 8 gets +@code{inline-close}@footnote{You might wonder why it doesn't get +@code{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 @code{inlambda} syntax too to be indented correctly.}. + +@ssindex inexpr-statement +On line 9, @code{catch} is a special function taking a statement block +as its argument. The block is handled as an in-expression statement +with the @code{inexpr-statement} syntax, just like the gcc extended C +example above. The other similar special function, @code{gauge}, is +handled like this too. + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node K&R Symbols, , Statement Block Symbols, Syntactic Symbols +@comment node-name, next, previous, up +@subsection K&R Symbols +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +@ssindex knr-argdecl-intro +@ssindex knr-argdecl +Two other syntactic symbols can appear in old style, non-prototyped C +code @footnote{a.k.a. K&R C, or Kernighan & Ritchie C}: + +@example + 1: int add_three_integers(a, b, c) + 2: int a; + 3: int b; + 4: int c; + 5: @{ + 6: return a + b + c; + 7: @} +@end example + +Here, line 2 is the first line in an argument declaration list and so is +given the @code{knr-argdecl-intro} syntactic symbol. Subsequent lines +(i.e. lines 3 and 4 in this example), are given @code{knr-argdecl} +syntax. + + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Indentation Calculation, , Syntactic Symbols, Indentation Engine Basics +@comment node-name, next, previous, up +@section Indentation Calculation +@cindex indentation +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +Indentation for a line is calculated from the syntactic context +(@pxref{Syntactic Analysis}). + +First, a buffer position is found whose column will be the base for the +indentation calculation. It's the anchor position in the first +syntactic element that provides one that is used. If no syntactic +element has an anchor position then column zero is used. + +Second, the syntactic symbols in each syntactic element are looked up +in the @code{c-offsets-alist} style variable +(@pxref{c-offsets-alist}), which is an association list of syntactic +symbols and the offsets to apply for those symbols. These offsets are +added together with the base column to produce the new indentation +column. + +Let's use our two code examples above to see how this works. Here is +our first example again: + +@example + 1: void swap( int& a, int& b ) + 2: @{ + 3: int tmp = a; + 4: a = b; + 5: b = tmp; + 6: @} +@end example + +Let's say point is on line 3 and we hit the @key{TAB} key to reindent +the line. The syntactic context for that line is: + +@example +((defun-block-intro 29)) +@end example + +@noindent +Since buffer position 29 is the first and only anchor position in the +list, @ccmode{} goes there and asks for the current column. This brace +is in column zero, so @ccmode{} uses @samp{0} as the base column. + +Next, @ccmode{} looks up @code{defun-block-intro} in the +@code{c-offsets-alist} style variable. Let's say it finds the value +@samp{4}; it adds this to the base column @samp{0}, yielding a running +total indentation of 4 spaces. + +Since there is only one syntactic element on the list for this line, +indentation calculation is complete, and the total indentation for the +line is 4 spaces. + +Here's another example: + +@example + 1: int add( int val, int incr, int doit ) + 2: @{ + 3: if( doit ) + 4: @{ + 5: return( val + incr ); + 6: @} + 7: return( val ); + 8: @} +@end example + +If we were to hit @kbd{TAB} on line 4 in the above example, the same +basic process is performed, despite the differences in the syntactic +context. The context for this line is: + +@example +((substatement-open 46)) +@end example + +Here, @ccmode{} goes to buffer position 46, which is the @samp{i} in +@code{if} on line 3. This character is in the fourth column on that +line so the base column is @samp{4}. Then @ccmode{} looks up the +@code{substatement-open} symbol in @code{c-offsets-alist}. Let's say it +finds the value @samp{4}. It's added with the base column and yields an +indentation for the line of 8 spaces. + +Simple, huh? + +Actually, it's a bit more complicated than that since the entries on +@code{c-offsets-alist} can be much more than plain offsets. +@xref{c-offsets-alist}, for the full story. + +Anyway, the mode usually just does The Right Thing without you having to +think about it in this much detail. But when customizing indentation, +it's helpful to understand the general indentation model being used. + +As you configure @ccmode{}, you might want to set the variable +@code{c-echo-syntactic-information-p} to non-@code{nil} so that the +syntactic context and calculated offset always is echoed in the +minibuffer when you hit @kbd{TAB}. + + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Customizing Indentation, Custom Macros, Indentation Engine Basics, Top +@comment node-name, next, previous, up +@chapter Customizing Indentation +@cindex customization, indentation +@cindex indentation +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +The principal variable for customizing indentation is the style +variable @code{c-offsets-alist}, which gives an @dfn{offset} (an +indentation rule) for each syntactic symbol. Its structure and +semantics are completely described in @ref{c-offsets-alist}. The +various ways you can set the variable, including the use of the +@ccmode{} style system, are described in @ref{Config Basics} and its +sections, in particular @ref{Style Variables}. + +The simplest and most used kind of ``offset'' setting in +@code{c-offsets-alist} is in terms of multiples of +@code{c-basic-offset}: + +@defopt c-basic-offset +@vindex basic-offset (c-) +This style variable holds the basic offset between indentation levels. +It's factory default is 4, but all the built-in styles set it +themselves, to some value between 2 (for @code{gnu} style) and 8 (for +@code{bsd}, @code{linux}, and @code{python} styles). +@end defopt + +The most flexible ``offset'' setting you can make in +@code{c-offsets-alist} is a line-up function (or even a list of them), +either one supplied by @ccmode{} (@pxref{Line-Up Functions}) or one +you write yourself (@pxref{Custom Line-Up}). + +Finally, in @ref{Other Indentation} you'll find the tool of last +resort: a hook which is called after a line has been indented. You +can install functions here to make ad-hoc adjustments to any line's +indentation. + +@menu +* c-offsets-alist:: +* Interactive Customization:: +* Line-Up Functions:: +* Custom Line-Up:: +* Other Indentation:: +@end menu + + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node c-offsets-alist, Interactive Customization, Customizing Indentation, Customizing Indentation +@comment node-name, next, previous, up +@section c-offsets-alist +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +This section explains the structure and semantics of the style +variable @code{c-offset-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}. + +@defopt c-offsets-alist +@vindex offsets-alist (c-) +This is an alist which associates an offset with each syntactic +symbol. This @dfn{offset} is a rule specifying how to indent a line +whose syntactic context matches the symbol. @xref{Syntactic +Analysis}. + +Note that the buffer-local binding of this alist in a @ccmode{} buffer +contains an entry for @emph{every} syntactic symbol. Its global +binding and its settings within style specifications usually contain +only a few entries. @xref{Style Variables}. + +The offset specification associated with any particular syntactic +symbol can be an integer, a variable name, a vector, a function or +lambda expression, a list, or one of the following special symbols: +@code{+}, @code{-}, @code{++}, @code{--}, @code{*}, or @code{/}. The +meanings of these values are described in detail below. + +Here is an example fragment of a @code{c-offsets-alist}, showing some +of these kinds of offsets: + +@example +((statement . 0) + (substatement . +) + (cpp-macro . [0]) + (topmost-intro-cont . c-lineup-topmost-intro-cont) + (statement-block-intro . (add c-lineup-whitesmith-in-block + c-indent-multi-line-block)) + @dots{} +@*) +@end example +@end defopt + +@deffn Command c-set-offset (@kbd{C-c C-o}) +@findex set-offset (c-) +@kindex C-c C-o +This command changes the entry for a syntactic symbol in the current +binding of @code{c-offsets-alist}, or it inserts a new entry if there +isn't already one for that syntactic symbol. + +You can use @code{c-set-offsets} interactively within a @ccmode{} +buffer to make experimental changes to your indentation settings. +@kbd{C-c C-o} prompts you for the syntactic symbol to change +(defaulting to that of the current line) and the new offset +(defaulting to the current offset). + +@code{c-set-offsets} takes two arguments when used programmatically: +@var{symbol}, the syntactic element symbol to change and @var{offset}, +the new offset for that syntactic element. You can call the command +in your @file{.emacs} to change the global binding of +@code{c-offsets-alist} (@pxref{Style Variables}); you can use it in a +hook function to make changes from the current style. @ccmode{} +itself uses this function when initializing styles. +@end deffn + +@cindex offset specification +The ``offset specifications'' in @code{c-offsets-alist} can be any of +the following: + +@table @asis +@item An integer +The integer specifies a relative offset. All relative +offsets@footnote{The syntactic context @code{@w{((defun-block-intro +2724) (comment-intro))}} would likely have two relative offsets.} will +be added together and used to calculate the indentation relative to an +anchor position earlier in the buffer. @xref{Indentation +Calculation}, for details. Most of the time, it's probably better to +use one of the special symbols like @code{+} than an integer (apart +from zero). + +@item One of the symbols @code{+}, @code{-}, @code{++}, @code{--}, @code{*}, or @code{/} +These special symbols describe a relative offset in multiples of +@code{c-basic-offset}: + +By defining a style's indentation in terms of @code{c-basic-offset}, +you can change the amount of whitespace given to an indentation level +while maintaining the same basic shape of your code. Here are the +values that the special symbols correspond to: + +@table @code +@item + +@code{c-basic-offset} times 1 +@item - +@code{c-basic-offset} times -1 +@item ++ +@code{c-basic-offset} times 2 +@item -- +@code{c-basic-offset} times -2 +@item * +@code{c-basic-offset} times 0.5 +@item / +@code{c-basic-offset} times -0.5 +@end table + +@item A vector +The first element of the vector, an integer, sets the absolute +indentation column. This will override any previously calculated +indentation, but won't override relative indentation calculated from +syntactic elements later on in the syntactic context of the line being +indented. @xref{Indentation Calculation}. Any elements in the vector +beyond the first will be ignored. + +@item A function or lambda expression +The function will be called and its return value will in turn be +evaluated as an offset specification. Functions are useful when more +context than just the syntactic symbol is needed to get the desired +indentation. @xref{Line-Up Functions}, and @ref{Custom Line-Up}, for +details about them. + +@item A symbol with a variable binding +If the symbol also has a function binding, the function takes +precedence over the variable. Otherwise the value of the variable is +used. It must be an integer (which is used as relative offset) or a +vector (an absolute offset). + +@item A list +The offset can also be a list containing several offset +specifications; these are evaluated recursively and combined. A list +is typically only useful when some of the offsets are line-up +functions. A common strategy is calling a sequence of functions in +turn until one of them recognizes that it is appropriate for the +source line and returns a non-@code{nil} value. + +@code{nil} values are always ignored when the offsets are combined. +The first element of the list specifies the method of combining the +non-@code{nil} offsets from the remaining elements: + +@table @code +@item first +Use the first offset that doesn't evaluate to @code{nil}. Subsequent +elements of the list don't get evaluated. +@item min +Use the minimum of all the offsets. All must be either relative or +absolute - they can't be mixed. +@item max +Use the maximum of all the offsets. All must be either relative or +absolute - they can't be mixed. +@item add +Add all the evaluated offsets together. Exactly one of them may be +absolute, in which case the result is absolute. Any relative offsets +that preceded the absolute one in the list will be ignored in that case. +@end table + +As a compatibility measure, if the first element is none of the above +then it too will be taken as an offset specification and the whole list +will be combined according to the method @code{first}. +@end table + +@vindex c-strict-syntax-p +@vindex strict-syntax-p (c-) +If an offset specification evaluates to @code{nil}, then a relative +offset of 0 (zero) is used@footnote{There is however a variable +@code{c-strict-syntax-p} that when set to non-@code{nil} will cause an +error to be signaled in that case. It's now considered obsolete since +it doesn't work well with some of the alignment functions that return +@code{nil} instead of zero. You should therefore leave +@code{c-strict-syntax-p} set to @code{nil}.}. + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Interactive Customization, Line-Up Functions, c-offsets-alist, Customizing Indentation +@comment node-name, next, previous, up +@section Interactive Customization +@cindex customization, interactive +@cindex interactive customization +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +As an example of how to customize indentation, let's change the +style of this example@footnote{In this and subsequent examples, the +original code is formatted using the @samp{gnu} style unless otherwise +indicated. @xref{Styles}.}: + +@example +@group + 1: int add( int val, int incr, int doit ) + 2: @{ + 3: if( doit ) + 4: @{ + 5: return( val + incr ); + 6: @} + 7: return( val ); + 8: @} +@end group +@end example + +@noindent +to: + +@example +@group + 1: int add( int val, int incr, int doit ) + 2: @{ + 3: if( doit ) + 4: @{ + 5: return( val + incr ); + 6: @} + 7: return( val ); + 8: @} +@end group +@end example + +In other words, we want to change the indentation of braces that open a +block following a condition so that the braces line up under the +conditional, instead of being indented. Notice that the construct we +want to change starts on line 4. To change the indentation of a line, +we need to see which syntactic symbols affect the offset calculations +for that line. Hitting @kbd{C-c C-s} on line 4 yields: + +@example +((substatement-open 44)) +@end example + +@noindent +so we know that to change the offset of the open brace, we need to +change the indentation for the @code{substatement-open} syntactic +symbol. + +To do this interactively, just hit @kbd{C-c C-o}. This prompts +you for the syntactic symbol to change, providing a reasonable default. +In this case, the default is @code{substatement-open}, which is just the +syntactic symbol we want to change! + +After you hit return, @ccmode{} will then prompt you for the new +offset value, with the old value as the default. The default in this +case is @samp{+}, but we want no extra indentation so enter +@samp{0} and @kbd{RET}. This will associate the offset 0 with the +syntactic symbol @code{substatement-open}. + +To check your changes quickly, just hit @kbd{C-c C-q} +(@code{c-indent-defun}) to reindent the entire function. The example +should now look like: + +@example +@group + 1: int add( int val, int incr, int doit ) + 2: @{ + 3: if( doit ) + 4: @{ + 5: return( val + incr ); + 6: @} + 7: return( val ); + 8: @} +@end group +@end example + +Notice how just changing the open brace offset on line 4 is all we +needed to do. Since the other affected lines are indented relative to +line 4, they are automatically indented the way you'd expect. For more +complicated examples, this might not always work. The general approach +to take is to always start adjusting offsets for lines higher up in the +file, then reindent and see if any following lines need further +adjustments. + +@c Move this bit to "Styles" (2005/10/7) +@deffn Command c-set-offset symbol offset +@findex set-offset (c-) +@kindex C-c C-o +This is the command bound to @kbd{C-c C-o}. It provides a convenient +way to set offsets on @code{c-offsets-alist} both interactively (see +the example above) and from your mode hook. + +It takes two arguments when used programmatically: @var{symbol} is the +syntactic element symbol to change and @var{offset} is the new offset +for that syntactic element. +@end deffn +@c End of MOVE THIS BIT. + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Line-Up Functions, Custom Line-Up, Interactive Customization, Customizing Indentation +@comment node-name, next, previous, up +@section Line-Up Functions +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +@cindex line-up function +@cindex indentation function +Often there are cases when a simple offset setting on a syntactic +symbol isn't enough to get the desired indentation---for example, you +might want to line up a closing parenthesis with the matching opening +one rather than indenting relative to its ``anchor point''. @ccmode{} +provides this flexibility with @dfn{line-up functions}. + +The way you associate a line-up function with a syntactic symbol is +described in @ref{c-offsets-alist}. @ccmode{} comes with many +predefined line-up functions for common situations. If none of these +does what you want, you can write your own. @xref{Custom Line-Up}. +Sometimes, it is easier to tweak the standard indentation by adding a +function to @code{c-special-indent-hook} (@pxref{Other Indentation}). + +The line-up functions haven't been adapted for AWK buffers or tested +with them. Some of them might work serendipitously. There shouldn't be +any problems writing custom line-up functions for AWK mode. + +The calling convention for line-up functions is described fully in +@ref{Custom Line-Up}. Roughly speaking, the return value is either an +offset itself (such as @code{+} or @code{[0]}) or it's @code{nil}, +meaning ``this function is inappropriate in this case - try a +different one''. @xref{c-offsets-alist}. + +The subsections below describe all the standard line-up functions, +categorized by the sort of token the lining-up centers around. For +each of these functions there is a ``works with'' list that indicates +which syntactic symbols the function is intended to be used with. + +@macro workswith +@emph{Works with:@ } +@end macro +@ifinfo +@unmacro workswith +@macro workswith +Works with: +@end macro +@end ifinfo + +@macro sssTBasicOffset +<--> @i{c-basic-offset}@c +@end macro + +@macro sssTsssTBasicOffset +<--><--> @i{c-basic-offset}@c +@end macro + +@macro hereFn{func} +<- @i{\func\}@c +@end macro + +@c The TeX backend seems to insert extra spaces around the argument. :P +@iftex +@unmacro hereFn +@macro hereFn{func} +<-@i{\func\}@c +@end macro +@end iftex + +@menu +* Brace/Paren Line-Up:: +* List Line-Up:: +* Operator Line-Up:: +* Comment Line-Up:: +* Misc Line-Up:: +@end menu + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Brace/Paren Line-Up, List Line-Up, Line-Up Functions, Line-Up Functions +@comment node-name, next, previous, up +@subsection Brace and Parenthesis Line-Up Functions +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +The line-up functions here calculate the indentation for braces, +parentheses and statements within brace blocks. + +@defun c-lineup-close-paren +@findex lineup-close-paren (c-) +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: + +@example +@group +main (int, + char ** + ) @hereFn{c-lineup-close-paren} +@end group +@end example + +@noindent +and + +@example +@group +main ( + int, char ** +) @hereFn{c-lineup-close-paren} +@end group +@end example + +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 +@code{c-basic-offset} instead of the open paren column. See +@code{c-lineup-arglist} for further discussion of this ``DWIM'' measure. + +@workswith All @code{*-close} symbols. +@end defun + +@comment ------------------------------------------------------------ + +@anchor{c-lineup-arglist-close-under-paren} +@defun c-lineup-arglist-close-under-paren +@findex lineup-arglist-close-under-paren (c-) +Set your @code{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 +@code{arglist-cont} and @code{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 +@code{c-basic-offset} only. See @code{c-lineup-arglist} for further +discussion of this ``DWIM'' measure. + +@workswith Almost all symbols, but are typically most useful on +@code{arglist-close}, @code{brace-list-close}, @code{arglist-cont} and +@code{arglist-cont-nonempty}. +@end defun + +@comment ------------------------------------------------------------ + +@defun c-indent-one-line-block +@findex indent-one-line-block (c-) +Indent a one line block @code{c-basic-offset} extra. E.g: + +@example +@group +if (n > 0) + @{m+=n; n=0;@} @hereFn{c-indent-one-line-block} +@sssTBasicOffset{} +@end group +@end example + +@noindent +and + +@example +@group +if (n > 0) +@{ @hereFn{c-indent-one-line-block} + m+=n; n=0; +@} +@end group +@end example + +The block may be surrounded by any kind of parenthesis characters. +@code{nil} is returned if the line doesn't start with a one line block, +which makes the function usable in list expressions. -@cindex -open syntactic symbols -@cindex -close syntactic symbols -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 @code{-open} or @code{-close} respectively. - -@cindex -intro syntactic symbols -@cindex -cont syntactic symbols -@cindex -block-intro syntactic symbols -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 @code{-intro} or -@code{-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 @code{-block-intro}. +@workswith Almost all syntactic symbols, but most useful on the +@code{-open} symbols. +@end defun + +@comment ------------------------------------------------------------ + +@defun c-indent-multi-line-block +@findex indent-multi-line-block (c-) +Indent a multiline block @code{c-basic-offset} extra. E.g: -@kindex C-c C-s -Let's look at some examples to understand how this works. Remember that -you can check the syntax of any line by using @kbd{C-c C-s}. @example @group +int *foo[] = @{ + NULL, + @{17@}, @hereFn{c-indent-multi-line-block} +@end group +@end example - 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: @} +@noindent +and +@example +@group +int *foo[] = @{ + NULL, + @{ @hereFn{c-indent-multi-line-block} + 17 + @}, + @sssTBasicOffset{} @end group @end example -@cindex topmost-intro syntactic symbol -@cindex topmost-intro-cont syntactic symbol -@cindex defun-open syntactic symbol -@cindex defun-close syntactic symbol -@cindex defun-block-intro syntactic symbol -Line 1 shows a @code{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 -@code{topmost-intro-cont}. Line 3 shows a @code{defun-open} since it is -the brace that opens a top-level function definition. Line 9 is a -@code{defun-close} since it contains the brace that closes the top-level -function definition. Line 4 is a @code{defun-block-intro}, i.e. it is -the first line of a brace-block, enclosed in a -top-level function definition. +The block may be surrounded by any kind of parenthesis characters. +@code{nil} is returned if the line doesn't start with a multiline +block, which makes the function usable in list expressions. -@cindex statement syntactic symbol -@cindex statement-cont syntactic symbol -Lines 5, 6, and 7 are all given @code{statement} syntax since there -isn't much special about them. Note however that line 8 is given -@code{statement-cont} syntax since it continues the statement begun -on the previous line. +@workswith Almost all syntactic symbols, but most useful on the +@code{-open} symbols. +@end defun -Here's another example, which illustrates some C++ class syntactic -symbols: -@example -@group +@comment ------------------------------------------------------------ - 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: @} +@defun c-lineup-runin-statements +@findex lineup-runin-statements (c-) +Line up statements for coding standards which place the first statement +in a block on the same line as the block opening brace@footnote{Run-in +style doesn't really work too well. You might need to write your own +custom line-up functions to better support this style.}. E.g: +@example +@group +int main() +@{ puts ("Hello!"); + return 0; @hereFn{c-lineup-runin-statements} +@} @end group @end example -@cindex class-open syntactic symbol -@cindex class-close syntactic symbol -As in the previous example, line 1 has the @code{topmost-intro} syntax. -Here however, the brace that opens a C++ class definition on line 4 is -assigned the @code{class-open} syntax. Note that in C++, classes, -structs, and unions are essentially equivalent syntactically (and are -very similar semantically), so replacing the @code{class} keyword in the -example above with @code{struct} or @code{union} would still result in a -syntax of @code{class-open} for line 4 @footnote{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 @code{class} is meaningless in C and Objective-C.}. -Similarly, line 18 is assigned @code{class-close} syntax. +If there is no statement after the opening brace to align with, +@code{nil} is returned. This makes the function usable in list +expressions. -@cindex inher-intro syntactic symbol -@cindex inher-cont syntactic symbol -Line 2 introduces the inheritance list for the class so it is assigned -the @code{inher-intro} syntax, and line 3, which continues the -inheritance list is given @code{inher-cont} syntax. +@workswith The @code{statement} syntactic symbol. +@end defun -@cindex access-label syntactic symbol -@cindex inclass syntactic symbol -Hitting @kbd{C-c C-s} on line 5 shows the following analysis: +@comment ------------------------------------------------------------ -@example -@group +@defun c-lineup-inexpr-block +@findex lineup-inexpr-block (c-) +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 @samp{new} keyword, +and in Pike it lines up the lambda function body under the @samp{lambda} +keyword. Returns @code{nil} if the block isn't part of such a +construct. -@code{((inclass . 1) (access-label . 67))} +@workswith @code{inlambda}, @code{inexpr-statement}, +@code{inexpr-class}. +@end defun -@end group -@end example +@comment ------------------------------------------------------------ -@noindent -The primary syntactic symbol for this line is @code{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 @code{inclass}. -Similarly, line 6 is given both @code{inclass} and @code{topmost-intro} -syntax: +@defun c-lineup-after-whitesmith-blocks +@findex lineup-after-whitesmith-blocks (c-) +Compensate for Whitesmith style indentation of blocks. Due to the way +@ccmode{} calculates anchor positions for normal lines inside blocks, +this function is necessary for those lines to get correct Whitesmith +style indentation. Consider the following examples: @example @group +int foo() + @{ + a; + x; @hereFn{c-lineup-after-whitesmith-blocks} +@end group +@end example -@code{((inclass . 58) (topmost-intro . 60))} - +@example +@group +int foo() + @{ + @{ + a; + @} + x; @hereFn{c-lineup-after-whitesmith-blocks} @end group @end example -@cindex member-init-intro syntactic symbol -@cindex member-init-cont syntactic symbol -Line 7 introduces a C++ member initialization list and as such is given -@code{member-init-intro} syntax. Note that in this case it is -@emph{not} assigned @code{inclass} since this is not considered a -top-level construct. Lines 8 through 10 are all assigned -@code{member-init-cont} since they continue the member initialization -list started on line 7. +The fact that the line with @code{x} is preceded by a Whitesmith style +indented block in the latter case and not the first should not affect +its indentation. But since CC Mode in cases like this uses the +indentation of the preceding statement as anchor position, the @code{x} +would in the second case be indented too much if the offset for +@code{statement} was set simply to zero. -@cindex in-class inline methods -@cindex inline-open syntactic symbol -@cindex inline-close syntactic symbol -Line 11's analysis is a bit more complicated: +This lineup function corrects for this situation by detecting if the +anchor position is at an open paren character. In that case, it instead +indents relative to the surrounding block just like +@code{c-lineup-whitesmith-in-block}. -@example -@group +@workswith @code{brace-list-entry}, @code{brace-entry-open}, +@code{statement}, @code{arglist-cont}. +@end defun -@code{((inclass . 1) (inline-open))} +@comment ------------------------------------------------------------ +@defun c-lineup-whitesmith-in-block +@findex lineup-whitesmith-in-block (c-) +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: + +@example +@group +something + @{ + foo; @hereFn{c-lineup-whitesmith-in-block} + @} @end group @end example -This line is assigned a syntax of both @code{inline-open} and -@code{inclass} because it opens an @dfn{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 @code{Bass} constructor appeared -outside the class definition, the construct would be given the -@code{defun-open} syntax, even if the keyword @code{inline} appeared -before the method name, as in: +@noindent +and + @example @group +something @{ + foo; @hereFn{c-lineup-whitesmith-in-block} + @} +@sssTBasicOffset{} +@end group +@end example -class Bass - : public Guitar, - public Amplifiable -@{ -public: - Bass(); -@} +In the first case the indentation is kept unchanged, in the second +@code{c-basic-offset} is added. -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' ); -@} +@workswith @code{defun-close}, @code{defun-block-intro}, +@code{inline-close}, @code{block-close}, @code{brace-list-close}, +@code{brace-list-intro}, @code{statement-block-intro}, +@code{arglist-intro}, @code{arglist-cont-nonempty}, +@code{arglist-close}, and all @code{in*} symbols, e.g. @code{inclass} +and @code{inextern-lang}. +@end defun + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node List Line-Up, Operator Line-Up, Brace/Paren Line-Up, Line-Up Functions +@comment node-name, next, previous, up +@subsection List Line-Up Functions +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +The line-up functions here calculate the indentation for lines which +form lists of items, usually separated by commas. + +The function @ref{c-lineup-arglist-close-under-paren}, which is mainly +for indenting a close parenthesis, is also useful for the lines +contained within parentheses. + +@defun c-lineup-arglist +@findex lineup-arglist (c-) +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 +@code{c-basic-offset} only. This is intended as a ``DWIM'' measure in +cases like macros that contain statement blocks, e.g: +@example +@group +A_VERY_LONG_MACRO_NAME (@{ + some (code, with + long, lines * in[it]); + @}); +@sssTBasicOffset{} @end group @end example -@cindex friend syntactic symbol -Returning to the previous example, line 16 is given @code{inline-close} -syntax, while line 12 is given @code{defun-block-open} syntax, and lines -13 through 15 are all given @code{statement} syntax. Line 17 is -interesting in that its syntactic analysis list contains three -elements: +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. -@example +@workswith @code{arglist-cont-nonempty}, @code{arglist-close}. +@end defun -@code{((friend) (inclass . 58) (topmost-intro . 380))} +@comment ------------------------------------------------------------ -@end example +@defun c-lineup-arglist-intro-after-paren +@findex lineup-arglist-intro-after-paren (c-) +Line up a line to just after the open paren of the surrounding paren or +brace block. -The @code{friend} syntactic symbol is a modifier that typically does not -have a relative buffer position. +@workswith @code{defun-block-intro}, @code{brace-list-intro}, +@code{statement-block-intro}, @code{statement-case-intro}, +@code{arglist-intro}. +@end defun -Template definitions introduce yet another syntactic symbol: +@comment ------------------------------------------------------------ + +@defun c-lineup-multi-inher +@findex lineup-multi-inher (c-) +Line up the classes in C++ multiple inheritance clauses and member +initializers under each other. E.g: @example @group +Foo::Foo (int a, int b): + Cyphr (a), + Bar (b) @hereFn{c-lineup-multi-inher} +@end group +@end example - 1: ThingManager framework_callbacks; +@noindent +and +@example +@group +class Foo + : public Cyphr, + public Bar @hereFn{c-lineup-multi-inher} @end group @end example -Here, line 1 is analyzed as a @code{topmost-intro}, but lines 2 and 3 -are both analyzed as @code{template-args-cont} lines. +@noindent +and -Here is another (totally contrived) example which illustrates how syntax -is assigned to various conditional constructs: @example @group +Foo::Foo (int a, int b) + : Cyphr (a) + , Bar (b) @hereFn{c-lineup-multi-inher} +@end group +@end example + +@workswith @code{inher-cont}, @code{member-init-cont}. +@end defun - 1: void spam( int index ) - 2: @{ - 3: for( int i=0; i 0 ); - 16: @} +@comment ------------------------------------------------------------ +@defun c-lineup-java-inher +@findex lineup-java-inher (c-) +Line up Java implements and extends declarations. If class names +follow on the same line as the @samp{implements}/@samp{extends} +keyword, they are lined up under each other. Otherwise, they are +indented by adding @code{c-basic-offset} to the column of the keyword. +E.g: +@example +@group +class Foo + extends + Bar @hereFn{c-lineup-java-inher} + @sssTBasicOffset{} @end group @end example @noindent -Only the lines that illustrate new syntactic symbols will be discussed. - -@cindex substatement-open syntactic symbol -@cindex substatement-block-intro syntactic symbol -@cindex block-close syntactic symbol -Line 4 has a brace which opens a conditional's substatement block. It -is thus assigned @code{substatement-open} syntax, and since line 5 is -the first line in the substatement block, it is assigned -@code{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 @code{block-close}, -as are lines 11 and 14. - -@cindex else-clause syntactic symbol -@cindex substatement syntactic symbol -Line 9 is a little different --- since it contains the keyword -@code{else} matching the @code{if} statement introduced on line 5, it is -given the @code{else-clause} syntax. Note also that line 10 is slightly -different too. Because @code{else} is considered a conditional -introducing keyword @footnote{The list of conditional keywords are (in -C, C++, Objective-C, and Java): @code{for}, @code{if}, @code{do}, -@code{else}, @code{while}, and @code{switch}. C++ and Java have two -additional conditional keywords: @code{try} and @code{catch}. Java also -has the @code{finally} and @code{synchronized} keywords.}, and because -the following substatement is not a brace block, line 10 is assigned the -@code{substatement} syntax. - -@cindex do-while-closure syntactic symbol -One other difference is seen on line 15. The @code{while} construct -that closes a @code{do} conditional is given the special syntax -@code{do-while-closure} if it appears on a line by itself. Note that if -the @code{while} appeared on the same line as the preceding close brace, -that line would have been assigned @code{block-close} syntax instead. +and -Switch statements have their own set of syntactic symbols. Here's an -example: @example @group - - 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: @} - +class Foo + extends Cyphr, + Bar @hereFn{c-lineup-java-inher} @end group @end example -@cindex case-label syntactic symbol -@cindex statement-case-intro syntactic symbol -@cindex statement-case-open syntactic symbol -Here, lines 4, 7, and 10 are all assigned @code{case-label} syntax, -while lines 5 and 8 are assigned @code{statement-case-intro}. Line 11 -is treated slightly differently since it contains a brace that opens a -block --- it is given @code{statement-case-open} syntax. +@workswith @code{inher-cont}. +@end defun + +@comment ------------------------------------------------------------ + +@defun c-lineup-java-throws +@findex lineup-java-throws (c-) +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 @code{c-basic-offset} to the +column of the @samp{throws} keyword. The @samp{throws} keyword itself +is also indented by @code{c-basic-offset} from the function declaration +start if it doesn't hang. E.g: -@cindex brace lists -There are a set of syntactic symbols that are used to recognize -constructs inside of brace lists. A brace list is defined as an -@code{enum} or aggregate initializer list, such as might statically -initialize an array of structs. For example: @example @group +int foo() + throws @hereFn{c-lineup-java-throws} + Bar @hereFn{c-lineup-java-throws} +@sssTsssTBasicOffset{} +@end group +@end example - 1: static char* ingredients[] = - 2: @{ - 3: "Ham", - 4: "Salt", - 5: NULL - 6: @} +@noindent +and +@example +@group +int foo() throws Cyphr, + Bar, @hereFn{c-lineup-java-throws} + Vlod @hereFn{c-lineup-java-throws} @end group @end example -@cindex brace-list-open syntactic symbol -@cindex brace-list-intro syntactic symbol -@cindex brace-list-close syntactic symbol -@cindex brace-list-entry syntactic symbol -Following convention, line 2 in this example is assigned -@code{brace-list-open} syntax, and line 3 is assigned -@code{brace-list-intro} syntax. Likewise, line 6 is assigned -@code{brace-list-close} syntax. Lines 4 and 5 however, are assigned -@code{brace-list-entry} syntax, as would all subsequent lines in this -initializer list. +@workswith @code{func-decl-cont}. +@end defun + +@comment ------------------------------------------------------------ + +@defun c-lineup-template-args +@findex lineup-template-args (c-) +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 @samp{<}. + +To allow this function to be used in a list expression, @code{nil} is +returned if there's no template argument on the first line. + +@workswith @code{template-args-cont}. +@end defun + +@comment ------------------------------------------------------------ + +@defun c-lineup-ObjC-method-call +@findex lineup-ObjC-method-call (c-) +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. + +@workswith @code{objc-method-call-cont}. +@end defun + +@comment ------------------------------------------------------------ + +@defun c-lineup-ObjC-method-args +@findex lineup-ObjC-method-args (c-) +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. + +@workswith @code{objc-method-args-cont}. +@end defun + +@comment ------------------------------------------------------------ + +@defun c-lineup-ObjC-method-args-2 +@findex lineup-ObjC-method-args-2 (c-) +Similar to @code{c-lineup-ObjC-method-args} but lines up the colon on +the current line with the colon on the previous line. + +@workswith @code{objc-method-args-cont}. +@end defun + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Operator Line-Up, Comment Line-Up, List Line-Up, Line-Up Functions +@comment node-name, next, previous, up +@subsection Operator Line-Up Functions +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +The line-up functions here calculate the indentation for lines which +start with an operator, by lining it up with something on the previous +line. + +@defun c-lineup-argcont +@findex lineup-argcont (c-) +Line up a continued argument. E.g: -External language definition blocks also have their own syntactic -symbols. In this example: @example @group +foo (xyz, aaa + bbb + ccc + + ddd + eee + fff); @hereFn{c-lineup-argcont} +@end group +@end example + +Only continuation lines like this are touched, @code{nil} is returned on +lines which are the start of an argument. - 1: extern "C" - 2: @{ - 3: int thing_one( int ); - 4: int thing_two( double ); - 5: @} +Within a gcc @code{asm} block, @code{:} is recognised as an argument +separator, but of course only between operand specifications, not in the +expressions for the operands. +@workswith @code{arglist-cont}, @code{arglist-cont-nonempty}. +@end defun + +@comment ------------------------------------------------------------ + +@defun c-lineup-arglist-operators +@findex lineup-arglist-operators (c-) +Line up lines starting with an infix operator under the open paren. +Return @code{nil} on lines that don't start with an operator, to leave +those cases to other line-up functions. Example: + +@example +@group +if ( x < 10 + || at_limit (x, @hereFn{c-lineup-arglist-operators} + list) @hereFn{c-lineup-arglist-operators@r{ returns nil}} + ) @end group @end example -@cindex extern-lang-open syntactic symbol -@cindex extern-lang-close syntactic symbol -@cindex inextern-lang syntactic symbol -@cindex inclass syntactic symbol -@noindent -line 2 is given the @code{extern-lang-open} syntax, while line 5 is given -the @code{extern-lang-close} syntax. The analysis for line 3 yields: -@code{((inextern-lang) (topmost-intro . 14))}, where -@code{inextern-lang} is a modifier similar in purpose to @code{inclass}. +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 @code{arglist-close} setting is just a +suggestion to get a consistent style): -Similarly, C++ namespace constructs have their own associated syntactic -symbols. In this example: @example -@group +(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)) +@end example + +@workswith @code{arglist-cont}, @code{arglist-cont-nonempty}. +@end defun + +@comment ------------------------------------------------------------ + +@defun c-lineup-assignments +@findex lineup-assignments (c-) +Line up the current line after the assignment operator on the first line +in the statement. If there isn't any, return nil to allow stacking with +other line-up functions. If the current line contains an assignment +operator too, try to align it with the first one. + +@workswith @code{topmost-intro-cont}, @code{statement-cont}, +@code{arglist-cont}, @code{arglist-cont-nonempty}. + +@end defun - 1: namespace foo - 2: @{ - 3: void xxx() @{@} - 4: @} +@comment ------------------------------------------------------------ +@defun c-lineup-math +@findex lineup-math (c-) +Like @code{c-lineup-assignments} but indent with @code{c-basic-offset} +if no assignment operator was found on the first line. I.e. this +function is the same as specifying a list @code{(c-lineup-assignments ++)}. It's provided for compatibility with old configurations. + +@workswith @code{topmost-intro-cont}, @code{statement-cont}, +@code{arglist-cont}, @code{arglist-cont-nonempty}. +@end defun + +@comment ------------------------------------------------------------ + +@defun c-lineup-cascaded-calls +@findex lineup-cascaded-calls (c-) +Line up ``cascaded calls'' under each other. If the line begins with +@code{->} or @code{.} 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: + +@example +@group +r = proc->add(17)->add(18) + ->add(19) + @hereFn{c-lineup-cascaded-calls} + offset; @hereFn{c-lineup-cascaded-calls@r{ (inactive)}} @end group @end example -@cindex namespace-open syntactic-symbol -@cindex namespace-close syntactic-symbol -@cindex innamespace syntactic-symbol -@noindent -line 2 is given the @code{namespace-open} syntax, while line 4 is given -the @code{namespace-close} syntax. The analysis for line 3 yields: -@code{((innamespace) (topmost-intro . 17))}, where @code{innamespace} is -a modifier similar in purpose to @code{inextern-lang} and @code{inclass}. +In any other situation @code{nil} is returned to allow use in list +expressions. + +@workswith @code{topmost-intro-cont}, @code{statement-cont}, +@code{arglist-cont}, @code{arglist-cont-nonempty}. +@end defun + +@comment ------------------------------------------------------------ + +@defun c-lineup-streamop +@findex lineup-streamop (c-) +Line up C++ stream operators (i.e. @samp{<<} and @samp{>>}). + +@workswith @code{stream-op}. +@end defun + +@comment ------------------------------------------------------------ + +@defun c-lineup-string-cont +@findex lineup-string-cont (c-) +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: -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: @example @group +result = prefix + "A message " + "string."; @hereFn{c-lineup-string-cont} +@end group +@end example + +@code{nil} is returned in other situations, to allow stacking with other +lineup functions. + +@workswith @code{topmost-intro-cont}, @code{statement-cont}, +@code{arglist-cont}, @code{arglist-cont-nonempty}. +@end defun + + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Comment Line-Up, Misc Line-Up, Operator Line-Up, Line-Up Functions +@comment node-name, next, previous, up +@subsection Comment Line-Up Functions +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - 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: @} +The lineup functions here calculate the indentation for several types +of comment structure. + +@defun c-lineup-C-comments +@findex lineup-C-comments (c-) +Line up C block comment continuation lines. Various heuristics are used +to handle most of the common comment styles. Some examples: +@example +@group +/* /** /* + * text * text text + */ */ */ @end group @end example -@cindex arglist-intro syntactic symbol -@cindex arglist-close syntactic symbol -Lines 5 and 12 are assigned @code{arglist-intro} syntax since they are -the first line following the open parenthesis, and lines 7 and 14 are -assigned @code{arglist-close} syntax since they contain the parenthesis -that closes the argument list. - -@cindex arglist-cont-nonempty syntactic symbol -@cindex arglist-cont syntactic symbol -Lines that continue argument lists can be assigned one of two syntactic -symbols. For example, Lines 2 and 17 -are assigned @code{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 @emph{not empty} following the open -parenthesis. Contrast this against lines 6 and 13 which are assigned -@code{arglist-cont} syntax. This is because the parenthesis that opens -their argument lists is the last character on that line. +@example +@group +/* text /* /** + text ** text ** text +*/ */ */ +@end group +@end example -Note that there is no @code{arglist-open} syntax. This is because any -parenthesis that opens an argument list, appearing on a separate line, -is assigned the @code{statement-cont} syntax instead. +@example +@group +/************************************************** + * text + *************************************************/ +@end group +@end example -A few miscellaneous syntactic symbols that haven't been previously -covered are illustrated by this C++ example: +@vindex comment-start-skip @example @group +/************************************************** + 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 + @code{comment-start-skip} regexp. +**************************************************/ +@end group +@end 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 style variable @code{c-comment-prefix-regexp} is used to recognize +the comment line prefix, e.g. the @samp{*} that usually starts every +line inside a comment. -@end group +@workswith The @code{c} syntactic symbol. +@end defun + +@comment ------------------------------------------------------------ + +@defun c-lineup-comment +@findex lineup-comment (c-) +Line up a comment-only line according to the style variable +@code{c-comment-only-line-offset}. If the comment is lined up with a +comment starter on the previous line, that alignment is preserved. + +@defopt c-comment-only-line-offset +@vindex comment-only-line-offset (c-) +This style variable specifies the extra offset for the line. It can +contain an integer or a cons cell of the form + +@example +(@r{@var{non-anchored-offset}} . @r{@var{anchored-offset}}) @end example -@cindex modifier syntactic symbol -The lines to note in this example include: +@noindent +where @var{non-anchored-offset} is the amount of offset given to +non-column-zero anchored lines, and @var{anchored-offset} is the amount +of offset to give column-zero anchored lines. Just an integer as value +is equivalent to @code{(@r{@var{value}} . -1000)}. +@end defopt -@itemize @bullet +@workswith @code{comment-intro}. +@end defun -@cindex func-decl-cont syntactic symbol -@item -line 2, assigned the @code{func-decl-cont} syntax; +@comment ------------------------------------------------------------ -@cindex comment-intro syntactic symbol -@item -line 4, assigned both @code{defun-block-intro} @emph{and} -@code{comment-intro} syntax; +@defun c-lineup-knr-region-comment +@findex lineup-knr-region-comment (c-) +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: -@cindex c syntactic symbol -@item -line 5, assigned @code{c} syntax; +@example +@group +int main() +/* Called at startup. */ @hereFn{c-lineup-knr-region-comment} +@{ + return 0; +@} +@end group +@end example -@item -@cindex syntactic whitespace -line 6 which, even though it contains nothing but whitespace, is -assigned @code{defun-block-intro}. Note that the appearance of the -comment on lines 4 and 5 do not cause line 6 to be assigned -@code{statement} syntax because comments are considered to be -@dfn{syntactic whitespace}, which are ignored when analyzing -code; +Return @code{nil} if called in any other situation, to be useful in list +expressions. -@cindex string syntactic symbol -@item -line 8, assigned @code{string} syntax; +@workswith @code{comment-intro}. +@end defun -@cindex label syntactic symbol -@item -line 10, assigned @code{label} syntax; +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Misc Line-Up, , Comment Line-Up, Line-Up Functions +@comment node-name, next, previous, up +@subsection Miscellaneous Line-Up Functions +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@cindex block-open syntactic symbol -@item -line 11, assigned @code{block-open} syntax; +The line-up functions here are the odds and ends which didn't fit into +any earlier category. -@cindex cpp-macro syntactic symbol -@cindex cpp-macro-cont syntactic symbol -@item -lines 12 and 14, assigned @code{cpp-macro} syntax. +@defun c-lineup-dont-change +@findex lineup-dont-change (c-) +This lineup function makes the line stay at whatever indentation it +already has; think of it as an identity function for lineups. -@cindex stream-op syntactic symbol -@item -line 17, assigned @code{stream-op} syntax. +@workswith Any syntactic symbol. +@end defun -@end itemize +@comment ------------------------------------------------------------ + +@defun c-lineup-cpp-define +@findex lineup-cpp-define (c-) +Line up macro continuation lines according to the indentation of the +construct preceding the macro. E.g: -@cindex multi-line macros -@cindex syntactic whitespace -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: @example @group +const char msg[] = @hereFn{@r{The beginning of the preceding construct.}} + \"Some text.\"; - 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 - +#define X(A, B) \ +do @{ \ @hereFn{c-lineup-cpp-define} + printf (A, B); \ +@} while (0) @end group @end example + @noindent -line 1 is given the syntactic symbol @code{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 @code{cpp-macro-cont} syntactic -symbol, with a relative buffer position pointing to the @code{#} which -starts the macro definition. +and: -In Objective-C buffers, there are three additional syntactic symbols -assigned to various message calling constructs. Here's an example -illustrating these: @example @group - - 1: - (void)setDelegate:anObject - 2: withStuff:stuff - 3: @{ - 4: [delegate masterWillRebind:self - 5: toDelegate:anObject - 6: withExtraStuff:stuff]; - 7: @} - +int dribble() @{ + if (!running) @hereFn{@r{The beginning of the preceding construct.}} + error(\"Not running!\"); + +#define X(A, B) \ + do @{ \ @hereFn{c-lineup-cpp-define} + printf (A, B); \ + @} while (0) @end group @end example -@cindex objc-method-intro syntactic symbol -@cindex objc-method-args-cont syntactic symbol -@cindex objc-method-call-cont syntactic symbol -Here, line 1 is assigned @code{objc-method-intro} syntax, and line 2 is -assigned @code{objc-method-args-cont} syntax. Lines 5 and 6 are both -assigned @code{objc-method-call-cont} syntax. +If @code{c-syntactic-indentation-in-macros} is non-@code{nil}, the +function returns the relative indentation to the macro start line to +allow accumulation with other offsets. E.g. in the following cases, +@code{cpp-define-intro} is combined with the +@code{statement-block-intro} that comes from the @samp{do @{} that hangs +on the @samp{#define} line: -@cindex knr-argdecl-intro syntactic symbol -@cindex knr-argdecl syntactic symbol -Two other syntactic symbols can appear in old style, non-prototyped C -code @footnote{a.k.a. K&R C, or Kernighan & Ritchie C}: @example @group +const char msg[] = + \"Some text.\"; - 1: int add_three_integers(a, b, c) - 2: int a; - 3: int b; - 4: int c; - 5: @{ - 6: return a + b + c; - 7: @} - +#define X(A, B) do @{ \ + printf (A, B); \ @hereFn{c-lineup-cpp-define} + this->refs++; \ +@} while (0) @hereFn{c-lineup-cpp-define} @end group @end example -Here, line 2 is the first line in an argument declaration list and so is -given the @code{knr-argdecl-intro} syntactic symbol. Subsequent lines -(i.e. lines 3 and 4 in this example), are given @code{knr-argdecl} -syntax. +@noindent +and: -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Performance Issues, Frequently Asked Questions, Syntactic Symbols, Top -@comment node-name, next, previous,up +@example +@group +int dribble() @{ + if (!running) + error(\"Not running!\"); + +#define X(A, B) do @{ \ + printf (A, B); \ @hereFn{c-lineup-cpp-define} + this->refs++; \ + @} while (0) @hereFn{c-lineup-cpp-define} +@end group +@end example -@chapter Performance Issues -@cindex Performance Issues -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +The relative indentation returned by @code{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 +@code{statement-block-intro} gives in both cases here. -C and its derivative languages are highly complex creatures. Often, -ambiguous code situations arise that require @ccmode{} to scan -large portions of the buffer to determine syntactic context. Such -pathological code@footnote{such as the output of @code{lex(1)}!} -can cause @ccmode{} 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. +If the relative indentation is zero, then @code{nil} is returned +instead. That is useful in a list expression to specify the default +indentation on the top level. -Because @ccmode{} 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, @ccmode{} 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 @ccmode{} -to scan from the beginning of the buffer for every line of code! +If @code{c-syntactic-indentation-in-macros} is @code{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. -@findex beginning-of-defun -@findex defun-prompt-regexp -One of the simplest things you can do to reduce scan time, is make sure -any brace that opens a top-level construct@footnote{e.g. a function in -C, or outermost class definition in C++ or Java.} always appears in the -leftmost column. This is actually an Emacs constraint, as embodied in -the @code{beginning-of-defun} function which @ccmode{} 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 -@code{defun-prompt-regexp} to something reasonable @footnote{Note that -this variable is only defined in Emacs 19.}, however that ``something -reasonable'' is difficult to define, so @ccmode{} doesn't do it -for you. +@workswith @code{cpp-define-intro}. +@end defun -@vindex c-Java-defun-prompt-regexp -@vindex Java-defun-prompt-regexp (c-) -A special note about @code{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. @ccmode{} comes with a variable -@code{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 @code{beginning-of-defun} to hang@footnote{This -has been observed in Emacs 19.34 and XEmacs 19.15.}. For this reason, -it is not used by default, but if you feel adventurous, you can set -@code{defun-prompt-regexp} to it in your mode hook. In any event, -setting and rely on @code{defun-prompt-regexp} will definitely slow -things down! - -You will probably notice pathological behavior from @ccmode{} 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 comment. - -@vindex c-recognize-knr-p -@vindex recognize-knr-p (c-) -Previous versions of @ccmode{} 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@footnote{It is hard to distinguish them from top-level -declarations.}. @ccmode{} 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 @ccmode{}, user customization of -@code{c-recognize-knr-p} is deprecated. Just don't put argdecls in -column zero! - -@cindex @file{cc-lobotomy.el} file -@vindex cc-lobotomy-pith-list -You might want to investigate the speed-ups contained in the -file @file{cc-lobotomy.el}, which comes as part of the @ccmode{} -distribution, but is completely unsupported. -As mentioned previous, @ccmode{} always trades speed for accuracy, -however it is recognized that sometimes you need speed and can sacrifice -some accuracy in indentation. The file @file{cc-lobotomy.el} contains -hacks that will ``dumb down'' @ccmode{} 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 @code{cc-lobotomy-pith-list} for details. - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Frequently Asked Questions, Getting the latest CC Mode release, Performance Issues, Top -@comment node-name, next, previous,up - -@chapter Frequently Asked Questions -@cindex Frequently Asked Questions -@comment FAQ -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@comment ------------------------------------------------------------ -@kindex C-x h -@kindex ESC C-\ -@kindex ESC C-x -@kindex C-c C-q -@kindex ESC C-q -@kindex ESC C-u -@kindex RET -@kindex C-j -@findex newline-and-indent -@quotation +@defun c-lineup-gcc-asm-reg +@findex lineup-gcc-asm-reg (c-) +Line up a gcc asm register under one on a previous line. -@strong{Q.} @emph{How do I re-indent the whole file?} +@example +@group + asm ("foo %1, %0\n" + "bar %0, %1" + : "=r" (w), + "=r" (x) + : "0" (y), + "1" (z)); +@end group +@end example -@strong{A.} Visit the file and hit @kbd{C-x h} to mark the whole -buffer. Then hit @kbd{ESC C-\}. -@sp 1 +The @samp{x} line is aligned to the text after the @samp{:} on the +@samp{w} line, and similarly @samp{z} under @samp{y}. -@strong{Q.} @emph{How do I re-indent the entire function? -@kbd{ESC C-x} doesn't work.} +This is done only in an @samp{asm} or @samp{__asm__} block, and only to +those lines mentioned. Anywhere else @code{nil} is returned. The usual +arrangement is to have this routine as an extra feature at the start of +arglist lineups, e.g. -@strong{A.} @kbd{ESC C-x} is reserved for future Emacs use. -To re-indent the entire function hit @kbd{C-c C-q}. -@sp 1 +@example +(c-lineup-gcc-asm-reg c-lineup-arglist) +@end example -@strong{Q.} @emph{How do I re-indent the current block?} +@workswith @code{arglist-cont}, @code{arglist-cont-nonempty}. +@end defun -@strong{A.} First move to the brace which opens the block with -@kbd{ESC C-u}, then re-indent that expression with -@kbd{ESC C-q}. -@sp 1 +@comment ------------------------------------------------------------ -@strong{Q.} @emph{Why doesn't the @kbd{RET} key indent the line to -where the new text should go after inserting the newline?} +@defun c-lineup-topmost-intro-cont +@findex lineup-topmost-intro-cont (c-) +Line up declaration continuation lines zero or one indentation +step@footnote{This function is mainly provided to mimic the behavior of +CC Mode 5.28 and earlier where this case wasn't handled consistently so +that those lines could be analyzed as either topmost-intro-cont or +statement-cont. It's used for @code{topmost-intro-cont} by default, but +you might consider using @code{+} instead.}. For lines preceding a +definition, zero is used. For other lines, @code{c-basic-offset} is +added to the indentation. E.g: -@strong{A.} Emacs' 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-mode-common-hook} (see the sample @file{.emacs} file -@ref{Sample .emacs File}): @example - -(define-key c-mode-base-map "\C-m" 'newline-and-indent) - +@group +int +neg (int i) @hereFn{c-lineup-topmost-intro-cont} +@{ + return -i; +@} +@end group @end example -This is a very common question. If you want this to be the default -behavior, don't lobby me, lobby RMS! @code{:-)} -@sp 1 - -@strong{Q.} @emph{I put @code{(c-set-offset 'substatement-open 0)} -in my @file{.emacs} file but I get an error saying that -@code{c-set-offset}'s function definition is void.} +@noindent +and -@strong{A.} This means that @ccmode{} wasn't loaded into your -Emacs session by the time the @code{c-set-offset} call was reached, -mostly likely because @ccmode{} is being autoloaded. Instead -of putting the @code{c-set-offset} line in your top-level -@file{.emacs} file, put it in your @code{c-mode-common-hook}, or -simply add the following to the top of your @file{.emacs} file: @example - -(require 'cc-mode) - +@group +struct +larch @hereFn{c-lineup-topmost-intro-cont} +@{ + double height; +@} + the_larch, @hereFn{c-lineup-topmost-intro-cont} + another_larch; @hereFn{c-lineup-topmost-intro-cont} +@sssTBasicOffset{} +@end group @end example -See the sample @file{.emacs} file @ref{Sample .emacs File} for -details. +@noindent +and -@sp 1 -@strong{Q.} @emph{How do I make strings, comments, keywords, and other -constructs appear in different colors, or in bold face, etc.?} +@example +@group +struct larch +the_larch, @hereFn{c-lineup-topmost-intro-cont} + another_larch; @hereFn{c-lineup-topmost-intro-cont} +@end group +@end example -@strong{A.} ``Syntax Colorization'' is a standard Emacs feature, -controlled by @code{font-lock-mode}. It is not part of @ccmode{}. +@workswith @code{topmost-intro-cont}. +@end defun -@sp 1 -@strong{Q.} @emph{@kbd{M-a} and @kbd{M-e} used to move over entire -balanced brace lists, but now they move into blocks. How do I get the -old behavior back?} +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Custom Line-Up, Other Indentation, Line-Up Functions, Customizing Indentation +@comment node-name, next, previous, up +@section Custom Line-Up Functions +@cindex customization, indentation functions +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@strong{A.} Use @kbd{C-M-f} and @kbd{C-M-b} to move over balanced brace -blocks. Use @kbd{M-a} and @kbd{M-e} to move by statements, which will -move into blocks. +The most flexible way to customize indentation is by writing custom +line-up functions, and associating them with specific syntactic +symbols (@pxref{c-offsets-alist}). Depending on the effect you want, +it might be better to write a @code{c-special-indent-hook} function +rather than a line-up function (@pxref{Other Indentation}). + +@ccmode{} comes with an extensive set of predefined line-up functions, +not all of which are used by the default styles. So there's a good +chance the function you want already exists. @xref{Line-Up +Functions}, for a list of them. If you write your own line-up +function, it's probably a good idea to start working from one of these +predefined functions, which can be found in the file +@file{cc-align.el}. If you have written a line-up function that you +think is generally useful, you're very welcome to contribute it; +please contact @email{bug-cc-mode@@gnu.org}. + + Line-up functions are passed a single argument, the syntactic +element (see below). The return value is a @code{c-offsets-alist} +offset specification: for example, an integer, a symbol such as +@code{+}, a vector, @code{nil}@footnote{Returning @code{nil} is useful +when the offset specification for a syntactic element is a list +containing the line-up function (@pxref{c-offsets-alist}).}, or even +another line-up function. Full details of these are in +@ref{c-offsets-alist}. + +Line-up functions must not move point or change the content of the +buffer (except temporarily). They are however allowed to do +@dfn{hidden buffer changes}, i.e. setting text properties for caching +purposes etc. Buffer undo recording is disabled while they run. + +The syntactic element passed as the parameter to a line-up function is +a cons cell of the form -@end quotation +@example +(@r{@var{syntactic-symbol}} . @r{@var{anchor-position}}) +@end example +@noindent +@c FIXME!!! The following sentence might be better omitted, since the +@c information is in the cross reference "Syntactic Analysis". 2005/10/2. +where @var{syntactic-symbol} is the symbol that the function was +called for, and @var{anchor-position} is the anchor position (if any) +for the construct that triggered the syntactic symbol +(@pxref{Syntactic Analysis}). This cons cell is how the syntactic +element of a line used to be represented in @ccmode{} 5.28 and +earlier. Line-up functions are still passed this cons cell, so as to +preserve compatibility with older configurations. In the future, we +may decide to convert to using the full list format---you can prepare +your setup for this by using the access functions +(@code{c-langelem-sym}, etc.) described below. + +@vindex c-syntactic-element +@vindex syntactic-element (c-) +@vindex c-syntactic-context +@vindex syntactic-context (c-) +Some syntactic symbols, e.g. @code{arglist-cont-nonempty}, have more +info in the syntactic element - typically other positions that can be +interesting besides the anchor position. That info can't be accessed +through the passed argument, which is a cons cell. Instead, you can +get this information from the variable @code{c-syntactic-element}, +which is dynamically bound to the complete syntactic element. The +variable @code{c-syntactic-context} might also be useful - it gets +dynamically bound to the complete syntactic context. @xref{Custom +Braces}. + +@ccmode{} provides a few functions to access parts of syntactic +elements in a more abstract way. Besides making the code easier to +read, they also hide the difference between the old cons cell form +used in the line-up function argument and the new list form used in +@code{c-syntactic-element} and everywhere else. The functions are: + +@defun c-langelem-sym langelem +@findex langelem-sym (c-) +Return the syntactic symbol in @var{langelem}. +@end defun + +@defun c-langelem-pos langelem +@findex langelem-pos (c-) +Return the anchor position in @var{langelem}, or nil if there is none. +@end defun + +@defun c-langelem-col langelem &optional preserve-point +@findex langelem-col (c-) +Return the column of the anchor position in @var{langelem}. Also move +the point to that position unless @var{preserve-point} is +non-@code{nil}. +@end defun + +@defun c-langelem-2nd-pos langelem +@findex langelem-2nd-pos (c-) +Return the secondary position in @var{langelem}, or @code{nil} if there +is none. + +Note that the return value of this function is always @code{nil} if +@var{langelem} is in the old cons cell form. Thus this function is +only meaningful when used on syntactic elements taken from +@code{c-syntactic-element} or @code{c-syntactic-context}. +@end defun + +Custom line-up functions can be as simple or as complex as you like, and +any syntactic symbol that appears in @code{c-offsets-alist} can have a +custom line-up function associated with it. @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Getting the latest CC Mode release, Sample .emacs File, Frequently Asked Questions, Top -@comment node-name, next, previous,up - -@chapter Getting the latest CC Mode release -@cindex Getting the latest CC Mode release +@node Other Indentation, , Custom Line-Up, Customizing Indentation +@comment node-name, next, previous, up +@section Other Special Indentations @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@ccmode{} is now standard with the latest versions of Emacs 19 and -XEmacs 19. It is also the standard for Emacs 20 and XEmacs 20. You -would typically just use the version that comes with your X/Emacs. -These may be slightly out of date due to release schedule skew, so you -should always check the canonical site for the latest version. - -@example -@group +Here are the remaining odds and ends regarding indentation: - World Wide Web: - - @code{http://www.python.org/ftp/emacs/} +@defopt c-label-minimum-indentation +@vindex label-minimum-indentation (c-) +In @samp{gnu} style (@pxref{Built-in Styles}), a minimum indentation is +imposed on lines inside code blocks. This minimum indentation is +controlled by this style variable. The default value is 1. + +@findex c-gnu-impose-minimum +@findex gnu-impose-minimum (c-) +It's the function @code{c-gnu-impose-minimum} that enforces this minimum +indentation. It must be present on @code{c-special-indent-hook} to +work. +@end defopt + +@defopt c-special-indent-hook +@vindex special-indent-hook (c-) +This style variable is a standard hook variable that is called after +every line is indented by @ccmode{}. It is called only if +@code{c-syntactic-indentation} is non-@code{nil} (which it is by +default (@pxref{Indentation Engine Basics})). You can put a function +on this hook to do any special indentation or ad hoc line adjustments +your style dictates, such as adding extra indentation to constructors +or destructor declarations in a class definition, etc. Sometimes it +is better to write a custom Line-up Function instead (@pxref{Custom +Line-Up}). + +When the indentation engine calls this hook, the variable +@code{c-syntactic-context} is bound to the current syntactic context +(i.e. what you would get by typing @kbd{C-c C-s} on the source line. +@xref{Custom Braces}.). Note that you should not change point or mark +inside a @code{c-special-indent-hook} function, i.e. you'll probably +want to wrap your function in a @code{save-excursion}@footnote{The +numerical value returned by @code{point} will change if you change the +indentation of the line within a @code{save-excursion} form, but point +itself will still be over the same piece of text.}. + +Setting @code{c-special-indent-hook} in style definitions is handled +slightly differently from other variables---A style can only add +functions to this hook, not remove them. @xref{Style Variables}. +@end defopt - Anonymous FTP: - @code{ftp://ftp.python.org/pub/emacs/} +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Custom Macros, Odds and Ends, Customizing Indentation, Top +@comment node-name, next, previous, up +@chapter Customizing Macros +@cindex macros +@cindex preprocessor directives +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@end group -@end example +Normally, the lines in a multi-line macro are indented relative to +each other as though they were code. You can suppress this behaviour +by setting the following user option: + +@defopt c-syntactic-indentation-in-macros +@vindex syntactic-indentation-in-macros (c-) +Enable syntactic analysis inside macros, which is the default. If this +is @code{nil}, all lines inside macro definitions are analyzed as +@code{cpp-macro-cont}. +@end defopt + +@ccmode{} provides some tools to help keep the line continuation +backslashes in macros neat and tidy. Their precise action is +customized with these variables: + +@defopt c-backslash-column +@vindex backslash-column (c-) +@defoptx c-backslash-max-column +@vindex backslash-max-column (c-) +These variables control the alignment columns for line continuation +backslashes in multiline macros. They are used by the functions that +automatically insert or align such backslashes, +e.g. @code{c-backslash-region} and @code{c-context-line-break}. + +@code{c-backslash-column} specifies the minimum column for the +backslashes. If any line in the macro goes past this column, then the +next tab stop (i.e. next multiple of @code{tab-width}) in that line is +used as the alignment column for all the backslashes, so that they +remain in a single column. However, if any lines go past +@code{c-backslash-max-column} then the backslashes in the rest of the +macro will be kept at that column, so that the lines which are too +long ``stick out'' instead. + +Don't ever set these variables to @code{nil}. If you want to disable +the automatic alignment of backslashes, use +@code{c-auto-align-backslashes}. +@end defopt + +@defopt c-auto-align-backslashes +@vindex auto-align-backslashes (c-) +Align automatically inserted line continuation backslashes if +non-@code{nil}. When line continuation backslashes are inserted +automatically for line breaks in multiline macros, e.g. by +@code{c-context-line-break}, they are aligned with the other +backslashes in the same macro if this flag is set. + +If @code{c-auto-align-backslashes} is @code{nil}, automatically +inserted backslashes are preceded by a single space, and backslashes +get aligned only when you explicitly invoke the command +@code{c-backslash-region} (@kbd{C-c C-\}). +@end defopt -There are many files under these directories; you can pick up the entire -distribution (named @code{cc-mode.tar.gz}; a gzip'd tar file), or any of -the individual files, including PostScript documentation. +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Odds and Ends, Sample .emacs File, Custom Macros, Top +@comment node-name, next, previous, up +@chapter Odds and Ends +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -If you do not have World Wide Web, or anonymous ftp access, you can get -the distribution through an anonymous ftp-to-mail gateway, such as the -one run by DEC at: -@example +The stuff that didn't fit in anywhere else is documented here. -@code{ftpmail@@decwrl.dec.com} +@defopt c-require-final-newline +@vindex require-final-newline (c-) +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 +language isn't present on the association list, CC Mode won't touch +@code{require-final-newline} in buffers for that language. -@end example -To get @ccmode{} via email, send the following message in the body of -your mail to that address: -@example +The default is to set @code{require-final-newline} to @code{t} in the +languages that mandate that source files should end with newlines. +These are C, C++ and Objective-C. +@end defopt -reply -connect ftp.python.org -binary -uuencode -chdir pub/emacs -get cc-mode.tar.gz +@defopt c-echo-syntactic-information-p +@vindex echo-syntactic-information-p (c-) +If non-@code{nil}, the syntactic analysis for the current line is shown +in the echo area when it's indented (unless +@code{c-syntactic-indentation} is @code{nil}). That's useful when +finding out which syntactic symbols to modify to get the indentation you +want. +@end defopt + +@defopt c-report-syntactic-errors +@vindex report-syntactic-errors (c-) +If non-@code{nil}, certain syntactic errors are reported with a ding and +a message, for example when an @code{else} is indented for which there +is no corresponding @code{if}. + +Note however that @ccmode{} doesn't make any special effort to check for +syntactic errors; that's the job of the compiler. The reason it can +report cases like the one above is that it can't find the correct +anchoring position to indent the line in that case. +@end defopt -@end example -@noindent -or just send the message "help" for more information on ftpmail. -Response times will vary with the number of requests in the queue. I am -in no way connected to this service, so I make no claims or guarantees -about its availability! @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Sample .emacs File, Limitations and Known Bugs, Getting the latest CC Mode release, Top -@comment node-name, next, previous,up - -@chapter Sample .emacs file -@cindex Sample .emacs file +@node Sample .emacs File, Performance Issues, Odds and Ends, Top +@comment node-name, next, previous, up +@appendix Sample .emacs File @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@example -;; Here's a sample .emacs file that might help you along the way. Just -;; copy this region and paste it into your .emacs file. You may want to -;; change some of the actual values. +Here's a sample .emacs file fragment that might help you along the way. +Just copy this region and paste it into your .emacs file. You might want +to change some of the actual values. + +@verbatim +;; Make a non-standard key binding. We can put this in +;; c-mode-base-map because c-mode-map, c++-mode-map, and so on, +;; inherit from it. +(defun my-c-initialization-hook () + (define-key c-mode-base-map "\C-m" 'c-context-line-break)) +(add-hook 'c-initialization-hook 'my-c-initialization-hook) +;; offset customizations not in my-c-style +;; This will take precedence over any setting of the syntactic symbol +;; made by a style. +(setq c-offsets-alist '((member-init-intro . ++))) + +;; Create my personal style. (defconst my-c-style '((c-tab-always-indent . t) (c-comment-only-line-offset . 4) @@ -3413,148 +6598,398 @@ about its availability! (case-label . 4) (block-open . 0) (knr-argdecl-intro . -))) - (c-echo-syntactic-information-p . t) - ) + (c-echo-syntactic-information-p . t)) "My C Programming Style") +(c-add-style "PERSONAL" my-c-style) -;; Customizations for all of c-mode, c++-mode, and objc-mode +;; Customizations for all modes in CC Mode. (defun my-c-mode-common-hook () - ;; add my personal style and set it for the current buffer - (c-add-style "PERSONAL" my-c-style t) - ;; offset customizations not in my-c-style - (c-set-offset 'member-init-intro '++) + ;; set my personal style for the current buffer + (c-set-style "PERSONAL") ;; other customizations (setq tab-width 8 ;; this will make sure spaces are used instead of tabs indent-tabs-mode nil) - ;; we like auto-newline and hungry-delete - (c-toggle-auto-hungry-state 1) - ;; keybindings for all supported languages. We can put these in - ;; c-mode-base-map because c-mode-map, c++-mode-map, objc-mode-map, - ;; java-mode-map, and idl-mode-map inherit from it. - (define-key c-mode-base-map "\C-m" 'newline-and-indent) - ) - + ;; we like auto-newline, but not hungry-delete + (c-toggle-auto-newline 1)) (add-hook 'c-mode-common-hook 'my-c-mode-common-hook) -@end example +@end verbatim + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Performance Issues, Limitations and Known Bugs, Sample .emacs File, Top +@comment node-name, next, previous, up +@chapter Performance Issues +@cindex performance +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +@comment FIXME: (ACM, 2003/5/24). Check whether AWK needs mentioning here. + +C and its derivative languages are highly complex creatures. Often, +ambiguous code situations arise that require @ccmode{} to scan large +portions of the buffer to determine syntactic context. Such +pathological code can cause @ccmode{} to perform fairly badly. This +section gives some insight in how @ccmode{} operates, how that interacts +with some coding styles, and what you can use to improve performance. + +The overall goal is that @ccmode{} shouldn't be overly slow (i.e. take +more than a fraction of a second) in any interactive operation. +I.e. it's tuned to limit the maximum response time in single operations, +which is sometimes at the expense of batch-like operations like +reindenting whole blocks. If you find that @ccmode{} gradually gets +slower and slower in certain situations, perhaps as the file grows in +size or as the macro or comment you're editing gets bigger, then chances +are that something isn't working right. You should consider reporting +it, unless it's something that's mentioned in this section. + +Because @ccmode{} 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, @ccmode{} often tries to find the nearest +position higher up in the buffer from which to begin a forward scan +(it's typically an opening or closing parenthesis of some kind). The +farther this position is from the current insertion point, the slower it +gets. + +@findex beginning-of-defun +In earlier versions of @ccmode{}, we used to recommend putting the +opening brace of a top-level construct@footnote{E.g. a function in C, +or outermost class definition in C++ or Java.} into the leftmost +column. Earlier still, this used to be a rigid Emacs constraint, as +embodied in the @code{beginning-of-defun} function. @ccmode now +caches syntactic information much better, so that the delay caused by +searching for such a brace when it's not in column 0 is minimal, +except perhaps when you've just moved a long way inside the file. + +@findex defun-prompt-regexp +@vindex c-Java-defun-prompt-regexp +@vindex Java-defun-prompt-regexp (c-) +A special note about @code{defun-prompt-regexp} in Java mode: The common +style is to hang the opening braces of functions and classes on the +right side of the line, and that doesn't work well with the Emacs +approach. @ccmode{} comes with a constant +@code{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 @code{beginning-of-defun} to hang@footnote{This +has been observed in Emacs 19.34 and XEmacs 19.15.}. For this reason, +it is not used by default, but if you feel adventurous, you can set +@code{defun-prompt-regexp} to it in your mode hook. In any event, +setting and relying on @code{defun-prompt-regexp} will definitely slow +things down because (X)Emacs will be doing regular expression searches a +lot, so you'll probably be taking a hit either way! + +@ccmode{} maintains a cache of the opening parentheses of the blocks +surrounding the point, and it adapts that cache as the point is moved +around. That means that in bad cases it can take noticeable time to +indent a line in a new surrounding, but after that it gets fast as long +as the point isn't moved far off. The farther the point is moved, the +less useful is the cache. Since editing typically is done in ``chunks'' +rather than on single lines far apart from each other, the cache +typically gives good performance even when the code doesn't fit the +Emacs approach to finding the defun starts. + +@vindex c-enable-xemacs-performance-kludge-p +@vindex enable-xemacs-performance-kludge-p (c-) +XEmacs users can set the variable +@code{c-enable-xemacs-performance-kludge-p} to non-@code{nil}. This +tells @ccmode{} to use XEmacs-specific built-in functions which, in some +circumstances, can locate the top-most opening brace much more quickly than +@code{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 @emph{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 @code{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 +21.3 as of this writing in May 2003). + +Text properties are used to speed up skipping over syntactic whitespace, +i.e. comments and preprocessor directives. Indenting a line after a +huge macro definition can be slow the first time, but after that the +text properties are in place and it should be fast (even after you've +edited other parts of the file and then moved back). + +Font locking can be a CPU hog, especially the font locking done on +decoration level 3 which tries to be very accurate. Note that that +level is designed to be used with a font lock support mode that only +fontifies the text that's actually shown, i.e. Lazy Lock or Just-in-time +Lock mode, so make sure you use one of them. Fontification of a whole +buffer with some thousand lines can often take over a minute. That is +a known weakness; the idea is that it never should happen. + +The most effective way to speed up font locking is to reduce the +decoration level to 2 by setting @code{font-lock-maximum-decoration} +appropriately. That level is designed to be as pretty as possible +without sacrificing performance. @xref{Font Locking Preliminaries}, for +more info. + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Limitations and Known Bugs, Mailing Lists and Submitting Bug Reports, Sample .emacs File, Top -@comment node-name, next, previous,up -@chapter Limitations and Known Bugs -@cindex Limitations and Known Bugs -@comment * Limitations and Known Bugs +@node Limitations and Known Bugs, FAQ, Performance Issues, Top +@comment node-name, next, previous, up +@chapter Limitations and Known Bugs +@cindex limitations +@cindex bugs @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @itemize @bullet @item -Re-indenting large regions or expressions can be slow. +@ccmode{} doesn't support trigraphs. (These are character sequences +such as @samp{??(}, which represents @samp{[}. They date from a time +when some character sets didn't have all the characters that C needs, +and are now utterly obsolete.) + +@item +There is no way to apply auto newline settings (@pxref{Auto-newlines}) +on already typed lines. That's only a feature to ease interactive +editing. + +To generalize this issue a bit: @ccmode{} is not intended to be used as +a reformatter for old code in some more or less batch-like way. With +the exception of some functions like @code{c-indent-region}, it's only +geared to be used interactively to edit new code. There's currently no +intention to change this goal. + +If you want to reformat old code, you're probably better off using some +other tool instead, e.g. @ref{Top, , GNU indent, indent, The `indent' +Manual}, which has more powerful reformatting capabilities than +@ccmode{}. + +@item +The support for C++ templates (in angle brackets) is not yet complete. +When a non-nested template is used in a declaration, @ccmode{} indents +it and font-locks it OK. Templates used in expressions, and nested +templates do not fare so well. Sometimes a workaround is to refontify +the expression after typing the closing @samp{>}. + +@item +On loading @ccmode{}, sometimes this error message appears: + +@example +File mode specification error: (void-variable c-font-lock-keywords-3) +@end example + +This is due to a bug in the function @code{eval-after-load} in some +versions of (X)Emacs. It can manifest itself when there is a symbolic +link in the path of the directory which contains (X)Emacs. As a +workaround, put the following into your @file{.emacs} file, fairly +early on: + +@example +(defun my-load-cc-fonts () + (require "cc-fonts")) +(add-hook 'c-initialization-hook 'my-load-cc-fonts) +@end example +@end itemize + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node FAQ, Updating CC Mode, Limitations and Known Bugs, Top +@comment node-name, next, previous, up +@appendix Frequently Asked Questions +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +@itemize @bullet +@item +@emph{How can I change the indent level from 4 spaces to 2 spaces?} + +Set the variable @code{c-basic-offset}. @xref{Getting Started}. + +@item +@kindex RET +@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 +@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}: + +@example +(define-key c-mode-base-map "\C-m" 'c-context-line-break) +@end example + +@xref{Getting Started}. This is a very common question. If you want +this to be the default behavior, don't lobby us, lobby RMS! @t{:-)} + +@item +@emph{How do I stop my code jumping all over the place when I type?} + +Deactivate ``electric minor mode'' with @kbd{C-c C-l}. @xref{Getting +Started}. + +@item +@kindex C-x h +@kindex C-M-\ +@emph{How do I reindent the whole file?} + +Visit the file and hit @kbd{C-x h} to mark the whole buffer. Then hit +@kbd{C-M-\}. @xref{Indentation Commands}. + +@item +@kindex C-M-q +@kindex C-M-u +@emph{How do I reindent the current block?} + +First move to the brace which opens the block with @kbd{C-M-u}, then +reindent that expression with @kbd{C-M-q}. @xref{Indentation +Commands}. @item -Add-on fill packages may not work as well as @ccmode{}'s built-in -filling routines. I no longer recommend you use @code{filladapt} to -fill comments. +@emph{I put @code{(c-set-offset 'substatement-open 0)} in my +@file{.emacs} file but I get an error saying that @code{c-set-offset}'s +function definition is void. What's wrong?} + +This means that @ccmode{} hasn't yet been loaded into your Emacs +session by the time the @code{c-set-offset} call is reached, most +likely because @ccmode{} is being autoloaded. Instead of putting the +@code{c-set-offset} line in your top-level @file{.emacs} file, put it +in your @code{c-initialization-hook} (@pxref{CC Hooks}), or simply +modify @code{c-offsets-alist} directly: + +@example +(setq c-offsets-alist '((substatement-open . 0))) +@end example -@cindex c-indent-exp -@cindex indent-exp (c-) @item -@code{c-indent-exp} has not been fully optimized. It essentially -equivalent to hitting @kbd{TAB} (@code{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. +@cindex open paren in column zero +@emph{I have an open paren character at column zero inside a comment or +multiline string literal, and it causes the fontification and/or +indentation to go haywire. What gives?} + +It's due to the ad-hoc rule in (X)Emacs that such open parens always +start defuns (which translates to functions, classes, namespaces or any +other top-level block constructs in the @ccmode{} languages). +@ifset XEMACS +@xref{Defuns,,, xemacs, XEmacs User's Manual}, for details. +@end ifset +@ifclear XEMACS +@xref{Left Margin Paren,,, emacs, GNU Emacs Manual}, for details +(@xref{Defuns,,, emacs, GNU Emacs Manual}, in the Emacs 20 manual). +@end ifclear + +This heuristic is built into the core syntax analysis routines in +(X)Emacs, so it's not really a @ccmode{} issue. However, in Emacs +21.1 it became possible to turn it off@footnote{Using the variable +@code{open-paren-in-column-0-is-defun-start}.} and @ccmode{} does so +there since it's got its own system to keep track of blocks. @end itemize -@c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Mailing Lists and Submitting Bug Reports, Concept Index, Limitations and Known Bugs, Top -@comment node-name, next, previous,up -@chapter Mailing Lists and Submitting Bug Reports -@cindex Mailing Lists and Submitting Bug Reports -@c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Updating CC Mode, Mailing Lists and Bug Reports, FAQ, Top +@comment node-name, next, previous, up +@appendix Getting the Latest CC Mode Release +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +@ccmode{} has been standard with all versions of Emacs since 19.34 and +of XEmacs since 19.16. + +@cindex web site +Due to release schedule skew, it is likely that all of these Emacsen +have old versions of @ccmode{} and so should be upgraded. Access to the +@ccmode{} source code, as well as more detailed information on Emacsen +compatibility, etc. are all available on the web site: + +@quotation +@uref{http://cc-mode.sourceforge.net/} +@end quotation + + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Mailing Lists and Bug Reports, Command and Function Index, Updating CC Mode, Top +@comment node-name, next, previous, up +@appendix Mailing Lists and Submitting Bug Reports +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @kindex C-c C-b @findex c-submit-bug-report @findex submit-bug-report (c-) -@cindex beta testers mailing list +To report bugs, use the @kbd{C-c C-b} (bound to +@code{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 @emph{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 @samp{-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 triggers the bug and include it in your report. + +@cindex bug report mailing list +Bug reports should be sent to @email{bug-cc-mode@@gnu.org}. You can +also send other questions and suggestions (kudos? @t{;-)} to that +address. It's a mailing list which you can join or browse an archive +of; see the web site at @uref{http://cc-mode.sourceforge.net/} for +further details. + @cindex announcement mailing list -To report bugs, use the @kbd{C-c C-b} (@code{c-submit-bug-report}) -command. This provides vital information I 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 -@emph{before} your bug example, if you think it might affect my ability -to reproduce it. - -Bug reports are now sent to the following email addresses: -@code{cc-mode-help@@python.org} and -@code{bug-gnu-emacs@@gnu.org}; the latter is mirrored on the -Usenet newsgroup @code{gnu.emacs.bug}. You can send other questions and -suggestions (kudos? @code{;-)} to @code{cc-mode-help@@python.org}, or -@code{help-gnu-emacs@@gnu.org} which is mirrored on newsgroup -@code{gnu.emacs.help}. - -If you want to get announcements of new CC Mode releases, send the +If you want to get announcements of new @ccmode{} releases, send the word @emph{subscribe} in the body of a message to -@code{cc-mode-announce-request@@python.org}. Announcements will also be -posted to the Usenet newsgroup @code{gnu.emacs.sources}. Note that the -@code{cc-mode-victims@@python.org} mailing list was recently -decommissioned. - -@c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Concept Index, Command Index, Mailing Lists and Submitting Bug Reports, Top -@comment node-name, next, previous, up -@unnumbered Concept Index -@c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@printindex cp +@email{cc-mode-announce-request@@lists.sourceforge.net}. It's possible +to subscribe from the web site too. Announcements will also be posted +to the Usenet newsgroups @code{gnu.emacs.sources}, @code{comp.emacs}, +@code{comp.emacs.xemacs}, @code{comp.lang.c}, @code{comp.lang.c++}, +@code{comp.lang.objective-c}, @code{comp.lang.java.softwaretools}, +@code{comp.lang.idl}, and @code{comp.lang.awk}. +@c There is no newsgroup for Pike. :-( + +@c Removed the tentative node "Mode Initialization" from here, 2005/8/27. +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Command and Function Index, Variable Index, Mailing Lists and Bug Reports, Top +@comment node-name, next, previous, up +@unnumbered Command and Function Index +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +Since most @ccmode{} commands are prepended with the string +@samp{c-}, each appears under its @code{c-@var{thing}} name and its +@code{@var{thing} (c-)} name. +@iftex +@sp 2 +@end iftex +@printindex fn -@c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Command Index, Key Index, Concept Index, Top -@comment node-name, next, previous, up -@unnumbered Command Index -@c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@ifinfo +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Variable Index, Concept and Key Index, Command and Function Index, Top +@comment node-name, next, previous, up +@unnumbered Variable Index +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@end ifinfo -Since all @ccmode{} commands are prepended with the string -@samp{c-}, each appears under its @code{c-@var{}} name and its -@code{@var{} (c-)} name. +Since most @ccmode{} variables are prepended with the string +@samp{c-}, each appears under its @code{c-@var{thing}} name and its +@code{@var{thing} (c-)} name. @iftex @sp 2 @end iftex -@printindex fn - +@printindex vr -@c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Key Index, Variable Index, Command Index, Top -@comment node-name, next, previous, up -@unnumbered Key Index -@c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@printindex ky +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Concept and Key Index, , Variable Index, Top +@comment node-name, next, previous, up +@unnumbered Concept and Key Index +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@printindex cp -@c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Variable Index, , Key Index, Top -@comment node-name, next, previous, up -@unnumbered Variable Index -@c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@ifinfo +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@comment Epilogue. +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@end ifinfo -Since all @ccmode{} variables are prepended with the string -@samp{c-}, each appears under its @code{c-@var{}} name and its -@code{@var{} (c-)} name. @iftex -@sp 2 -@end iftex -@printindex vr @page @summarycontents @contents +@end iftex + @bye +@ignore + arch-tag: c4cab162-5e57-4366-bdce-4a9db2fc97f0 +@end ignore