X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/f214c025f74d9b4552272fbe4559b17a01e499f3..d5d04ab296e26d181f2f31370242b589c97abeb2:/man/cc-mode.texi diff --git a/man/cc-mode.texi b/man/cc-mode.texi index dbde6f9f56..e6619599d4 100644 --- a/man/cc-mode.texi +++ b/man/cc-mode.texi @@ -1,16 +1,130 @@ \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 +@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 !! @comment %**end of header (This is for running Texinfo on a region) @@ -18,61 +132,86 @@ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@comment +@comment @comment Texinfo manual for CC Mode @comment Generated from the original README file by Krishna Padmasola @comment -@comment -@comment Maintained by Martin Stjernholm -@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 Info directory entry for use by install-info +@comment Define an index for syntactic symbols. +@ifnottex @c In texi2dvi, the @defindex would create an empty cc-mode.ss + @c For Info, unlike tex, @syncodeindex needs a matching @defindex. +@defindex ss +@end ifnottex + +@comment Combine key, syntactic symbol and concept indices into one. +@syncodeindex ss cp +@syncodeindex ky cp + +@copying +This manual is for CC Mode in Emacs. + +Copyright @copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, +2003, 2004, 2005, 2006 Free Software Foundation, Inc. + +@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: (cc-mode). Emacs mode for editing C, C++, Objective-C, - Java, Pike, and IDL code. +* CC Mode: (ccmode). Emacs mode for editing C, C++, Objective-C, + Java, Pike, AWK, and CORBA IDL code. @end direntry @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@comment The following line inserts the copyright notice -@comment into the Info file. -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@ifinfo -Copyright @copyright{} 1995-2000 Free Software Foundation, Inc. -@end ifinfo - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@comment !!!The titlepage section does not appear in the Info file.!!! +@comment TeX title page @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @titlepage @sp 10 - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@comment The title is printed in a large font. -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@center @titlefont{CC Mode 5.27} +@center @titlefont{CC Mode 5.31} @sp 2 @center @subtitlefont{A GNU Emacs mode for editing C and C-like languages} @sp 2 -@center Current maintainer: -@center Martin Stjernholm - - -@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-2000 Free Software Foundation, Inc. -@end titlepage +@insertcopying +This manual was generated from $Revision: 1.36 $ of $RCSfile: cc-mode.texi,v $, 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. @@ -82,144 +221,170 @@ Copyright @copyright{} 1995-2000 Free Software Foundation, Inc. @node Top, Introduction, (dir), (dir) @comment node-name, next, previous, up -@macro ccmode -CC Mode -@end macro - @ifinfo @top @ccmode{} @ccmode{} is a GNU Emacs mode for editing files containing C, C++, -Objective-C, Java, CORBA IDL, and Pike code. It provides syntax-based -indentation and has several handy commands and some minor modes to make -the editing easier. Note that @ccmode{} does @emph{not} provide -font-locking; there are other Emacs packages for that. +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:: -* Text Filling and Line Breaking:: -* Commands:: -* Customizing Indentation:: -* Syntactic Symbols:: -* Indentation Functions:: -* Performance Issues:: -* Frequently Asked Questions:: -* Getting the Latest CC Mode Release:: -* Sample .emacs File:: -* Limitations and Known Bugs:: -* Mailing Lists and Submitting Bug Reports:: - - --- Indices --- - -* Concept Index:: -* Command Index:: -* Key Index:: -* Variable Index:: - +* Introduction:: +* 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:: +* FAQ:: +* Updating CC Mode:: +* Mailing Lists and Bug Reports:: +* Command and Function Index:: +* Variable Index:: +* Concept and Key Index:: + +@detailmenu --- The Detailed Node Listing --- -New Indentation Engine +Commands + +* Indentation Commands:: +* Comment Commands:: +* Movement Commands:: +* Filling and Breaking:: +* Minor Modes:: +* Electric Keys:: +* Auto-newlines:: +* Hungry WS Deletion:: +* Subword Movement:: +* Other Commands:: -* Syntactic Analysis:: -* Indentation Calculation:: +Font Locking -Minor Modes +* Font Locking Preliminaries:: +* Faces:: +* Doc Comments:: +* AWK Mode Font Locking:: -* Auto-newline Insertion:: -* Hungry-deletion of Whitespace:: +Configuration Basics -Auto-newline Insertion +* CC Hooks:: +* Style Variables:: +* Styles:: -* Hanging Braces:: -* Hanging Colons:: -* Hanging Semi-colons and Commas:: -* Other Electric Commands:: -* Clean-ups:: +Styles -Commands +* Built-in Styles:: +* Choosing a Style:: +* Adding Styles:: +* File Styles:: -* Indentation Commands:: -* Movement Commands:: -* Other Commands:: +Customizing Auto-newlines -Customizing Indentation +* Hanging Braces:: +* Hanging Colons:: +* Hanging Semicolons and Commas:: -* Interactive Customization:: -* Permanent Customization:: -* Hooks:: -* Styles:: -* Advanced Customizations:: +Hanging Braces -Styles +* Custom Braces:: -* Built-in Styles:: -* Adding Styles:: -* File Styles:: +Indentation Engine Basics -Advanced Customizations +* Syntactic Analysis:: +* Syntactic Symbols:: +* Indentation Calculation:: -* Custom Indentation Functions:: -* Custom Brace and Colon Hanging:: -* Customizing Semi-colons and Commas:: -* Other Special Indentations:: -@end menu +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, Getting Connected, Top, Top +@node Introduction, Overview, Top, Top @comment node-name, next, previous, up -@chapter Introduction +@chapter Introduction @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @cindex BOCM +@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 Pike code. This incarnation of -the mode is descendant from @file{c-mode.el} (also called "Boring Old C -Mode" or BOCM @t{:-)}, and @file{c++-mode.el} version 2, which Barry has -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. Late in 1997, Martin -joined the @ccmode{} Maintainers Team, and implemented the Pike support. -As of 2000 Martin has taken over as the sole maintainer. +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 automated -version 5.27. +@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, @dfn{ARM} -@footnote{@cite{The Annotated C++ Reference Manual}, by Ellis and -Stroustrup.} C++, Objective-C, Java, CORBA's Interface Definition -Language, and Pike@footnote{A C-like scripting language with its roots -in the LPC language used in some MUD engines. See -@uref{http://pike.idonex.se/}.} files. In this way, you can easily set -up consistent coding styles for use in editing all of these languages. -@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 +@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 @@ -227,1908 +392,2072 @@ How to customize the new indentation engine. @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 +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}, and @code{pike-mode} entry points are provided. This -package 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. +@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 Getting Connected, New Indentation Engine, Introduction, Top -@comment node-name, next, previous, up -@chapter Getting Connected -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Overview, Getting Started, Introduction, Top +@comment node-name, next, previous, up@cindex organization of the manual +@chapter Overview of the Manual +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -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. +@noindent +The manual starts with several introductory chapters (including this +one). -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 (@pxref{Getting the Latest CC Mode Release}). +@noindent +The next chunk of the manual describes the day to day @emph{use} of +@ccmode{} (as contrasted with how to customize it). -@cindex @file{cc-mode-18.el} file -@emph{Note that @ccmode{} no longer -works with Emacs 18!}, so if you haven't upgraded from Emacs 18 by now, -you are out of luck. +@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. -@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 +@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 -Using CC Mode version 5.XX +@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. -@end 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. -@noindent -where @samp{XX} is the minor release number. +@item +The next few chapters describe in detail how to customize the various +features of @ccmode{}. +@item +Finally, there is a sample @file{.emacs} fragment, which might help you +in creating your own customization. +@end itemize -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node New Indentation Engine, Minor Modes, Getting Connected, Top -@comment node-name, next, previous, up -@chapter New Indentation Engine -@cindex indentation engine -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@noindent +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 +@node Getting Started, Commands, Overview, Top @comment node-name, next, previous, up -@section Syntactic Analysis -@cindex syntactic analysis +@chapter Getting Started @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@cindex relative buffer position -@cindex syntactic symbol -@cindex syntactic component -@cindex syntactic component list -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{Unless otherwise noted, the term ``C code'' to refers to all -the C-like languages.}, 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 style 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 C++ 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 reading 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 availables 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: @} +@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.}: -@end group -@end example - -@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 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 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 +@node Commands, Font Locking, Getting Started, Top @comment node-name, next, previous, up -@section Indentation Calculation -@cindex indentation calculation +@chapter Commands @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -Indentation for a line is calculated using the syntactic -component list derived in step 1 above (@pxref{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} -style 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 +@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 - 1: void swap( int& a, int& b ) - 2: @{ - 3: int tmp = a; - 4: a = b; - 5: b = tmp; - 6: @} +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Indentation Commands, Comment Commands, Commands, Commands +@comment node-name, next, previous,up +@section Indentation Commands +@cindex indentation +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@end group -@end example +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. -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 +@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. -((defun-block-intro . 29)) +These commands indent code: -@end example +@table @asis +@item @kbd{@key{TAB}} (@code{c-indent-command}) +@kindex TAB +@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. -@noindent -@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 running total (initialized to zero), -yielding a running total indentation of 4 spaces. +@code{c-indent-command} does different things, depending on the +settting of @code{c-syntactic-indentation} (@pxref{Indentation Engine +Basics}): -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. +@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. -Here's another example: -@example -@group +@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 - 1: int add( int val, int incr, int doit ) - 2: @{ - 3: if( doit ) - 4: @{ - 5: return( val + incr ); - 6: @} - 7: return( val ); - 8: @} +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{}}. -@end group -@end example +@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 -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 +@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 -((substatement-open . 46)) +@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 -@end example +@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. -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-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. -Simple, huh? +@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. + +@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-) -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, Text Filling and Line Breaking, New Indentation Engine, Top +@node Comment Commands, Movement Commands, Indentation Commands, Commands @comment node-name, next, previous, up -@chapter Minor Modes +@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. - -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{The @samp{C} -would be replaced with @samp{C++}, @samp{ObjC}, @samp{Java}, @samp{IDL}, -or @samp{Pike} for the respective languages.}. When hungry delete mode -is enabled you would see @samp{C/h} and when both modes are enabled, -you'd see @samp{C/ah}. - -@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 - -(add-hook 'c-mode-common-hook - '(lambda () (c-toggle-auto-hungry-state 1))) - -@end example +@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 +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Movement Commands, Filling and Breaking, Comment Commands, Commands +@comment node-name, next, previous, up +@section Movement Commands +@cindex movement +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@cindex electric characters +@ccmode{} contains some useful commands for moving around in C code. -@menu -* Auto-newline Insertion:: -* Hungry-deletion of Whitespace:: -@end menu +@table @asis +@item @kbd{M-x c-beginning-of-defun} +@itemx @kbd{M-x c-end-of-defun} +@findex c-beginning-of-defun +@findex c-end-of-defun +@findex beginning-of-defun (c-) +@findex end-of-defun (c-) +@findex beginning-of-defun +@findex end-of-defun +Move to the start or end of the current top-level definition. This is +the outermost brace pair which encloses point, together with the +function header or similar preamble which precedes the opening brace. +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. + +Depending on the coding style you're using, you might prefer these two +commands to the standard Emacs ones. If so, consider binding them to +@kbd{C-M-a} and @kbd{C-M-e}. @xref{Sample .emacs File}. This +customization won't affect the special bindings for these key +sequences in force in AWK Mode. For backwards compatibility reasons, +the default bindings for @kbd{C-M-a} and @kbd{C-M-e} remain in effect. + +@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 back to the beginning or forward to the end of the current AWK +defun. These functions are bound to @kbd{C-M-a} and @kbd{C-M-e} by +default in AWK Mode. They 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. -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Auto-newline Insertion, Hungry-deletion of Whitespace, , Minor Modes -@comment node-name, next, previous, up -@section Auto-newline Insertion -@cindex auto-newline insertion -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +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. -@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: +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. -@itemize @bullet -@item -Auto-newline minor mode is enabled, as evidenced by a @samp{C/a} or -@samp{C/ah} indicator on the modeline. +@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. -@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.}. +@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. -@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). +This key sequence is not bound in AWK Mode, which doesn't have +preprocessor statements. -@end itemize +@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. -@menu -* Hanging Braces:: -* Hanging Colons:: -* Hanging Semi-colons and Commas:: -* Other Electric Commands:: -* Clean-ups:: -@end menu +@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. -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Hanging Braces, Hanging Colons, , Auto-newline Insertion -@comment node-name, next, previous, up -@subsection Hanging Braces -@cindex hanging braces -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@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. -@findex c-electric-brace -@findex electric-brace (c-) -@vindex c-hanging-braces-alist -@vindex hanging-braces-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-entry-open 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 syntactic symbol -@cindex namespace-close syntactic symbol -@cindex inexpr-class-open symbol -@cindex inexpr-class-close symbol - -The default in auto-newline mode is to insert newlines both before and -after a brace, but that can be controlled by the -@code{c-hanging-braces-alist} style 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-entry-open}, @code{block-open}, -@code{block-close}, @code{substatement-open}, -@code{statement-case-open}, @code{extern-lang-open}, -@code{extern-lang-close}, @code{namespace-open}, @code{namespace-close}, -@code{inexpr-class-open}, and @code{inexpr-class-close}@footnote{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.}. @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. +@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. -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 produces a combination of -@code{inexpr-class}, and @code{class-open} or @code{class-close} in -normal indentation analysis.}. +These key sequences are not bound in AWK Mode, which doesn't have +preprocessor statements. -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}. +@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}. -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 +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. -// here, open braces always `hang' -void spam( int i ) @{ - if( i == 7 ) @{ - dosomething(i); - @} -@} +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 +@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 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@end group -@end example +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. -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. +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. -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. +@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})}. -For example, the default value of @code{c-hanging-braces-alist} is: -@example -@group +@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. - ((brace-list-open) - (brace-entry-open) - (substatement-open after) - (block-close . c-snug-do-while) - (extern-lang-open after) - (inexpr-class-open after) - (inexpr-class-close before)) +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. -@end group -@end example +This command is the replacement for @code{fill-paragraph} in @ccmode{} +buffers. -@noindent which says that @code{brace-list-open} and -@code{brace-entry-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}, @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. +@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}. -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 them can introduce performance problems. -@xref{Performance Issues}, for more information. +@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. + +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 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Hanging Colons, Hanging Semi-colons and Commas, Hanging Braces, Auto-newline Insertion +@node Minor Modes, Electric Keys, Filling and Breaking, Commands @comment node-name, next, previous, up -@subsection Hanging Colons -@cindex hanging colons +@section Minor Modes +@cindex Minor Modes @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@vindex hanging-colons-alist (c-) -@vindex c-hanging-colons-alist -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}. 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. +@ccmode{} contains several minor-mode-like features that you might +find useful while writing new code or editing old code: -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. +@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}. -@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 -@cindex hanging commas -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +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. + +@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. + +@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 -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. +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 Other Electric Commands, Clean-ups, Hanging Semi-colons and Commas, Auto-newline Insertion +@node Electric Keys, Auto-newlines, Minor Modes, Commands @comment node-name, next, previous, up -@subsection Other Electric Commands +@section Electric Keys and Keywords +@cindex electric characters @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +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}). + +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). + +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-) -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-) -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 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-paren -@findex electric-paren (c-) +@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 ) -The normal parenthesis characters @samp{(} and @samp{)} also reindent -the current line if they are used in normal code. This is useful for -getting the closing parenthesis of an argument list aligned +@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}. -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Clean-ups, , Other Electric Commands, Auto-newline Insertion -@comment node-name, next, previous, up -@subsection Clean-ups -@cindex clean-ups -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@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}. + +@end table -@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. +@deffn Command c-electric-continued-statement +@findex electric-continued-statement (c-) -@vindex c-cleanup-list -@vindex cleanup-list (c-) -@cindex literal -You can 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. Note that clean-ups are only -performed when the construct does not occur within a literal -(@pxref{Auto-newline Insertion}), and when there is nothing but -whitespace appearing between the individual components of the construct. +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). -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 @{ +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}. -@end group -@end example +@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 -@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 -void spam(int i) -@{ - if( i==7 ) - @{ - dosomething(); - @} - else if( i==3 ) - @{ +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Auto-newlines, Hungry WS Deletion, Electric Keys, Commands +@comment node-name, next, previous, up +@section Auto-newline Insertion +@cindex auto-newline +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@end group -@end example -@noindent -appears like this after the open parenthesis is typed: -@example -@group +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. -void spam(int i) -@{ - if( i==7 ) @{ - dosomething(); - @} else if( i==3 ) - @{ - -@end group -@end example -@noindent -and like this after the open brace is typed: -@example -@group - -void spam(int i) -@{ - if( i==7 ) @{ - dosomething(); - @} else if( i==3 ) @{ - -@end group -@end example +Auto-newline only triggers when the following conditions hold: +@itemize @bullet @item -@code{brace-catch-brace} --- analogous to @code{brace-elseif-brace}, but -cleans up @samp{@} catch (...) @{} in C++ and Java mode. +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{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 +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{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 is not on its own line already. (This applies only to +insertion of a newline @emph{before} the character.) @item -@code{list-close-comma} --- cleans up commas following braces in array -and aggregate initializers. Clean up occurs when the comma is typed. +@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 -@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. - +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. + +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. + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Hungry-deletion of Whitespace, , Auto-newline Insertion, Minor Modes +@node Hungry WS Deletion, Subword Movement, Auto-newlines, Commands @comment node-name, next, previous, up -@section Hungry-deletion of Whitespace -@cindex hungry-deletion of whitespace +@section Hungry Deletion of Whitespace +@cindex hungry-deletion @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! +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}. -@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. +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 @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 backward-delete-char-untabify - -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 (@pxref{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. - -@vindex delete-key-deletes-forward @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 -The default behavior of the @key{Delete} key depends on the flavor of -Emacs you are using. By default in XEmacs 20.3 and beyond, the -@key{Delete} key is bound to @code{c-electric-delete}. You control the -direction that the @key{Delete} key deletes by setting the variable -@code{delete-key-deletes-forward}, a standard XEmacs variable. When -this variable is non-@code{nil} and hungry-delete mode is enabled, -@code{c-electric-delete} will consume all whitespace @emph{following} -point. When @code{delete-key-deletes-forward} is @code{nil}, it deletes -all whitespace @emph{preceding} point@footnote{i.e. it literally calls -@code{c-electric-backspace}.} When deleting a single character, or if -@key{Delete} is hit in a literal, or hungry-delete mode is disabled, the -function contained in @code{c-delete-function} is called with one -argument: the number of characters to delete. This variable is set to -@code{delete-char} by default. - -In Emacs 19 or Emacs 20, both the @key{Delete} and @key{Backspace} keys -are bound to @code{c-electric-backspace}, however you can change this by -explicitly binding @code{[delete]}@footnote{E.g. to -@code{c-electric-delete} in your @file{.emacs} file. Note however, that -Emacs 20 does not have a standard variable such as -@code{delete-key-deletes-forward}.}. - -XEmacsen older than 20.3 behave similar to Emacs 19 and Emacs 20. - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Text Filling and Line Breaking, Commands, Minor Modes, Top -@comment node-name, next, previous, up -@chapter Text Filling and Line Breaking -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -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 as seamlessly as possible, 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{} should keep the indentation, fix the comment line -decorations, and so on, for you. It does that 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 style of line decoration that -starts every line in a comment. The style variable -@code{c-comment-prefix-regexp} contains the regexp used to recognize -this @dfn{comment line prefix}. The default is @samp{//+\\|\\**}, which -matches C++ style line comments like -@example +@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. -// blah blah +@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 -@end example +@kindex +@kindex -@noindent -with two or more slashes in front of them, and C style block comments -like -@example -@group +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. -/* - * blah blah - */ +@findex c-electric-delete +@findex electric-delete (c-) +@findex c-hungry-delete +@findex hungry-delete (c-) +@vindex delete-key-deletes-forward +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. -@end group -@end example -@noindent -with zero or more stars at the beginning of every line. If you change -that variable, please make sure it still matches the comment starter -(i.e. @code{//}) of line comments @emph{and} the line prefix inside -block comments. Also note that since @ccmode{} uses the value of -@code{c-comment-prefix-regexp} to set up several other variables at mode -initialization, you need to reinitialize the program mode if you change -it inside a @ccmode{} buffer. +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Subword Movement, Other Commands, Hungry WS Deletion, Commands +@comment node-name, next, previous, up +@section Subword Movement and Editing +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@findex auto-fill-mode -@cindex auto fill mode -@cindex paragraph fill -Line breaks are by default handled (almost) the same regardless whether -they are made by auto fill mode (@pxref{Auto Fill,,, emacs, The Emacs -Editor}), 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 (may be changed with the -@code{string} syntactic symbol). In comments, @ccmode{} uses -@code{c-comment-prefix-regexp} to adapt the line prefix from the other -lines in the comment. +@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}} +@headitem Nomenclature + @tab Subwords +@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 +@headitem Key @tab Word oriented command @tab Subword oriented command +@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}: -@vindex adaptive-fill-mode -@cindex adaptive fill mode -@ccmode{} uses adaptive fill mode (@pxref{Adaptive Fill,,, emacs, The -Emacs Editor}) 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 kept intact: @example -@group +(add-hook 'c-mode-common-hook + (lambda () (c-subword-mode 1))) +@end example -/* 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. - */ +As a bonus, you can also use @code{c-subword-mode} in non-@ccmode{} +buffers by typing @kbd{M-x c-subword-mode}. -@end group -@end example +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Other Commands, , Subword Movement, Commands +@comment node-name, next, previous, up +@section Other Commands +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@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 site}.}, -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 -@group +Here are the various other commands that didn't fit anywhere else: -(defun my-c-mode-common-hook () - (c-setup-filladapt) - (filladapt-mode 1)) -(add-hook 'c-mode-common-hook 'my-c-mode-common-hook) +@table @asis +@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. -@end group -@end example +@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. -@vindex 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 clue about how the prefix should look, namely -when a block comment is broken for the first time. The string in the -style variable @code{c-block-comment-prefix}@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 in that case. It defaults to @samp{* }, which -makes a comment -@example +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. -/* Got O(n^2) here, which is a Bad Thing. */ +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. -@end example +To customize the precise workings of this command, @ref{Custom Macros}. +@end table @noindent -break into -@example -@group +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. -/* Got O(n^2) here, - * which is a Bad Thing. */ +@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 -@end group -@end example +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Font Locking, Config Basics, Commands, Top +@comment node-name, next, previous, up +@chapter Font Locking +@cindex font locking +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -Note that it won't work to justify the indentation by putting leading -spaces in the @code{c-block-comment-prefix} string, since @ccmode{} -still uses the normal indentation engine to indent the line. Thus, the -right way to fix the indentation is by setting the @code{c} syntactic -symbol. It defaults to @code{c-lineup-C-comments}, which handles the -indentation of most common comment styles, see @ref{Indentation -Functions}. +@cindex Font Lock mode -@vindex 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 behavior can -be controlled with the @code{c-ignore-auto-fill} variable. It takes a -list of symbols for the different contexts where auto-filling never -should occur: +@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. -@itemize @bullet -@item @code{string} --- Inside a string or character literal. -@item @code{c} --- Inside a C style block comment. -@item @code{c++} --- Inside a C++ style line comment. -@item @code{cpp} --- Inside a preprocessor directive. -@item @code{code} --- Anywhere else, i.e. in normal code. -@end itemize +@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. -By default, @code{c-ignore-auto-fill} is set to @code{'(string cpp -code)}, which means that auto-filling only occurs in comments when -auto-fill mode is activated. 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. +@menu +* Font Locking Preliminaries:: +* Faces:: +* Doc Comments:: +* AWK Mode Font Locking:: +@end menu -The commands that does the actual work follows. -@table @asis +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Font Locking Preliminaries, Faces, Font Locking, Font Locking +@comment node-name, next, previous, up +@section Font Locking Preliminaries +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@kindex M-q -@findex c-fill-paragraph -@findex fill-paragraph (c-) -@cindex Javadoc markup -@item @kbd{M-q} (@code{c-fill-paragraph}) -This is the replacement for @code{fill-paragraph} in @ccmode{} -buffers. It's used to fill multiline string literals and both block and -line style comments. In Java buffers, the Javadoc markup words are -recognized as paragraph starters. - -The function keeps the comment starters and enders of block comments as -they were before the filling. This means that a comment ender on the -same line as the paragraph being filled will be filled with the -paragraph, and one on a line by itself will stay as it is. The comment -starter is handled similarly@footnote{This means that the variables -@code{c-hanging-comment-starter-p} and @code{c-hanging-comment-ender-p}, -which controlled this behavior in earlier versions of @ccmode{}, are now -obsolete.}. +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: -@kindex M-j -@findex c-indent-new-comment-line -@findex indent-new-comment-line (c-) -@item @kbd{M-j} (@code{c-indent-new-comment-line}) -This is the replacement for @code{indent-new-comment-line}. It breaks -the line at point and indents the new line like the current one. +@enumerate +@comment 1 +@item +Minimal font locking: Fontify only comments, strings and preprocessor +directives (in the languages that use cpp). -@vindex comment-multi-line -If inside a comment and @code{comment-multi-line} 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. +@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}). -@findex c-context-line-break -@findex context-line-break (c-) -@item @kbd{M-x c-context-line-break} -This is a function that works like @code{indent-new-comment-line} in -comments and @code{newline-and-indent} elsewhere, thus combining those -two in a way that uses each one in the context it's best suited for. -I.e. in comments the comment line prefix and indentation is kept for the -new line, and in normal code it's indented according to context by the -indentation engine. +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. -It's 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 might consider switching to this function. +@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 -@end table +@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 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Commands, Customizing Indentation, Text Filling and Line Breaking, Top +@node Faces, Doc Comments, Font Locking Preliminaries, Font Locking @comment node-name, next, previous, up -@chapter Commands +@section Faces +@cindex faces @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@menu -* Indentation Commands:: -* Movement Commands:: -* Other Commands:: -@end menu +@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}. -See also @ref{Text Filling and Line Breaking}, for commands concerning -that bit. +@itemize @bullet +@item +@vindex font-lock-comment-face +Normal comments are fontified in @code{font-lock-comment-face}. +@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. -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Indentation Commands, Movement Commands, , Commands -@comment node-name, next, previous,up -@section Indentation Commands -@cindex indentation commands -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@item +@vindex font-lock-string-face +String and character literals are fontified in +@code{font-lock-string-face}. -The following list of commands re-indent C constructs. Note that when -you change your coding style, either interactively or through some other -means, your file does @emph{not} automatically get re-indented. You -will need to execute one of the following commands to see the effects of -your changes. +@item +@vindex font-lock-keyword-face +Keywords are fontified with @code{font-lock-keyword-face}. -@cindex GNU indent program -Also, variables like @code{c-hanging-*} and @code{c-cleanup-list} -only affect how on-the-fly code is formatted. Changing the -``hanginess'' of a brace and then re-indenting, 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 re-arrange brace location, -among other things. +@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. -Re-indenting large sections of code can take a long time. When -@ccmode{} reindents a region of code, it is essentially equivalent to -hitting @kbd{TAB} on every line of the region. Especially vulnerable is -code generator output@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. Re-indenting such code will be slow.}. +@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. -These commands are useful when indenting code: +@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. -@table @asis +@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. -@kindex TAB -@findex c-indent-command -@findex indent-command (c-) -@item @kbd{TAB} (@code{c-indent-command}) -Indents the current line. The actual behavior is controlled by several -variables, described below. See @code{c-tab-always-indent}, -@code{c-insert-tab-function}, and @code{indent-tabs-mode}. With a -numeric argument, this command rigidly indents the region, preserving -the relative indentation among the lines. - -@kindex M-C-q -@findex c-indent-exp -@findex indent-exp (c-) -@item @kbd{M-C-q} (@code{c-indent-exp}) -Indent 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. - -@kindex C-c C-q -@findex c-indent-defun -@findex indent-defun (c-) -@item @kbd{C-c C-q} (@code{c-indent-defun}) -Indents the entire top-level function or class definition encompassing -point. It leaves point unchanged. This function can't be used to -re-indent a nested brace construct, such as a nested class or function, -or a Java method. The top-level construct being re-indented must be -complete, i.e. it must have both a beginning brace and an ending brace. - -@kindex M-C-\ -@findex indent-region -@item @kbd{M-C-\} (@code{indent-region}) -Indents an arbitrary region of code. This is a standard Emacs command, -tailored for C code in a @ccmode{} buffer. Note that of course, point -and mark must delineate the region you want to indent. - -@kindex M-C-h -@findex c-mark-function -@findex mark-function (c-) -@item @kbd{M-C-h} (@code{c-mark-function}) -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 +@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. -These variables are also useful when indenting code: +@item +Name qualifiers and identifiers for scope constructs are fontified like +labels. -@table @code +@item +Special markup inside documentation comments are also fontified like +labels. -@vindex c-tab-always-indent -@vindex tab-always-indent (c-) -@kindex TAB -@cindex literal -@item c-tab-always-indent -This variable controls how @kbd{TAB} @code{c-indent-command} operates. -When this variable is @code{t}, @kbd{TAB} always just indents the -current line. When it is @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 some whitespace is inserted. If this -variable is the symbol @code{other}, then some whitespace is inserted -only within strings and comments (literals), an inside preprocessor -directives, but the line is always reindented. - -@vindex c-insert-tab-function -@vindex insert-tab-function (c-) -@findex tab-to-tab-stop -@item c-insert-tab-function -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 just 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. - -@vindex indent-tabs-mode -@item indent-tabs-mode -This is a standard Emacs variable that controls how line indentation is -composed. When this variable is non-@code{nil}, then tabs can be used -in a line's indentation, otherwise only spaces can be used. - -@vindex c-progress-interval -@vindex progress-interval (c-) -@item c-progress-interval -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 the -interval in seconds that progress messages are displayed. +@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. -@end table +@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 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Movement Commands, Other Commands, Indentation Commands, Commands +@node Doc Comments, AWK Mode Font Locking, Faces, Font Locking @comment node-name, next, previous, up -@section Movement Commands -@cindex movement commands +@section Documentation Comments +@cindex documentation comments @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@ccmode{} contains some useful command for moving around in C -code. - -@table @asis - -@findex c-beginning-of-defun -@findex beginning-of-defun (c-) -@findex beginning-of-defun -@item @kbd{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. - -@findex c-end-of-defun -@findex end-of-defun (c-) -@findex end-of-defun -@item @kbd{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. - -@kindex C-c C-u -@findex c-up-conditional -@findex up-conditional (c-) -@item @kbd{C-c C-u} (@code{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. - -@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. - -@findex c-up-conditional-with-else -@findex up-conditional-with-else (c-) -@item @kbd{M-x c-up-conditional-with-else} -A variety of @code{c-up-conditional} that also stops at @samp{#else} -lines. Normally those lines are ignored. +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: -@findex c-down-conditional -@findex down-conditional (c-) -@item @kbd{M-x c-down-conditional} -Move point forward into the next nested preprocessor conditional, -leaving the mark behind. A prefix argument acts as a repeat count. -With a negative argument, move point backward into the previous -nested preprocessor conditional. +@table @code +@item javadoc +@cindex Javadoc markup +Javadoc comments, the standard tool in Java. -@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 autodoc +@cindex Pike autodoc markup +For Pike autodoc markup, the standard in Pike. -@findex c-down-conditional-with-else -@findex down-conditional-with-else (c-) -@item @kbd{M-x c-down-conditional-with-else} -A variety of @code{c-down-conditional} that also stops at @samp{#else} -lines. Normally those lines are ignored. +@item gtkdoc +@cindex GtkDoc markup +For GtkDoc markup, widely used in the Gnome community. +@end table -@kindex C-c C-p -@findex c-backward-conditional -@findex backward-conditional (c-) -@item @kbd{C-c C-p} (@code{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. +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}). -@kindex C-c C-n -@findex c-forward-conditional -@findex forward-conditional (c-) -@item @kbd{C-c C-n} (@code{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. +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}. -@kindex M-a -@findex c-beginning-of-statement -@findex beginning-of-statement (c-) -@item @kbd{M-a} (@code{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 you add support for another doc comment style, please consider +contributing it - send a note to @email{bug-cc-mode@@gnu.org}. -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 which is -the farthest back to search, and a flag to enable moving by sentence -inside comments. +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node AWK Mode Font Locking, , Doc Comments, Font Locking +@comment node-name, next, previous, up +@section AWK Mode Font Locking +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@kindex M-e -@findex c-end-of-statement -@findex end-of-statement (c-) -@item @kbd{M-e} (@code{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. +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}. -If point is within a comment, or next to a comment, this command moves -by sentences instead of statements. +The following faces are, however, used in a non-standard fashion in +AWK mode: -When called from a program, this function takes three optional -arguments: the numeric prefix argument, a buffer position limit which is -the farthest back to search, and a flag to enable moving by sentence -inside comments. +@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}). + +@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{/}). + +@item @code{font-lock-warning-face} (Emacs)/@code{c-invalid-face} (XEmacs) +This face highlights the following syntactically invalid AWK +constructs: -@findex c-forward-into-nomenclature -@findex forward-into-nomenclature (c-) -@item @kbd{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}. +@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. -This command moves point forward to next capitalized word. With prefix -argument @var{n}, move @var{n} times. +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. -@findex c-backward-into-nomenclature -@findex backward-into-nomenclature (c-) -@item @kbd{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 +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 Config Basics, Custom Filling and Breaking, Font Locking, Top +@comment node-name, next, previous, up +@chapter Configuration Basics @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Other Commands, , Movement Commands, Commands -@comment node-name, next, previous, up -@section Other Commands -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@ccmode{} contains a few other useful commands: +@cindex Emacs Initiliazation 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 - -@kindex C-c : -@findex c-scope-operator -@findex scope-operator (c-) -@item @kbd{C-c :} (@code{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. - -@kindex C-c C-\ -@findex c-backslash-region -@findex backslash-region (c-) -@item @kbd{C-c C-\} (@code{c-backslash-region}) -This function is handy when editing macros split over several lines by -ending each line with a backslash. It inserts and aligns, or deletes -these end-of-line backslashes in the current region. - -@vindex c-backslash-column -@vindex backslash-column (c-) -With no prefix argument, it inserts any missing backslashes and aligns -them to the column specified by the @code{c-backslash-column} style -variable. With a prefix argument, it deletes any backslashes. - -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. - +@item Style +@itemx Top-level command or ``customization interface'' +@itemx Hook +@itemx File Style @end table +@end itemize +Here is a summary of the different ways of writing your configuration +settings: -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Customizing Indentation, Syntactic Symbols, Commands, Top -@comment node-name, next, previous, up -@chapter Customizing Indentation -@cindex customizing indentation -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@vindex c-offsets-alist -@vindex offsets-alist (c-) -The style variable @code{c-offsets-alist} contains the mappings between -syntactic symbols and the offsets to apply for those symbols. It's set -at mode initialization from a @emph{style} you may specify. Styles are -groupings of syntactic symbol offsets and other style variable values. -Most likely, you'll find that one of the pre-defined styles will suit -your needs. @xref{Styles}, for an explanation of how to set up named -styles. - -Only syntactic symbols not already bound on @code{c-offsets-alist} will -be set from styles. This means that any association you set on it, be -it before or after mode initialization, will not be changed. The -@code{c-offsets-alist} variable may therefore be used from e.g. the -Customization interface@footnote{Available in Emacs 20 and later, and -XEmacs 19.15 and later.} to easily change indentation offsets without -having to bother about styles. Initially @code{c-offsets-alist} is -empty, so that all syntactic symbols are set by the style system. - -@kindex C-c C-o -@findex c-set-offset -@findex set-offset (c-) -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@footnote{Obviously, you use the keybinding interactively, and the -function call programmatically!}. +@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: -@vindex c-basic-offset -@vindex basic-offset (c-) -The offset associated with any particular syntactic symbol 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 latter describe offset in multiples of the -value of the style 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 -maintaining the same basic shape of your code. Here are the values that -the special symbols correspond to: +@example +(setq c-basic-offset 4) +@end example -@table @code +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: -@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 +@example +@group +(defun my-c-mode-hook () + (setq c-basic-offset 3)) +(add-hook 'c-mode-hook 'my-c-mode-hook) -@end table +(defun my-java-mode-hook () + (setq c-basic-offset 6)) +(add-hook 'java-mode-hook 'my-java-mode-hook) +@end group +@end example -@cindex indentation functions +See @ref{CC Hooks} for more details on the use of @ccmode{} hooks. -When a function is used as offset, it's called an @dfn{indentation -function}. Such functions are useful when more context than just the -syntactic symbol is needed to get the desired indentation. -@xref{Indentation Functions}, and @ref{Custom Indentation Functions}, -for details about them. +@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: -@vindex c-strict-syntax-p -@vindex strict-syntax-p (c-) -The offset can also be a list, in which case it is evaluated recursively -using the semantics described above. The first element of the list that -returns a non-@code{nil} value succeeds and the evaluation stops. If -none of the list elements return a non-@code{nil} value, then an 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 signalled in that case. It's now considered obsolete since -it doesn't work well with some of the alignment functions that now -returns @code{nil} instead of zero to be more usable in lists. You -should therefore leave @code{c-strict-syntax-p} set to @code{nil}.}. - -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@footnote{You can try this interactively in -a C buffer by typing the text that appears in italics.}: @example +(setq c-default-style '((java-mode . "java") + (awk-mode . "awk") + (other . "free-group-style"))) +@end example -@emph{M-x set-variable RET} -Set variable: @emph{c-basic-offset RET} -Set c-basic-offset to value: @emph{4 RET} +See @ref{Styles} for fuller details on using @ccmode{} styles and how +to create them. -@end example +@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}: -@noindent -This would change @example @group - -int add( int val, int incr, int doit ) -@{ - if( doit ) - @{ - return( val + incr ); - @} - return( val ); -@} - +(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 -@noindent -to -@example -@group -int add( int val, int incr, int doit ) -@{ - if( doit ) - @{ - return( val + incr ); - @} - return( val ); -@} +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 - -To change indentation styles more radically, you will want to change the -offsets associated with other syntactic symbols. 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. +@end table @menu -* Interactive Customization:: -* Permanent Customization:: -* Hooks:: -* Styles:: -* Advanced Customizations:: +* CC Hooks:: +* Style Variables:: +* Styles:: @end menu - @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Interactive Customization, Permanent Customization, , Customizing Indentation +@node CC Hooks, Style Variables, Config Basics, Config Basics @comment node-name, next, previous, up -@section Interactive Customization -@cindex interactive customization +@section Hooks +@cindex mode hooks @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@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-) +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 -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 +@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. -1: int add( int val, int incr, int doit ) -2: @{ -3: if( doit ) -4: @{ -5: return( val + incr ); -6: @} -7: return( val ); -8: @} +Here's a simplified example of what you can add to your @file{.emacs} +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. -@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 +(defun my-c-mode-common-hook () + ;; my customizations for all of c-mode and related modes + (no-case-fold-search) + ) +(add-hook 'c-mode-common-hook 'my-c-mode-common-hook) @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 +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Style Variables, Styles, CC Hooks, Config Basics +@comment node-name, next, previous, up +@section Style Variables +@cindex styles +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -((substatement-open . 44)) +@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}. -@end example +@dfn{Style variables} are handled specially in several ways: -@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! +@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. -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}. +@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}). -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 +@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}. -1: int add( int val, int incr, int doit ) -2: @{ -3: if( doit ) -4: @{ -5: return( val + incr ); -6: @} -7: return( val ); -8: @} +@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. -@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 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. - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Permanent Customization, Hooks, Interactive Customization, Customizing Indentation -@comment node-name, next, previous, up -@section Permanent Customization -@cindex permanent customization -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -To make your changes permanent, you need to add some lisp code to your -@file{.emacs} file. @ccmode{} supports many different ways to be -configured, from the straightforward way by setting variables globally -in @file{.emacs} or in the Customization interface, to the complex and -precisely controlled way by using styles and hook functions. - -The simplest way of customizing @ccmode{} permanently is to set the -variables in your @file{.emacs} with @code{setq} and similar commands. -So to make the setting of @code{substatement-open} permanent, add this -to the @file{.emacs} file: -@example -@group - -(require 'cc-mode) -(c-set-offset 'substatement-open 0) - -@end group -@end example - -The @code{require} line is only needed once in the beginning to make -sure @ccmode{} is loaded so that the @code{c-set-offset} function is -defined. - -You can also use the more user friendly Customization interface, but -this manual does not cover how that works. - -Variables set like this at the top level in @file{.emacs} take effect in -all @ccmode{} buffers, regardless of language. The indentation style -related variables, e.g. @code{c-basic-offset}, that you don't set this -way get their value from the style system (@pxref{Styles}), and they -therefore depend on the setting of @code{c-default-style}. Note that if -you use Customize, this means that the greyed-out default values -presented there might not be the ones you actually get, since the actual -values depend on the style, which may very well be different for -different languages. - -If you want to make more advanced configurations, e.g. language-specific -customization, global variable settings isn't enough. For that you can -use the language hooks, see @ref{Hooks}, and/or the style system, see -@ref{Styles}. - -@vindex c-style-variables-are-local-p -@vindex style-variables-are-local-p (c-) -By default, all style variables are global, so that every buffer will -share the same style settings. This is fine if you primarily edit one -style of code, but if you edit several languages and want to use -different styles for them, you need finer control by making the style -variables buffer local. The recommended way to do this is to set the -variable @code{c-style-variables-are-local-p} to @code{t}. The -variables will be made buffer local when @ccmode{} is activated in a -buffer for the first time in the Emacs session. Note that once the -style variables are made buffer local, they cannot be made global again, -without restarting Emacs. - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Hooks, Styles, Permanent Customization, Customizing Indentation -@comment node-name, next, previous, up -@section Hooks -@cindex hooks -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@vindex c-mode-common-hook -@vindex mode-common-hook (c-) -@vindex c-mode-hook -@vindex c++-mode-hook -@vindex objc-mode-hook -@vindex java-mode-hook -@vindex idl-mode-hook -@vindex pike-mode-hook -@vindex c-initialization-hook -@vindex initialization-hook (c-) -@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 CORBA IDL buffers only. -@item -@code{pike-mode-hook} --- For Pike 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. - +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 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{@code{java-mode} and the hook variables interact in a -slightly different way than the other modes. @code{java-mode} normally -sets the style 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. This is arguably bogus, but it's kept for -historical reasons. @xref{Built-in Styles}, the documentation of -@code{c-default-style}, for details.} - -Here's a simplified example of what you can add to your @file{.emacs} -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 -@group - -(defun my-c-mode-common-hook () - ;; my customizations for all of c-mode and related modes - (no-case-fold-search) - ) -(add-hook 'c-mode-common-hook 'my-c-mode-common-hook) - -@end group -@end example - +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, Advanced Customizations, Hooks, Customizing Indentation +@node Styles, , Style Variables, Config Basics @comment node-name, next, previous, up -@section Styles +@section Styles @cindex styles @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @@ -2143,462 +2472,777 @@ 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. -@cindex style variables -The variables that the style system affect are called @dfn{style -variables}. They are handled specially in several ways: - -@itemize @bullet -@item -Style variables are by default global variables, i.e. they have the same -value in all Emacs buffers. However, they can instead be made always -buffer local by setting @code{c-style-variables-are-local-p} to -non-@code{nil} before @ccmode{} is initialized. - -@vindex c-old-style-variable-behavior -@vindex old-style-variable-behavior (c-) -@item -The default value of any style variable (with two exceptions --- see -below) is the special symbol @code{set-from-style}. Variables that are -still set to that symbol when a @ccmode{} buffer is initialized will be -set according to the current style, otherwise they will keep their -current value@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}.}. - -Note that when we talk about the ``default value'' for a style variable, -we don't mean the @code{set-from-style} symbol that all style variables -are set to initially, but instead the value it will get at mode -initialization when neither a style nor a global setting has set its -value. - -The style variable @code{c-offsets-alist} is handled a little -differently from the other style variables. It's an association list, -and is thus by default set to the empty list, @code{nil}. When the -style system is initialized, any syntactic symbols already on it are -kept --- only the missing ones are filled in from the chosen style. - -The style variable @code{c-special-indent-hook} is also handled in a -special way. Styles may only add more functions on this hook, so the -global settings on it are always preserved@footnote{This did not change -in version 5.26.}. - -@item -The global settings of style variables get captured in the special -@code{user} style, which is used as the base for all the other styles. -@xref{Built-in Styles}, for details. - -@end itemize - -The style variables are: -@code{c-basic-offset}, -@code{c-comment-only-line-offset}, -@code{c-block-comment-prefix}, -@code{c-comment-prefix-regexp}, -@code{c-cleanup-list}, -@code{c-hanging-braces-alist}, -@code{c-hanging-colons-alist}, -@code{c-hanging-semi&comma-criteria}, -@code{c-backslash-column}, -@code{c-special-indent-hook}, -@code{c-label-minimum-indentation}, and -@code{c-offsets-alist}. - @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 +@node Built-in Styles, Choosing a Style, Styles, Styles @comment node-name, next, previous, up @subsection Built-in Styles -@cindex 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 +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 available at +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 -@uref{http://www.python.org/}.}. +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 -@findex 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 -@item -@code{user} --- This is a special style for several reasons. First, the -@ccmode{} customizations you do by using either the Customization -interface, or by writing @code{setq}'s at the top level of your -@file{.emacs} file, 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} -(@pxref{Adding Styles}) you need only define the differences between -your new style and @code{user} style. +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 -@vindex c-default-style +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Choosing a Style, Adding Styles, Built-in Styles, Styles +@comment node-name, next, previous, up +@subsection Choosing a Style +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +Use @kbd{C-c .} to choose a style interactively: + +@deffn Command c-set-style style-name +@findex set-style (c-) +@kindex C-c . +Switch to the specified style in the current buffer. Use +interactively like this: + +@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. + +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}. +@end deffn + +The default style in all newly created buffers is @code{gnu}, except +in Java and AWK modes where it's @code{java} and @code{awk}. + +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. + +@defopt c-default-style @vindex default-style (c-) -The default style in all newly created buffers is @code{gnu}, but you -can change this by setting variable @code{c-default-style}. Although -the @code{user} style is not the default style, any style variable -settings you do with the Customization interface or on the top level in -your @file{.emacs} file will by default override the style system, so -you don't need to set @code{c-default-style} to @code{user} to see the -effect of these settings. - -@code{c-default-style} takes either a style name string, or an -association list of major mode symbols to style names. Thus you can -control exactly which default style is used for which @ccmode{} language -mode. Here are the rules: - -@vindex c-style-alist -@vindex style-alist (c-) -@vindex c-mode-common-hook -@vindex mode-common-hook (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: + @enumerate @item When @code{c-default-style} is a string, it must be an existing style -name as found in @code{c-style-alist}. This style is then used for all -modes @emph{except} @code{java-mode}, where the style @samp{java} is -used by default@footnote{This is for backwards compatibility reasons. -The hard-coding of @code{java-mode} style is admittedly bogus!}. +name. This style is then used for all modes. @item -When @code{c-default-style} is an association list, the current major -mode is looked up to find a style name string. In this case, this style -is always used exactly as specified and an error will occur if the named -style does not exist. +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, but the current major -mode isn't found, then the special symbol @samp{other} is looked up. If -this value is found, the associated style is used. +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. @item -If @samp{other} is not found, then the @samp{gnu} style is used. +If @samp{other} is not found then the @samp{gnu} style is used. +@end enumerate -@item -In all cases, the style described in @code{c-default-style} is installed +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 +this setting by including an explicit call to @code{c-set-style} in your language mode hook, or in @code{c-mode-common-hook}. -@end enumerate - -@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 - -@kbd{C-c . @var{STYLE-NAME} RET} - -@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. - -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}. +The standard value of @code{c-default-style} is @w{@code{((java-mode +. "java") (awk-mode . "awk") (other . "gnu"))}}. +@end defopt -@vindex c-indentation-style +@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 set @code{c-default-style} or 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 +@node Adding Styles, File Styles, Choosing a Style, Styles @comment node-name, next, previous, up -@subsection Adding Styles -@cindex adding styles +@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 +@node File Styles, , Adding Styles, Styles @comment node-name, next, previous, up @subsection File Styles -@cindex 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. +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{}}). -@vindex c-file-style -@vindex file-style (c-) -@vindex c-file-offsets -@vindex file-offsets (c-) +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: -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}. +@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 -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 offsets using -@code{c-set-offset}. +@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}). 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. - +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 +@node Custom Filling and Breaking, Custom Auto-newlines, Config Basics, Top @comment node-name, next, previous, up -@section Advanced Customizations +@chapter Customizing Filling and Line Breaking @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@vindex c-style-alist -@vindex style-alist (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. +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. -@menu -* Custom Indentation Functions:: -* Custom Brace and Colon Hanging:: -* Customizing Semi-colons and Commas:: -* Other Special Indentations:: -@end menu +@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. -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Custom Indentation Functions, Custom Brace and Colon Hanging, , Advanced Customizations -@comment node-name, next, previous, up -@subsection Custom Indentation Functions -@cindex custom indentation functions -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@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 -The most flexible way to customize @ccmode{} is by writing custom -indentation functions, and associating them with specific syntactic -symbols (@pxref{Syntactic Symbols}). @ccmode{} itself uses indentation -functions to provide more sophisticated indentation, for example when -lining up C++ stream operator blocks: @example -@group +// blah blah +@end example -1: void main(int argc, char**) -2: @{ -3: cout << "There were " -4: << argc -5: << "arguments passed to the program" -6: << endl; -7: @} +@noindent +with two or more slashes in front of them, and the second and +subsequent lines of C style block comments like +@example +@group +/* + * 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: -@example -@group +@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. -(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)))) +@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 +/* 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 -Indentation functions take a single argument, which is a syntactic -component cons cell (@pxref{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. - -The function should return @code{nil} if it's used in a situation where -it doesn't want to do any decision. If the function is used in a list -expression (@pxref{Customizing Indentation}), that will cause @ccmode{} -to go on and check the next entry in the list. - -@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 relevant for C++.}: -@example -(c-set-offset 'stream-op 'c-lineup-streamop) +@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 -Now the function looks like this after re-indenting (using @kbd{C-c -C-q}): +@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 overriden 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 -@group +/* Got O(n^2) here, which is a Bad Thing. */ +@end example -1: void main(int argc, char**) -2: @{ -3: cout << "There were " -4: << argc -5: << " arguments passed to the program" -6: << endl; -7: @} +@noindent +break into +@example +@group +/* Got O(n^2) here, which + * is a Bad Thing. */ @end group @end example -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. +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 -@ccmode{} comes with an extensive set of predefined indentation -functions, not all of which are used by the default styles. So there's -a good chance the function you want already exists. @xref{Indentation -Functions}, for a list of them. If you have written an indentation -function that you think is generally useful, you're very welcome to -contribute it; please contact @email{bug-cc-mode@@gnu.org}. +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 Brace and Colon Hanging, Customizing Semi-colons and Commas, Custom Indentation Functions, Advanced Customizations +@node Custom Auto-newlines, Clean-ups, Custom Filling and Breaking, Top @comment node-name, next, previous, up -@subsection Custom Brace and Colon Hanging +@chapter Customizing Auto-newlines @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@vindex c-hanging-braces-alist -@vindex hanging-braces-alist (c-) -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} style variable. -Remember that @var{ACTION}'s are typically a list containing some -combination of the symbols @code{before} and @code{after} -(@pxref{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}, -including neither of them (i.e. @code{nil}). This return value has the -normal brace hanging semantics. +@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 + +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: -As an example, @ccmode{} itself uses this feature to dynamically -determine the hanginess of braces which close ``do-while'' -constructs: @example @group +while (i < MAX) @{ + total += entry[i]; + entry [i++] = 0; +@} +@end group +@end example -void do_list( int count, char** atleast_one_string ) +@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. + +The next chapter, ``Clean-ups'', describes how to configure @ccmode{} +to remove these automatically added newlines in certain specific +circumstances. @xref{Clean-ups}. + +@menu +* Hanging Braces:: +* Hanging Colons:: +* Hanging Semicolons and Commas:: +@end menu + + +@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 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +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}. + +Say you wanted an auto-newline after (but not before) the following +@samp{@{}: + +@example +if (foo < 17) @{ +@end example + +@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: + +@example +((substatement-open 1061)) +@end example + +@noindent +So here you need to put the entry @code{(substatement-open . (after))} +into @code{c-hanging-braces-alist}. + +If you don't want any auto-newlines for a particular syntactic symbol, +put this into @code{c-hanging-braces-alist}: + +@example +(brace-entry-open) +@end example + +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. + +@defopt c-hanging-braces-alist +@vindex hanging-braces-alist (c-) + +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: + +@example +// here, open braces always `hang' +void spam( int i ) @{ + if( i == 7 ) @{ + dosomething(i); + @} +@} +@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 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 + +@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. 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 synctactic 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)@tie{}when calling a c-hanging-semi&comma-criteria function +(@pxref{Hanging Semicolons and Commas}; (ii)@tie{}when calling a +line-up function (@pxref{Custom Line-Up}; (iii)@tie{}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 +void do_list( int count, char** atleast_one_string ) @{ int i=0; do @{ @@ -2606,28 +3250,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) @@ -2638,77 +3273,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 customization, colon hanging +@vindex c-hanging-colons-alist +@vindex hanging-colons-alist (c-) + +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. + +@defopt c-hanging-colons-alist +@vindex hanging-colons-alist (c-) -@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} style variable. Since no use has actually -been found for this feature, it isn't currently implemented! +@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 +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. @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Customizing Semi-colons and Commas, Other Special Indentations, Custom Brace and Colon Hanging, Advanced Customizations +@node Hanging Semicolons and Commas, , Hanging Colons, Custom Auto-newlines @comment node-name, next, previous, up -@subsection Customizing Semi-colons and Commas -@cindex customizing semi-colons and commas +@section Hanging Semicolons and Commas +@cindex hanging semicolons +@cindex hanging commas +@cindex customization, semicolon newlines +@cindex customization, comma newlines @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@vindex c-hanging-semi&comma-criteria +@defopt 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 (@pxref{Minor -Modes}). This is controlled by the style 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: - -@itemize @bullet -@item -non-@code{nil} --- A newline is inserted, and no more functions from the -list are called. +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: -@item -@code{stop} --- No more functions from the list are called, but no -newline is inserted. - -@item -@code{nil} --- No determination is made, and the next function in the -list is called. +@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 -@end itemize +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. -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). +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 -@findex c-semi&comma-no-newlines-before-nonblanks +@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 ?\;) @@ -2716,13 +3387,12 @@ 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 function @code{c-semi&comma-inside-parenlist} is what prevents newlines from being inserted inside the parenthesis list of @code{for} @@ -2731,1241 +3401,2609 @@ statements. In addition to @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 +@node Clean-ups, Indentation Engine Basics, Custom Auto-newlines, Top @comment node-name, next, previous, up -@subsection Other Special Indentations +@chapter Clean-ups +@cindex clean-ups @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@vindex 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 top-level constructs. This minimum -indentation is controlled by the style variable -@code{c-label-minimum-indentation}. The default value for this variable -is 1. - -@vindex c-special-indent-hook -@vindex special-indent-hook (c-) -One other customization variable is available in @ccmode{}: The style -variable @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. +@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}. -@kindex M-; -@findex indent-for-comment -@vindex c-indent-comments-syntactically-p -@vindex indent-comments-syntactically-p (c-) -@vindex comment-column -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. +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. -Note that this has no effect for comment lines that are inserted with -@kbd{M-;} at the end of regular code lines. These comments will always -start at @code{comment-column}. +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}). +@defopt c-cleanup-list +@vindex cleanup-list (c-) +@cindex literal -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Syntactic Symbols, Indentation Functions, Customizing Indentation, Top -@comment node-name, next, previous, up -@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-) -Here is a complete list of the recognized syntactic symbols as described -in the @code{c-offsets-alist} style variable, along with a brief -description. More detailed descriptions follow. +These are the clean-ups that are only active when electric and +auto-newline minor modes are enabled: +@c TBD: Would like to use some sort of @deffoo here; @table indents a +@c bit too much in dvi output. @table @code -@item string -Inside a multi-line string. -@item c -Inside a multi-line C style block comment. -@item defun-open -Brace that opens a top-level function definition. -@item defun-close -Brace that closes a top-level function definition. -@item defun-block-intro -The first line in a top-level defun. -@item class-open -Brace that opens a class definition. -@item class-close -Brace that closes a class definition. -@item inline-open -Brace that opens an in-class inline method. -@item inline-close -Brace that closes an in-class inline method. -@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. -@item knr-argdecl-intro -First line of a K&R C argument declaration. -@item knr-argdecl -Subsequent lines in a K&R C argument declaration. -@item topmost-intro -The first line in a ``topmost'' definition. -@item topmost-intro-cont -Topmost definition continuation lines. -@item member-init-intro -First line in a member initialization list. -@item member-init-cont -Subsequent member initialization list lines. -@item inher-intro -First line of a multiple inheritance list. -@item inher-cont -Subsequent multiple inheritance lines. -@item block-open -Statement block open brace. -@item block-close -Statement block close brace. -@item brace-list-open -Open brace of an enum or static array list. -@item brace-list-close -Close brace of an enum or static array list. -@item brace-list-intro -First line in an enum or static array list. -@item brace-list-entry -Subsequent lines in an enum or static array list. -@item brace-entry-open -Subsequent lines in an enum or static array list where the line begins -with an open brace. -@item statement -A statement. -@item statement-cont -A continuation of a statement. -@item statement-block-intro -The first line in a new statement block. -@item statement-case-intro -The first line in a case block. -@item statement-case-open -The first line in a case block that starts with a brace. -@item substatement -The first line after a conditional or loop construct. -@item substatement-open -The brace that opens a substatement block. -@item case-label -A @code{case} or @code{default} label. -@item access-label -C++ access control label. -@item label -Any non-special C label. -@item do-while-closure -The @code{while} line that ends a @code{do}-@code{while} construct. -@item else-clause -The @code{else} line of an @code{if}-@code{else} construct. -@item catch-clause -The @code{catch} or @code{finally} (in Java) line of a -@code{try}-@code{catch} construct. -@item comment-intro -A line containing only a comment introduction. -@item arglist-intro -The first line in an argument list. -@item arglist-cont -Subsequent argument list lines when no arguments follow on the same line -as the the arglist opening paren. -@item arglist-cont-nonempty -Subsequent argument list lines when at least one argument follows on the -same line as the arglist opening paren. -@item arglist-close -The solo close paren of an argument list. -@item stream-op -Lines continuing a stream operator (C++ only). -@item inclass -The line is nested inside a class definition. -@item cpp-macro -The start of a C preprocessor macro definition. -@item cpp-macro-cont -Subsequent lines of a multi-line C preprocessor macro definition. -@item friend -A C++ friend declaration. -@item objc-method-intro -The first line of an Objective-C method. definition. -@item objc-method-args-cont -Lines continuing an Objective-C method. definition -@item objc-method-call-cont -Lines continuing an Objective-C method call. -@item extern-lang-open -Brace that opens an external language block. -@item extern-lang-close -Brace that closes an external language block. -@item inextern-lang -Analogous to @code{inclass} syntactic symbol, but used inside external -language blocks (e.g. @code{extern "C" @{}). -@item namespace-open -Brace that opens a C++ namespace block. -@item namespace-close -Brace that closes a C++ namespace block. -@item innamespace -Analogous to @code{inextern-lang} syntactic symbol, but used inside C++ -namespace blocks. -@item template-args-cont -C++ template argument list continuations. -@item inlambda -Analogous to @code{inclass} syntactic symbol, but used inside lambda -(i.e. anonymous) functions. Only used in Pike mode. -@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. -@item inexpr-statement -A statement block inside an expression. The gcc C extension of this is -recognized. It's also used for the special functions that takes a -statement block as an argument in Pike. -@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. -@end table +@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: -@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}. - -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 - - 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: @} - +void spam(int i) +@{ + if( i==7 ) @{ + dosomething(); + @} + else + @{ @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 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. - -@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. +@noindent +appears like this after the last open brace is typed: -Here's another example, which illustrates some C++ class syntactic -symbols: @example @group - - 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: @} - +void spam(int i) +@{ + if( i==7 ) @{ + dosomething(); + @} else @{ @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. - -@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. - -@cindex access-label syntactic symbol -@cindex inclass syntactic symbol -Hitting @kbd{C-c C-s} on line 5 shows the following analysis: +@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 - -@code{((inclass . 58) (access-label . 67))} - +void spam(int i) +@{ + if( i==7 ) @{ + dosomething(); + @} + else if( i==3 ) + @{ @end group @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: +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 -@code{((inclass . 58) (topmost-intro . 60))} +@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 -@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. +@item brace-catch-brace +Analogous to @code{brace-elseif-brace}, but cleans up @samp{@} catch +(...) @{} in C++ and Java mode. -@cindex in-class inline methods -@cindex inline-open syntactic symbol -@cindex inline-close syntactic symbol -Line 11's analysis is a bit more complicated: +@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 -@code{((inclass . 58) (inline-open))} +@noindent +is transformed into this when the close brace is typed: +@example +@group +class Spam +@{@} @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: +@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 Bass - : public Guitar, - public Amplifiable +class Spam @{ -public: - Bass(); +... @} +; +@end group +@end example + +@noindent +is transformed into this when the semicolon is typed: -inline -Bass::Bass() - : eString( new BassString( 0.105 )), - aString( new BassString( 0.085 )), - dString( new BassString( 0.065 )), - gString( new BassString( 0.045 )) +@example +@group +class Spam @{ - eString.tune( 'E' ); - aString.tune( 'A' ); - dString.tune( 'D' ); - gString.tune( 'G' ); -@} +... +@}; +@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 -@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: +@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@tie{}(SIGINT, +SIG_IGN)} and @samp{abort@tie{}()}. 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{*/}. +@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 +@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 +@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 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@code{((friend) (inclass . 58) (topmost-intro . 380))} +@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 -The @code{friend} syntactic symbol is a modifier that typically does not -have a relative buffer position. +@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. -Template definitions introduce yet another syntactic symbol: +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 -@group + 1: void swap( int& a, int& b ) + 2: @{ + 3: int tmp = a; + 4: a = b; + 5: b = tmp; + 6: @} +@end example - 1: ThingManager framework_callbacks; +@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: -@end group +@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 -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 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: -Here is another (totally contrived) example which illustrates how syntax -is assigned to various conditional constructs: @example -@group +((defun-block-intro 29)) +@end example - 1: void spam( int index ) - 2: @{ - 3: for( int i=0; i 0 ); - 16: @} +@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: -@end group +@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 -Only the lines that illustrate new syntactic symbols will be discussed. +Hitting @kbd{C-c C-s} on line 4 gives us: -@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 catch-clause 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. The @code{try}-@code{catch} -constructs in C++ and Java are treated this way too, with the only -difference that the @code{catch}, and in Java also @code{finally}, is -marked with @code{catch-clause}. - -@cindex substatement syntactic symbol -Line 10 is also slightly different. Because @code{else} is considered a -conditional introducing keyword @footnote{The list of conditional -keywords are (in C, C++, Objective-C, Java, and Pike): @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. +@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}: -Switch statements have their own set of syntactic symbols. Here's an -example: @example -@group + 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 - 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: @} +@noindent +Hitting @kbd{C-c C-s} on line 3 of this example gives: -@end group +@example +((comment-intro) (defun-block-intro 46)) @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. +@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 preproprocessor 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 returns +@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 centres 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: -@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 @group - - 1: static char* ingredients[] = - 2: @{ - 3: "Ham", - 4: "Salt", - 5: NULL - 6: @} - +main (int, + char ** + ) @hereFn{c-lineup-close-paren} @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. +@noindent +and -@cindex brace-entry-open syntactic symbol -Your static initializer might be initializing nested structures, for -example: @example @group - - 1: struct intpairs[] = - 2: @{ - 3: @{ 1, 2 @}, - 4: @{ - 5: 3, - 6: 4 - 7: @} - 8: @{ 1, - 9: 2 @}, - 10: @{ 3, 4 @} - 11: @} - +main ( + int, char ** +) @hereFn{c-lineup-close-paren} @end group @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. +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. -External language definition blocks also have their own syntactic -symbols. In this example: -@example -@group +@workswith All @code{*-close} symbols. +@end defun - 1: extern "C" - 2: @{ - 3: int thing_one( int ); - 4: int thing_two( double ); - 5: @} +@comment ------------------------------------------------------------ -@end group -@end example +@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. -@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}. +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. -Similarly, C++ namespace constructs have their own associated syntactic -symbols. In this example: -@example -@group +@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 - 1: namespace foo - 2: @{ - 3: void xxx() @{@} - 4: @} +@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 -@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}. +and -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 - - 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: @} - +if (n > 0) +@{ @hereFn{c-indent-one-line-block} + m+=n; n=0; +@} @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. +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 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. +@workswith Almost all syntactic symbols, but most useful on the +@code{-open} symbols. +@end defun -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 ------------------------------------------------------------ + +@defun c-indent-multi-line-block +@findex indent-multi-line-block (c-) +Indent a multiline block @code{c-basic-offset} extra. E.g: -A few miscellaneous syntactic symbols that haven't been previously -covered are illustrated by this C++ example: @example @group - - 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: @} - +int *foo[] = @{ + NULL, + @{17@}, @hereFn{c-indent-multi-line-block} @end group @end example -The lines to note in this example include: - -@itemize @bullet +@noindent +and -@cindex func-decl-cont syntactic symbol -@item -Line 2 is assigned the @code{func-decl-cont} syntax. +@example +@group +int *foo[] = @{ + NULL, + @{ @hereFn{c-indent-multi-line-block} + 17 + @}, + @sssTBasicOffset{} +@end group +@end example -@cindex comment-intro syntactic symbol -@item -Line 4 is assigned both @code{defun-block-intro} @emph{and} -@code{comment-intro} syntax. +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 c syntactic symbol -@item -Line 5 is assigned @code{c} syntax. +@workswith Almost all syntactic symbols, but most useful on the +@code{-open} symbols. +@end defun -@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. +@comment ------------------------------------------------------------ -@cindex string syntactic symbol -@item -Line 8 is assigned @code{string} syntax. +@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: -@cindex label syntactic symbol -@item -Line 10 is assigned @code{label} syntax. +@example +@group +int main() +@{ puts ("Hello!"); + return 0; @hereFn{c-lineup-runin-statements} +@} +@end group +@end example -@cindex block-open syntactic symbol -@item -Line 11 is assigned @code{block-open} 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 cpp-macro syntactic symbol -@cindex cpp-macro-cont syntactic symbol -@item -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. +@workswith The @code{statement} syntactic symbol. +@end defun -@cindex stream-op syntactic symbol -@item -Line 17 is assigned @code{stream-op} syntax. +@comment ------------------------------------------------------------ -@end itemize +@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. -@cindex multi-line macros -@cindex syntactic whitespace -Multi-line C preprocessor macros are now (somewhat) supported. At least -@ccmode{} 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 +@workswith @code{inlambda}, @code{inexpr-statement}, +@code{inexpr-class}. +@end defun - 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 +@comment ------------------------------------------------------------ -@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. +@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: -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 foo() + @{ + a; + x; @hereFn{c-lineup-after-whitesmith-blocks} @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. - -Java has a concept of anonymous classes, which may look something like -this: @example @group - - 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: @} - +int foo() + @{ + @{ + a; + @} + x; @hereFn{c-lineup-after-whitesmith-blocks} @end group @end example -@cindex inexpr-class syntactic symbol -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}. +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. -There are a few occasions where a statement block may be used inside an -expression. One is in C code using the gcc extension for this, e.g: -@example -@group +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}. - 1: int res = (@{ - 2: int y = foo (); int z; - 3: if (y > 0) z = y; else z = - y; - 4: z; - 5: @}); +@workswith @code{brace-list-entry}, @code{brace-entry-open}, +@code{statement}, @code{arglist-cont}. +@end defun -@end group -@end example +@comment ------------------------------------------------------------ -@cindex inexpr-statement syntactic symbol -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. +@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: -In Pike code, there are a few other situations where blocks occur inside -statements, as illustrated here: @example @group - - 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: @} - +something + @{ + foo; @hereFn{c-lineup-whitesmith-in-block} + @} @end group @end example -@cindex inlambda syntactic symbol -@cindex lambda-intro-cont syntactic symbol -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.}. - -@cindex inexpr-statement syntactic symbol -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. +@noindent +and -@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 - - 1: int add_three_integers(a, b, c) - 2: int a; - 3: int b; - 4: int c; - 5: @{ - 6: return a + b + c; - 7: @} - +something @{ + foo; @hereFn{c-lineup-whitesmith-in-block} + @} +@sssTBasicOffset{} @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. +In the first case the indentation is kept unchanged, in the second +@code{c-basic-offset} is added. +@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 Indentation Functions, Performance Issues, Syntactic Symbols, Top +@node List Line-Up, Operator Line-Up, Brace/Paren Line-Up, Line-Up Functions @comment node-name, next, previous, up -@chapter Indentation Functions -@cindex indentation functions -@cindex line-up functions +@subsection List Line-Up Functions @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -Often there are cases when a simple offset setting on a syntactic symbol -isn't enough to get the desired indentation. Therefore, it's also -possible to use a @dfn{indentation function} (a.k.a. line-up function) -for a syntactic symbol. - -@ccmode{} comes with many predefined indentation functions for common -situations. If none of these does what you want, you can write your -own, see @ref{Custom Indentation Functions}. If you do, it's probably a -good idea to start working from one of these predefined functions, they -can be found in the file @file{cc-align.el}. - -For every function below there is a ``works with'' list that indicates -which syntactic symbols the function is intended to be used with. - -@macro workswith -@emph{Works with:} -@end macro -@ifinfo -@unmacro workswith -@macro workswith -Works with: -@end macro -@end ifinfo +The line-up functions here calculate the indentation for lines which +form lists of items, usually separated by commas. -@table @code +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. -@findex c-lineup-arglist +@defun c-lineup-arglist @findex lineup-arglist (c-) -@item c-lineup-arglist -Line up the current argument line under the first argument. - -@workswith @code{arglist-cont-nonempty}. - -@findex c-lineup-arglist-intro-after-paren -@findex lineup-arglist-intro-after-paren (c-) -@item c-lineup-arglist-intro-after-paren -Line up a line just after the open paren of the surrounding paren or -brace block. - -@workswith @code{defun-block-intro}, @code{brace-list-intro}, -@code{statement-block-intro}, @code{statement-case-intro}, -@code{arglist-intro}. - -@findex c-lineup-arglist-close-under-paren -@findex lineup-arglist-close-under-paren (c-) -@item c-lineup-arglist-close-under-paren -Set e.g. 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. +Line up the current argument line under the first argument. -@workswith @code{defun-close}, @code{class-close}, @code{inline-close}, -@code{block-close}, @code{brace-list-close}, @code{arglist-close}, -@code{extern-lang-close}, @code{namespace-close} (for most of these, a -zero offset will normally produce the same result, though). +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: -@findex c-lineup-close-paren -@findex lineup-close-paren (c-) -@item c-lineup-close-paren -Line up the closing paren under its corresponding open paren if the -open paren is followed by code. If the open paren ends its line, no -indentation is added. E.g: @example @group - -main (int, - char ** - ) // c-lineup-close-paren - +A_VERY_LONG_MACRO_NAME (@{ + some (code, with + long, lines * in[it]); + @}); +@sssTBasicOffset{} @end group @end example -@noindent -and -@example -@group -main ( - int, char ** -) // c-lineup-close-paren +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. -@end group -@end example +@workswith @code{arglist-cont-nonempty}, @code{arglist-close}. +@end defun -@workswith @code{defun-close}, @code{class-close}, @code{inline-close}, -@code{block-close}, @code{brace-list-close}, @code{arglist-close}, -@code{extern-lang-close}, @code{namespace-close}. +@comment ------------------------------------------------------------ -@findex c-lineup-streamop -@findex lineup-streamop (c-) -@item c-lineup-streamop -Line up C++ stream operators (i.e. @samp{<<} and @samp{>>}). +@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. -@workswith @code{stream-op}. +@workswith @code{defun-block-intro}, @code{brace-list-intro}, +@code{statement-block-intro}, @code{statement-case-intro}, +@code{arglist-intro}. +@end defun -@findex c-lineup-multi-inher +@comment ------------------------------------------------------------ + +@defun c-lineup-multi-inher @findex lineup-multi-inher (c-) -@item c-lineup-multi-inher 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) // c-lineup-multi-inher - + Bar (b) @hereFn{c-lineup-multi-inher} @end group @end example + @noindent and + @example @group - class Foo : public Cyphr, - public Bar // c-lineup-multi-inher - + public Bar @hereFn{c-lineup-multi-inher} @end group @end example + @noindent and + @example @group - Foo::Foo (int a, int b) : Cyphr (a) - , Bar (b) // c-lineup-multi-inher - + , Bar (b) @hereFn{c-lineup-multi-inher} @end group @end example @workswith @code{inher-cont}, @code{member-init-cont}. +@end defun -@findex c-lineup-java-inher +@comment ------------------------------------------------------------ + +@defun c-lineup-java-inher @findex lineup-java-inher (c-) -@item c-lineup-java-inher Line up Java implements and extends declarations. If class names -follows on the same line as the @samp{implements}/@samp{extends} +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 // c-lineup-java-inher - - <--> c-basic-offset - + extends + Bar @hereFn{c-lineup-java-inher} + @sssTBasicOffset{} @end group @end example + @noindent and + @example @group - class Foo extends Cyphr, - Bar // c-lineup-java-inher - + Bar @hereFn{c-lineup-java-inher} @end group @end example @workswith @code{inher-cont}. +@end defun + +@comment ------------------------------------------------------------ -@findex c-lineup-java-throws +@defun c-lineup-java-throws @findex lineup-java-throws (c-) -@item c-lineup-java-throws -Line up Java throws declarations. If exception names follows on the +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: + @example @group - int foo() - throws // c-lineup-java-throws - Bar // c-lineup-java-throws - -<--><--> c-basic-offset - + throws @hereFn{c-lineup-java-throws} + Bar @hereFn{c-lineup-java-throws} +@sssTsssTBasicOffset{} @end group @end example + @noindent and + @example @group - int foo() throws Cyphr, - Bar, // c-lineup-java-throws - Vlod // c-lineup-java-throws - + Bar, @hereFn{c-lineup-java-throws} + Vlod @hereFn{c-lineup-java-throws} @end group @end example @workswith @code{func-decl-cont}. +@end defun -@findex c-indent-one-line-block -@findex indent-one-line-block (c-) -@item c-indent-one-line-block -Indent a one line block @code{c-basic-offset} extra. E.g: -@example -@group +@comment ------------------------------------------------------------ -if (n > 0) - @{m+=n; n=0;@} // c-indent-one-line-block - -<--> c-basic-offset +@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{<}. -@end group -@end example -@noindent -and -@example -@group +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. -if (n > 0) -@{ // c-indent-one-line-block - m+=n; n=0; -@} +@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: + +@example +@group +foo (xyz, aaa + bbb + ccc + + ddd + eee + fff); @hereFn{c-lineup-argcont} @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. +Only continuation lines like this are touched, @code{nil} is returned on +lines which are the start of an argument. -@workswith Almost all syntactic symbols, but most useful on the -@code{-open} symbols. +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: -@findex c-indent-multi-line-block -@findex indent-multi-line-block (c-) -@item c-indent-multi-line-block -Indent a multi line block @code{c-basic-offset} extra. E.g: @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 -int *foo[] = @{ - NULL, - @{17@}, // c-indent-multi-line-block +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): -@end group +@example +(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 -@noindent -and + +@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 + +@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 -int *foo[] = @{ - NULL, - @{ // c-indent-multi-line-block - 17 - @}, +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 ------------------------------------------------------------ - <--> c-basic-offset +@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: + +@example +@group +result = prefix + "A message " + "string."; @hereFn{c-lineup-string-cont} @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 multi line -block, which makes the function usable in list expressions. +@code{nil} is returned in other situations, to allow stacking with other +lineup functions. -@workswith Almost all syntactic symbols, but most useful on the -@code{-open} symbols. +@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 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +The lineup functions here calculate the indentation for several types +of comment structure. -@findex c-lineup-C-comments +@defun c-lineup-C-comments @findex lineup-C-comments (c-) -@item c-lineup-C-comments Line up C block comment continuation lines. Various heuristics are used to handle most of the common comment styles. Some examples: -@example +@example @group /* /** /* * text * text text */ */ */ @end group +@end example +@example @group /* text /* /** text ** text ** text */ */ */ @end group +@end example +@example @group /************************************************** * text *************************************************/ @end group +@end example @vindex comment-start-skip +@example @group /************************************************** Free form text comments: @@ -3976,7 +6014,6 @@ to handle most of the common comment styles. Some examples: @code{comment-start-skip} regexp. **************************************************/ @end group - @end example The style variable @code{c-comment-prefix-regexp} is used to recognize @@ -3984,430 +6021,539 @@ the comment line prefix, e.g. the @samp{*} that usually starts every line inside a comment. @workswith The @code{c} syntactic symbol. +@end defun + +@comment ------------------------------------------------------------ -@findex c-lineup-comment +@defun c-lineup-comment @findex lineup-comment (c-) -@item c-lineup-comment 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. -@vindex c-comment-only-line-offset +@defopt c-comment-only-line-offset @vindex comment-only-line-offset (c-) -@code{c-comment-only-line-offset} specifies the extra offset for the -line. It can contain an integer or a cons cell of the form -@example - - (@r{} . @r{}) +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 @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{} . -1000)}. +is equivalent to @code{(@r{@var{value}} . -1000)}. +@end defopt @workswith @code{comment-intro}. +@end defun -@findex c-lineup-runin-statements -@findex lineup-runin-statements (c-) -@item c-lineup-runin-statements -Line up statements for coding standards which place the first statement -in a block on the same line as the block opening brace@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.}. E.g: -@example -@group - -int main() -@{ puts (\"Hello world!\"); - return 0; // c-lineup-runin-statements -@} - -@end group -@end example - -If there is no statement after the opening brace to align with, -@code{nil} is returned. This makes the function usable in list -expressions. - -@workswith The @code{statement} syntactic symbol. - -@findex c-lineup-math -@findex lineup-math (c-) -@item c-lineup-math -Line up the current line after the equal sign on the first line in the -statement. If there isn't any, indent with @code{c-basic-offset}. If -the current line contains an equal sign too, try to align it with the -first one. - -@workswith @code{statement-cont}. - -@findex c-lineup-template-args -@findex lineup-template-args (c-) -@item c-lineup-template-args -Line up the arguments of a template argument list under each other, but -only in the case where the first argument is on the same line as the -opening @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}. - -@findex c-lineup-ObjC-method-call -@findex lineup-ObjC-method-call (c-) -@item c-lineup-ObjC-method-call -For Objective-C code, line up selector args as @code{elisp-mode} does -with function args: go to the position right after the message receiver, -and if you are at the end of the line, indent the current line -c-basic-offset columns from the opening bracket; otherwise you are -looking at the first character of the first method call argument, so -lineup the current line with it. - -@workswith @code{objc-method-call-cont}. - -@findex c-lineup-ObjC-method-args -@findex lineup-ObjC-method-args (c-) -@item c-lineup-ObjC-method-args -For Objective-C code, line up the colons that separate args. The colon -on the current line is aligned with the one on the first line. - -@workswith @code{objc-method-args-cont}. - -@findex c-lineup-ObjC-method-args-2 -@findex lineup-ObjC-method-args-2 (c-) -@item 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. - -@workswith @code{objc-method-args-cont}. - -@findex c-lineup-inexpr-block -@findex lineup-inexpr-block (c-) -@item c-lineup-inexpr-block -This can be used with the in-expression block symbols to indent the -whole block to the column where the construct is started. E.g. for Java -anonymous classes, this lines up the class under the @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. - -@workswith @code{inlambda}, @code{inexpr-statement}, -@code{inexpr-class}. - -@findex c-lineup-whitesmith-in-block -@findex lineup-whitesmith-in-block (c-) -@item c-lineup-whitesmith-in-block -Line up lines inside a block in Whitesmith style. It's done in a way -that works both when the opening brace hangs and when it doesn't. E.g: -@example -@group - -something - @{ - foo; // c-lineup-whitesmith-in-block - @} - -@end group -@end example -@noindent -and -@example -@group - -something @{ - foo; // c-lineup-whitesmith-in-block - @} +@comment ------------------------------------------------------------ -<--> c-basic-offset +@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: +@example +@group +int main() +/* Called at startup. */ @hereFn{c-lineup-knr-region-comment} +@{ + return 0; +@} @end group @end example -In the first case the indentation is kept unchanged, in the second -@code{c-basic-offset} is added. +Return @code{nil} if called in any other situation, to be useful in list +expressions. -@workswith @code{defun-close}, @code{defun-block-intro}, -@code{block-close}, @code{brace-list-close}, @code{brace-list-intro}, -@code{statement-block-intro}, @code{inclass}, @code{inextern-lang}, -@code{innamespace}. +@workswith @code{comment-intro}. +@end defun + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Misc Line-Up, , Comment Line-Up, Line-Up Functions +@comment node-name, next, previous, up +@subsection Miscellaneous Line-Up Functions +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@findex c-lineup-dont-change +The line-up functions here are the odds and ends which didn't fit into +any earlier category. + +@defun c-lineup-dont-change @findex lineup-dont-change (c-) -@item 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 lineup function makes the line stay at whatever indentation it +already has; think of it as an identity function for lineups. @workswith Any syntactic symbol. +@end defun -@end table +@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: -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Performance Issues, Frequently Asked Questions, Indentation Functions, Top -@comment node-name, next, previous, up -@chapter Performance Issues -@cindex performance issues -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@example +@group +const char msg[] = @hereFn{@r{The beginning of the preceding construct.}} + \"Some text.\"; -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. +#define X(A, B) \ +do @{ \ @hereFn{c-lineup-cpp-define} + printf (A, B); \ +@} while (0) +@end group +@end example -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! +@noindent +and: -@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, however that ``something reasonable'' is -difficult to define, so @ccmode{} doesn't do it for you. +@example +@group +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 -@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 anyway because you'll be doing regular expression searches -for every line you indent, so you're probably screwed either way! +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: -@vindex c-enable-xemacs-performance-kludge-p -@vindex enable-xemacs-performance-kludge-p (c-) -Another alternative for XEmacs users, is to 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 quicker 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 20.2 or 20.3 as of -this writing 27-Apr-1998). - -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 comments. - -@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 -@cindex FAQ -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@example +@group +const char msg[] = + \"Some text.\"; -@kindex C-x h -@kindex C-M-\ -@kindex C-M-x -@kindex C-M-q -@kindex C-M-u -@kindex RET -@kindex C-j -@quotation +#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 + +@noindent +and: -@strong{Q.} @emph{How do I re-indent the whole file?} +@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 -@strong{A.} Visit the file and hit @kbd{C-x h} to mark the whole -buffer. Then hit @kbd{C-M-\}. +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. -@sp 1 -@strong{Q.} @emph{How do I re-indent the entire function? -@kbd{C-M-x} doesn't work.} +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. -@strong{A.} @kbd{C-M-x} is reserved for future Emacs use. -To re-indent the entire function hit @kbd{C-c C-q}. +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. -@sp 1 -@strong{Q.} @emph{How do I re-indent the current block?} +@workswith @code{cpp-define-intro}. +@end defun -@strong{A.} First move to the brace which opens the block with -@kbd{C-M-u}, then re-indent that expression with -@kbd{C-M-q}. +@comment ------------------------------------------------------------ -@sp 1 -@strong{Q.} @emph{Why doesn't the @kbd{RET} key indent the new line?} +@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{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}: @example +@group + asm ("foo %1, %0\n" + "bar %0, %1" + : "=r" (w), + "=r" (x) + : "0" (y), + "1" (z)); +@end group +@end example -(define-key c-mode-base-map "\C-m" 'c-context-line-break) +The @samp{x} line is aligned to the text after the @samp{:} on the +@samp{w} line, and similarly @samp{z} under @samp{y}. + +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. +@example +(c-lineup-gcc-asm-reg c-lineup-arglist) @end example -This is a very common question. If you want this to be the default -behavior, don't lobby me, lobby RMS! @t{:-)} +@workswith @code{arglist-cont}, @code{arglist-cont-nonempty}. +@end defun + +@comment ------------------------------------------------------------ -@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.} +@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.} 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 modify @code{c-offsets-alist} directly: @example +@group +int +neg (int i) @hereFn{c-lineup-topmost-intro-cont} +@{ + return -i; +@} +@end group +@end example -(setq c-offsets-alist '((substatement-open . 0))) +@noindent +and +@example +@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 -@sp 1 -@strong{Q.} @emph{My style settings works in all the @ccmode{} language -modes except for Java, where I still get e.g. 4 column indentation.} +@noindent +and -@strong{A.} Java mode switches to the @samp{java} style by default for -historical reasons. You can override it by putting an association list -on @code{c-default-style}: @example +@group +struct larch +the_larch, @hereFn{c-lineup-topmost-intro-cont} + another_larch; @hereFn{c-lineup-topmost-intro-cont} +@end group +@end example + +@workswith @code{topmost-intro-cont}. +@end defun + +@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 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -(setq c-default-style '((other . "my-style"))) +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 +@example +(@r{@var{syntactic-symbol}} . @r{@var{anchor-position}}) @end example + @noindent -The @samp{other} symbol says that @ccmode{} should use "my-style" in all -modes not explicitly listed. Since there's nothing else on the list -this causes "my-style" to be used in every mode. - -@sp 1 -@strong{Q.} @emph{How do I make strings, comments, keywords, and other -constructs appear in different colors, or in bold face, etc.?} - -@strong{A.} ``Syntax Colorization'' is a standard Emacs feature, -controlled by @code{font-lock-mode}. @ccmode{} does not contain -font-lock definitions for any of its supported languages. - -@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?} - -@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 -also move into blocks. - -@sp 1 -@strong{Q.} @emph{Whenever I try to indent a line or type an -``electric'' key such as @kbd{;}, @kbd{@{}, or @kbd{@}}, I get an error -that look like this: @code{Invalid function: (macro . #[...}. What -gives?} - -@strong{A.} This is a common error when @ccmode{} hasn't been compiled -correctly, especially under Emacs 19.34@footnote{Technically, it's -because some macros wasn't defined during the compilation, so the byte -compiler put in function calls instead of the macro expansions. Later, -when the interpreter tries to call the macros as functions, it shows -this (somewhat cryptic) error message.}. If you are using the standalone -@ccmode{} distribution, try recompiling it according to the instructions -in the @file{README} file. +@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. -@end quotation +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Other Indentation, , Custom Line-Up, Customizing Indentation +@comment node-name, next, previous, up +@section Other Special Indentations +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +Here are the remaining odds and ends regarding indentation: + +@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 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Getting the Latest CC Mode Release, Sample .emacs File, Frequently Asked Questions, Top +@node Custom Macros, Odds and Ends, Customizing Indentation, Top @comment node-name, next, previous, up -@chapter Getting the Latest CC Mode Release +@chapter Customizing Macros +@cindex macros +@cindex preprocessor directives @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@ccmode{} is standard with all versions of Emacs since 19.34 and of -XEmacs since 19.16. +Normally, the lines in a multi-line macro are indented relative to +eachother as though they were code. You can suppress this behaviour +by setting the following user option: -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 via the Web at: +@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 -@example -@group +@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 + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Odds and Ends, Sample .emacs File, Custom Macros, Top +@comment node-name, next, previous, up +@chapter Odds and Ends +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - @uref{http://cc-mode.sourceforge.net/} +The stuff that didn't fit in anywhere else is documented here. -@end group -@end example +@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. -@emph{Old URLs, including the FTP URLs, should no longer be used.} +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 -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. +@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 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Sample .emacs File, Limitations and Known Bugs, Getting the Latest CC Mode Release, Top +@node Sample .emacs File, Performance Issues, Odds and Ends, Top @comment node-name, next, previous, up -@chapter Sample .emacs file +@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. +@verbatim +;; 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. + +;; Make some non-standard key bindings. We can put these 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) + (define-key c-mode-base-map [?\C-\M-a] 'c-beginning-of-defun) + (define-key c-mode-base-map [?\C-\M-e] 'c-end-of-defun) +(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) @@ -4426,161 +6572,376 @@ the individual files, including PostScript documentation. (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") - -;; offset customizations not in my-c-style -(setq c-offsets-alist '((member-init-intro . ++))) +(c-add-style "PERSONAL" my-c-style) ;; 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) + ;; 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, idl-mode-map, and pike-mode-map inherit from it. - (define-key c-mode-base-map "\C-m" 'c-context-line-break) - ) - + ;; 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. +Don't forget to rebind @kbd{C-M-a} and @kbd{C-M-e} to the @ccmode{} +functions @code{beginning-of-defun} and @code{end-of-defun} if you're +going to be hanging your braces! @xref{Sample .emacs 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 +@node Limitations and Known Bugs, FAQ, Performance Issues, Top @comment node-name, next, previous, up -@chapter Limitations and Known Bugs +@chapter Limitations and Known Bugs @cindex limitations @cindex bugs @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @itemize @bullet @item -Re-indenting large regions or expressions can be slow. +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{>}. +@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}. -@findex c-indent-exp -@findex 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. +@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 +@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 -@vindex signal-error-on-buffer-boundary @item -XEmacs versions from 19.15 until (as of this writing 12-Mar-1998) 20.4 -contain a variable called @code{signal-error-on-buffer-boundary}. This -was intended as a solution to user interface problems associated with -buffer movement and the @code{zmacs-region} deactivation on errors. -However, setting this variable to a non-default value had the -deleterious side effect of breaking many built-in primitive functions. -Most users will not be affected since they never change the value of -this variable. @strong{Do not set this variable to @code{nil}}; you -will cause serious problems in @ccmode{} and probably other XEmacs -packages! As of at least XEmacs 20.4, the effects this variable tried -to correct have been fixed in other, better ways. +@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 +@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 Submitting Bug Reports, Concept Index, Limitations and Known Bugs, Top +@node Mailing Lists and Bug Reports, Command and Function Index, Updating CC Mode, Top @comment node-name, next, previous, up -@chapter Mailing Lists and Submitting Bug Reports -@cindex mailing lists -@cindex reporting bugs +@appendix Mailing Lists and Submitting Bug Reports @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @kindex C-c C-b @findex c-submit-bug-report @findex submit-bug-report (c-) -To report bugs, use the @kbd{C-c C-b} (@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. +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 @code{-q -no-site-file} -arguments). If it works correctly there, the problem might be caused by -faulty customizations in either your own or your site configuration. In -that case, we'd appreciate if you isolate the Emacs Lisp code that trigs -the bug and include it in your report. - -Bug reports are now sent to the following email addresses: -@email{bug-cc-mode@@gnu.org} and @email{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? @t{;-)} to -@email{bug-cc-mode@@gnu.org}, or @email{help-gnu-emacs@@gnu.org} which is -mirrored on newsgroup @code{gnu.emacs.help}. - -@cindex beta testers mailing list +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 If you want to get announcements of new @ccmode{} releases, send the word @emph{subscribe} in the body of a message to -@email{cc-mode-announce-request@@lists.sourceforge.net}. Announcements -will also be posted to the Usenet newsgroups @code{gnu.emacs.sources}, -@code{comp.emacs}, @code{comp.emacs.xemacs}, and possibly some of the -language oriented newsgroups. - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Concept Index, Command Index, Mailing Lists and Submitting Bug Reports, Top +@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 Concept Index +@unnumbered Command and Function Index @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@printindex cp +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 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Command Index, Key Index, Concept Index, Top +@node Variable Index, Concept and Key Index, Command and Function Index, Top @comment node-name, next, previous, up -@unnumbered Command Index +@unnumbered Variable Index @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -Since most @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 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Key Index, Variable Index, Command Index, Top +@node Concept and Key Index, , Variable Index, Top @comment node-name, next, previous, up -@unnumbered Key Index +@unnumbered Concept and Key Index @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@printindex ky +@printindex cp @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Variable Index, , Key Index, Top -@comment node-name, next, previous, up -@unnumbered Variable Index +@comment Epilogue. @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -Since most @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