Mercurial > emacs
changeset 84132:add806db14ca
Move to ../doc/emacs/, misc/
| author | Glenn Morris <rgm@gnu.org> |
|---|---|
| date | Thu, 06 Sep 2007 04:34:23 +0000 |
| parents | 690b13c10f8e |
| children | 6d3e73fad987 |
| files | man/cc-mode.texi |
| diffstat | 1 files changed, 0 insertions(+), 6998 deletions(-) [+] |
line wrap: on
line diff
--- a/man/cc-mode.texi Thu Sep 06 04:34:18 2007 +0000 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,6998 +0,0 @@ -\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 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) -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@comment -@comment Texinfo manual for CC Mode -@comment Generated from the original README file by Krishna Padmasola -@comment <krishna@earth-gw.njit.edu> -@comment -@comment Authors: -@comment Barry A. Warsaw -@comment Martin Stjernholm -@comment Alan Mackenzie -@comment -@comment Maintained by Martin Stjernholm and Alan Mackenzie <bug-cc-mode@gnu.org> -@comment -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@comment Define an index for syntactic symbols. -@ifnottex @c In texi2dvi, the @defindex would create an empty cc-mode.ss - @c For Info, unlike tex, @syncodeindex needs a matching @defindex. -@defindex ss -@end ifnottex - -@comment 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, 2007 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: (ccmode). Emacs mode for editing C, C++, Objective-C, - Java, Pike, AWK, and CORBA IDL code. -@end direntry - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@comment TeX title page -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@titlepage -@sp 10 - -@center @titlefont{CC Mode 5.31} -@sp 2 -@center @subtitlefont{A GNU Emacs mode for editing C and C-like languages} -@sp 2 -@center Barry A. Warsaw, Martin Stjernholm, Alan Mackenzie - -@page -@vskip 0pt plus 1filll -@insertcopying - -This manual was generated from $Revision$ of $RCSfile$, which can be -downloaded from -@url{http://cvs.savannah.gnu.org/viewcvs/emacs/emacs/man/cc-mode.texi}. -@end titlepage - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@comment The Top node contains the master menu for the Info file. -@comment This appears only in the Info file, not the printed manual. -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@node Top, Introduction, (dir), (dir) -@comment node-name, next, previous, up - -@ifinfo -@top @ccmode{} - -@ccmode{} is a GNU Emacs mode for editing files containing C, C++, -Objective-C, Java, CORBA IDL (and the variants PSDL and CIDL), Pike -and AWK code. It provides syntax-based indentation, font locking, and -has several handy commands and some minor modes to make the editing -easier. It does not provide tools to look up and navigate between -functions, classes etc - there are other packages for that. -@end ifinfo - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@menu -* Introduction:: -* 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:: -* GNU Free Documentation License:: -* Command and Function Index:: -* Variable Index:: -* Concept and Key Index:: - -@detailmenu - --- The Detailed Node Listing --- - -Commands - -* Indentation Commands:: -* Comment Commands:: -* Movement Commands:: -* Filling and Breaking:: -* Minor Modes:: -* Electric Keys:: -* Auto-newlines:: -* Hungry WS Deletion:: -* Subword Movement:: -* Other Commands:: - -Font Locking - -* Font Locking Preliminaries:: -* Faces:: -* Doc Comments:: -* AWK Mode Font Locking:: - -Configuration Basics - -* CC Hooks:: -* Style Variables:: -* Styles:: - -Styles - -* Built-in Styles:: -* Choosing a Style:: -* Adding Styles:: -* File Styles:: - -Customizing Auto-newlines - -* Hanging Braces:: -* Hanging Colons:: -* Hanging Semicolons and Commas:: - -Hanging Braces - -* Custom Braces:: - -Indentation Engine Basics - -* Syntactic Analysis:: -* Syntactic Symbols:: -* Indentation Calculation:: - -Syntactic Symbols - -* Function Symbols:: -* Class Symbols:: -* Conditional Construct Symbols:: -* Switch Statement Symbols:: -* Brace List Symbols:: -* External Scope Symbols:: -* Paren List Symbols:: -* Literal Symbols:: -* Multiline Macro Symbols:: -* Objective-C Method Symbols:: -* Anonymous Class Symbol:: -* Statement Block Symbols:: -* K&R Symbols:: - -Customizing Indentation - -* c-offsets-alist:: -* Interactive Customization:: -* Line-Up Functions:: -* Custom Line-Up:: -* Other Indentation:: - -Line-Up Functions - -* Brace/Paren Line-Up:: -* List Line-Up:: -* Operator Line-Up:: -* Comment Line-Up:: -* Misc Line-Up:: - -@end detailmenu -@end menu - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Introduction, Overview, Top, Top -@comment node-name, next, previous, up -@chapter Introduction -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@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 the variants CORBA PSDL and -CIDL), Pike and AWK code. This incarnation of the mode is descended -from @file{c-mode.el} (also called ``Boring Old C Mode'' or BOCM -@t{:-)}, @file{c++-mode.el} version 2, which Barry Warsaw had been -maintaining since 1992, and @file{awk-mode.el}, a long neglected mode -in the (X)Emacs base. - -Late in 1997, Martin Stjernholm joined Barry on the @ccmode{} -Maintainers Team, and implemented the Pike support. In 2000 Martin -took over as the sole maintainer. In 2001 Alan Mackenzie joined the -team, implementing AWK support in version 5.30. @ccmode{} did not -originally contain the font lock support for its languages --- that -was added in version 5.30. - -This manual describes @ccmode{} -@comment The following line must appear on its own, so that the -version 5.31. -@comment Release.py script can update the version number automatically - -@ccmode{} supports the editing of K&R and ANSI C, C++, Objective-C, -Java, CORBA's Interface Definition Language, Pike@footnote{A C-like -scripting language with its roots in the LPC language used in some MUD -engines. See @uref{http://pike.ida.liu.se/}.} and AWK files. In this -way, you can easily set up consistent font locking and coding styles for -use in editing all of these languages, although AWK is not yet as -uniformly integrated as the other languages. - -@findex c-mode -@findex c++-mode -@findex objc-mode -@findex java-mode -@findex idl-mode -@findex pike-mode -@findex awk-mode -Note that the name of this package is ``@ccmode{}'', but there is no top -level @code{cc-mode} entry point. All of the variables, commands, and -functions in @ccmode{} are prefixed with @code{c-@var{thing}}, and -@code{c-mode}, @code{c++-mode}, @code{objc-mode}, @code{java-mode}, -@code{idl-mode}, @code{pike-mode}, and @code{awk-mode} entry points are -provided. This package is intended to be a replacement for -@file{c-mode.el}, @file{c++-mode.el} and @file{awk-mode.el}. - -A special word of thanks goes to Krishna Padmasola for his work in -converting the original @file{README} file to Texinfo format. I'd -also like to thank all the @ccmode{} victims who help enormously -during the early beta stages of @ccmode{}'s development. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Overview, Getting Started, Introduction, Top -@comment node-name, next, previous, up@cindex organization of the manual -@chapter Overview of the Manual -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@noindent -The manual starts with several introductory chapters (including this -one). - -@noindent -The next chunk of the manual describes the day to day @emph{use} of -@ccmode{} (as contrasted with how to customize it). - -@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. - -@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 - -@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. - -@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. - -@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 - -@noindent -The manual ends with ``this and that'', things that don't fit cleanly -into any of the previous chunks. - -@itemize @bullet -@item -Two chapters discuss the performance of @ccmode{} and known -bugs/limitations. - -@item -The FAQ contains a list of common problems and questions. - -@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 Getting Started, Commands, Overview, Top -@comment node-name, next, previous, up -@chapter Getting Started -@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 might not -have the latest @ccmode{} release and might want to upgrade your copy -(see below). - -You should probably start by skimming through the entire chapter -@ref{Commands} to get an overview of @ccmode{}'s capabilities. - -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: - -@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}: - -@example -(setq c-basic-offset 6) -@end example - -@item The (indentation) style -The basic ``shape'' of indentation created by @ccmode{}---by default, -this is @code{gnu} style (except for Java and AWK buffers). A list of -the available styles and their descriptions can be found in -@ref{Built-in Styles}. A complete specification of the @ccmode{} -style system, including how to create your own style, can be found in -the chapter @ref{Styles}. To set your style to @code{linux}, either -customize @code{c-default-style} or put this into your @file{.emacs}: - -@example -(setq c-default-style '((java-mode . "java") - (awk-mode . "awk") - (other . "linux"))) -@end example - -@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.}: - -@example -(setq-default c-electric-flag nil) -@end example - -@noindent -Details of this and other similar ``Minor Modes'' appear in the -section @ref{Minor Modes}. - -@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 would fail if the pertinent keymap didn't yet -exist---we thus need to delay the action until after @ccmode{} has -been loaded. Put the following code into your @file{.emacs}: - -@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 -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 - -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 -where @samp{XX} is the minor release number. -@end deffn - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Commands, Font Locking, Getting Started, Top -@comment node-name, next, previous, up -@chapter Commands -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -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. - -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. - - -@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 - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Indentation Commands, Comment Commands, Commands, Commands -@comment node-name, next, previous,up -@section Indentation Commands -@cindex indentation -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -The following commands reindent C constructs. Note that when you -change your coding style, either interactively or through some other -means, your file does @emph{not} automatically get reindented. You -will need to execute one of the following commands to see the effects -of your changes. - -@cindex GNU indent program -Also, variables like @code{c-hanging-*} and @code{c-cleanup-list} -(@pxref{Custom Auto-newlines}) only affect how on-the-fly code is -formatted. Changing the ``hanginess'' of a brace and then -reindenting, will not move the brace to a different line. For this, -you're better off getting an external program like GNU @code{indent}, -which will rearrange brace location, amongst other things. - -Preprocessor directives are handled as syntactic whitespace from other -code, i.e. they can be interspersed anywhere without affecting the -indentation of the surrounding code, just like comments. - -The code inside macro definitions is, by default, still analyzed -syntactically so that you get relative indentation there just as you'd -get if the same code was outside a macro. However, since there is no -hint about the syntactic context, i.e. whether the macro expands to an -expression, to some statements, or perhaps to whole functions, the -syntactic recognition can be wrong. @ccmode{} manages to figure it -out correctly most of the time, though. - -Reindenting large sections of code can take a long time. When -@ccmode{} reindents a region of code, it is essentially equivalent to -hitting @key{TAB} on every line of the region. - -These commands indent code: - -@table @asis -@item @kbd{@key{TAB}} (@code{c-indent-command}) -@kindex TAB -@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. - -@code{c-indent-command} does different things, depending on the -setting of @code{c-syntactic-indentation} (@pxref{Indentation Engine -Basics}): - -@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. - -@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 - -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{}}. - -@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 - -@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 - -@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 - -@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. - -@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. - -@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 - -These variables are also useful when indenting code: - -@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 Comment Commands, Movement Commands, Indentation Commands, Commands -@comment node-name, next, previous, up -@section Comment Commands -@cindex comments (insertion of) -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@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 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 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@ccmode{} contains some useful commands for moving around in C code. - -@table @asis -@item @kbd{C-M-a} (@code{c-beginning-of-defun}) -@itemx @kbd{C-M-e} (@code{c-end-of-defun}) -@findex c-beginning-of-defun -@findex c-end-of-defun - -Move to the beginning or end of the current or next function. Other -constructs (such as a structs or classes) which have a brace block -also count as ``functions'' here. To move over several functions, you -can give these commands a repeat count. - -The start of a function is at its header. The end of the function is -after its closing brace, or after the semicolon of a construct (such -as a @code{struct}) which doesn't end at the brace. These two -commands try to leave point at the beginning of a line near the actual -start or end of the function. This occasionally causes point not to -move at all. - -These functions are analogous to the Emacs built-in commands -@code{beginning-of-defun} and @code{end-of-defun}, except they -eliminate the constraint that the top-level opening brace of the defun -must be in column zero. See @ref{Defuns,,,@emacsman{}, -@emacsmantitle{}}, for more information. - -@item @kbd{C-M-a} (AWK Mode) (@code{c-awk-beginning-of-defun}) -@itemx @kbd{C-M-e} (AWK Mode) (@code{c-awk-end-of-defun}) -@kindex C-M-a (AWK Mode) -@kindex C-M-e (AWK Mode) -@findex c-awk-beginning-of-defun -@findex awk-beginning-of-defun (c-) -@findex c-awk-end-of-defun -@findex awk-end-of-defun (c-) -Move to the beginning or end of the current or next AWK defun. These -commands can take prefix-arguments, their functionality being entirely -equivalent to @code{beginning-of-defun} and @code{end-of-defun}. - -AWK Mode @dfn{defuns} are either pattern/action pairs (either of which -might be implicit) or user defined functions. Having the @samp{@{} and -@samp{@}} (if there are any) in column zero, as is suggested for some -modes, is neither necessary nor helpful in AWK mode. - -@item @kbd{M-a} (@code{c-beginning-of-statement}) -@itemx @kbd{M-e} (@code{c-end-of-statement}) -@kindex M-a -@kindex M-e -@findex c-beginning-of-statement -@findex c-end-of-statement -@findex beginning-of-statement (c-) -@findex end-of-statement (c-) -Move to the beginning or end of the innermost C statement. If point -is already there, move to the next beginning or end of a statement, -even if that means moving into a block. (Use @kbd{C-M-b} or -@kbd{C-M-f} to move over a balanced block.) A prefix argument @var{n} -means move over @var{n} statements. - -If point is within or next to a comment or a string which spans more -than one line, these commands move by sentences instead of statements. - -When called from a program, these functions take three optional -arguments: the repetition count, a buffer position limit which is the -farthest back to search for the syntactic context, and a flag saying -whether to do sentence motion in or near comments and multiline -strings. - -@item @kbd{C-c C-u} (@code{c-up-conditional}) -@kindex C-c C-u -@findex c-up-conditional -@findex up-conditional (c-) -Move back to the containing preprocessor conditional, leaving the mark -behind. A prefix argument acts as a repeat count. With a negative -argument, move forward to the end of the containing preprocessor -conditional. - -@samp{#elif} is treated like @samp{#else} followed by @samp{#if}, so the -function stops at them when going backward, but not when going -forward. - -This key sequence is not bound in AWK Mode, which doesn't have -preprocessor statements. - -@item @kbd{M-x c-up-conditional-with-else} -@findex c-up-conditional-with-else -@findex up-conditional-with-else (c-) -A variety of @code{c-up-conditional} that also stops at @samp{#else} -lines. Normally those lines are ignored. - -@item @kbd{M-x c-down-conditional} -@findex c-down-conditional -@findex down-conditional (c-) -Move forward into the next nested preprocessor conditional, leaving -the mark behind. A prefix argument acts as a repeat count. With a -negative argument, move backward into the previous nested preprocessor -conditional. - -@samp{#elif} is treated like @samp{#else} followed by @samp{#if}, so the -function stops at them when going forward, but not when going backward. - -@item @kbd{M-x c-down-conditional-with-else} -@findex c-down-conditional-with-else -@findex down-conditional-with-else (c-) -A variety of @code{c-down-conditional} that also stops at @samp{#else} -lines. Normally those lines are ignored. - -@item @kbd{C-c C-p} (@code{c-backward-conditional}) -@itemx @kbd{C-c C-n} (@code{c-forward-conditional}) -@kindex C-c C-p -@kindex C-c C-n -@findex c-backward-conditional -@findex c-forward-conditional -@findex backward-conditional (c-) -@findex forward-conditional (c-) -Move backward or forward across a preprocessor conditional, leaving -the mark behind. A prefix argument acts as a repeat count. With a -negative argument, move in the opposite direction. - -These key sequences are not bound in AWK Mode, which doesn't have -preprocessor statements. - -@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}. - -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. - -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 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -Since there's a lot of normal text in comments and string literals, -@ccmode{} provides features to edit these like in text mode. The goal -is to do it seamlessly, i.e. you can use auto fill mode, sentence and -paragraph movement, paragraph filling, adaptive filling etc. wherever -there's a piece of normal text without having to think much about it. -@ccmode{} keeps the indentation, fixes suitable comment line prefixes, -and so on. - -You can configure the exact way comments get filled and broken, and -where Emacs does auto-filling (see @pxref{Custom Filling and -Breaking}). Typically, the style system (@pxref{Styles}) will have -set this up for you, so you probably won't have to bother. - -@findex auto-fill-mode -@cindex Auto Fill mode -@cindex paragraph filling -Line breaks are by default handled (almost) the same regardless of -whether they are made by auto fill mode (@pxref{Auto Fill,,, -@emacsman{}, @emacsmantitle{}}), by paragraph filling (e.g. with -@kbd{M-q}), or explicitly with @kbd{M-j} or similar methods. In -string literals, the new line gets the same indentation as the -previous nonempty line.@footnote{You can change this default by -setting the @code{string} syntactic symbol (@pxref{Syntactic Symbols} -and @pxref{Customizing Indentation})}. - -@table @asis -@item @kbd{M-q} (@code{c-fill-paragraph}) -@kindex M-q -@findex c-fill-paragraph -@findex fill-paragraph (c-) -@cindex Javadoc markup -@cindex Pike autodoc markup -This command fills multiline string literals and both block -and line style comments. In Java buffers, the Javadoc markup words -are recognized as paragraph starters. The line oriented Pike autodoc -markup words are recognized in the same way in Pike mode. - -The formatting of the starters (@code{/*}) and enders (@code{*/}) of -block comments are kept as they were before the filling. I.e., if -either the starter or ender were on a line of its own, then it stays -on its own line; conversely, if the delimiter has comment text on its -line, it keeps at least one word of that text with it on the line. - -This command is the replacement for @code{fill-paragraph} in @ccmode{} -buffers. - -@item @kbd{M-j} (@code{c-indent-new-comment-line}) -@kindex M-j -@findex c-indent-new-comment-line -@findex indent-new-comment-line (c-) -This breaks the current line at point and indents the new line. If -point was in a comment, the new line gets the proper comment line -prefix. If point was inside a macro, a backslash is inserted before -the line break. It is the replacement for -@code{indent-new-comment-line}. - -@item @kbd{M-x c-context-line-break} -@findex c-context-line-break -@findex context-line-break (c-) -Insert a line break suitable to the context: If the point is inside a -comment, the new line gets the suitable indentation and comment line -prefix like @code{c-indent-new-comment-line}. In normal code it's -indented like @code{newline-and-indent} would do. In macros it acts -like @code{newline-and-indent} but additionally inserts and optionally -aligns the line ending backslash so that the macro remains unbroken. -@xref{Custom Macros}, for details about the backslash alignment. In a -string, a backslash is inserted only if the string is within a -macro@footnote{In GCC, unescaped line breaks within strings are -valid.}. - -This function is not bound to a key by default, but it's intended to be -used on the @kbd{RET} key. If you like the behavior of -@code{newline-and-indent} on @kbd{RET}, you should consider switching to -this function. @xref{Sample .emacs File}. - -@item @kbd{M-x c-context-open-line} -@findex c-context-open-line -@findex context-open-line (c-) -This is to @kbd{C-o} (@kbd{M-x open-line}) as -@code{c-context-line-break} is to @kbd{RET}. I.e. it works just like -@code{c-context-line-break} but leaves the point before the inserted -line break. -@end table - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Minor Modes, Electric Keys, Filling and Breaking, Commands -@comment node-name, next, previous, up -@section Minor Modes -@cindex Minor Modes -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@ccmode{} contains several minor-mode-like features that you might -find useful while writing new code or editing old code: - -@table @asis -@item electric mode -When this is enabled, certain visible characters cause reformatting as -they are typed. This is normally helpful, but can be a nuisance when -editing chaotically formatted code. It can also be disconcerting, -especially for users who are new to @ccmode{}. -@item auto-newline mode -This automatically inserts newlines where you'd probably want to type -them yourself, e.g. after typing @samp{@}}s. Its action is suppressed -when electric mode is disabled. -@item hungry-delete mode -This lets you delete a contiguous block of whitespace with a single -key - for example, the newline and indentation just inserted by -auto-newline when you want to back up and write a comment after the -last statement. -@item subword mode -This mode makes basic word movement commands like @kbd{M-f} -(@code{forward-word}) and @kbd{M-b} (@code{backward-word}) treat the -parts of sillycapsed symbols as different words. -E.g. @samp{NSGraphicsContext} is treated as three words @samp{NS}, -@samp{Graphics}, and @samp{Context}. -@item syntactic-indentation mode -When this is enabled (which it normally is), indentation commands such -as @kbd{C-j} indent lines of code according to their syntactic -structure. Otherwise, a line is simply indented to the same level as -the previous one and @kbd{@key{TAB}} adjusts the indentation in steps -of `c-basic-offset'. -@end table - -Full details on how these minor modes work are at @ref{Electric Keys}, -@ref{Auto-newlines}, @ref{Hungry WS Deletion}, @ref{Subword Movement}, -and @ref{Indentation Engine Basics}. - -You can toggle each of these minor modes on and off, and you can -configure @ccmode{} so that it starts up with your favourite -combination of them (@pxref{Sample .emacs File}). By default, when -you initialize a buffer, electric mode and syntactic-indentation mode -are enabled but the other two modes are disabled. - -@ccmode{} displays the current state of the first four of these minor -modes on the modeline by appending letters to the major mode's name, -one letter for each enabled minor mode - @samp{l} for electric mode, -@samp{a} for auto-newline mode, @samp{h} for hungry delete mode, and -@samp{w} for subword mode. If all these modes were enabled, you'd see -@samp{C/lahw}@footnote{The @samp{C} would be replaced with the name of -the language in question for the other languages @ccmode{} supports.}. - -Here are the commands to toggle these modes: - -@table @asis -@item @kbd{C-c C-l} (@code{c-toggle-electric-state}) -@kindex C-c C-l -@findex c-toggle-electric-state -@findex toggle-electric-state (c-) -Toggle electric minor mode. When the command turns the mode off, it -also suppresses auto-newline mode. - -@item @kbd{C-c C-a} (@code{c-toggle-auto-newline}) -@kindex C-c C-a -@findex c-toggle-auto-newline -@findex toggle-auto-newline (c-) -Toggle auto-newline minor mode. When the command turns the mode on, -it also enables electric minor mode. - -@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 - -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 Electric Keys, Auto-newlines, Minor Modes, Commands -@comment node-name, next, previous, up -@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 -@findex electric-pound (c-) -@vindex c-electric-pound-behavior -@vindex electric-pound-behavior (c-) -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 electric-star (c-) -@findex c-electric-slash -@findex electric-slash (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 > -@findex c-electric-lt-gt -@findex electric-lt-gt (c-) -A less-than or greater-than sign (bound to @code{c-electric-lt-gt}) is -electric in two circumstances: when it is an angle bracket in a C++ -@samp{template} declaration (and similar constructs in other -languages) and when it is the second of two @kbd{<} or @kbd{>} -characters in a C++ style stream operator. In either case, the line -is reindented. Angle brackets in C @samp{#include} directives are not -electric. - -@item ( -@kindex ( -@itemx ) -@kindex ) -@findex c-electric-paren -@findex electric-paren (c-) -The normal parenthesis characters @samp{(} and @samp{)} (bound to -@code{c-electric-paren}) reindent the current line. This is useful -for getting the closing parenthesis of an argument list aligned -automatically. - -You can also configure @ccmode{} to insert a space automatically -between a function name and the @samp{(} you've just typed, and to -remove it automatically after typing @samp{)}, should the argument -list be empty. You don't need to have electric minor mode enabled to -get these actions. @xref{Clean-ups}. - -@item @{ -@kindex @{ -@itemx @} -@kindex @} -@findex c-electric-brace -@findex electric-brace (c-) -Typing a brace (bound to @code{c-electric-brace}) reindents the -current line. Also, one or more newlines might be inserted if -auto-newline minor mode is enabled. @xref{Auto-newlines}. -Additionally, you can configure @ccmode{} to compact excess whitespace -inserted by auto-newline mode in certain circumstances. -@xref{Clean-ups}. - -@item : -@kindex : -@findex c-electric-colon -@findex electric-colon (c-) -Typing a colon (bound to @code{c-electric-colon}) reindents the -current line. Additionally, one or more newlines might be inserted if -auto-newline minor mode is enabled. @xref{Auto-newlines}. If you -type a second colon immediately after such an auto-newline, by default -the whitespace between the two colons is removed, leaving a C++ scope -operator. @xref{Clean-ups}. - -If you prefer, you can insert @samp{::} in a single operation, -avoiding all these spurious reindentations, newlines, and clean-ups. -@xref{Other Commands}. - -@item ; -@kindex ; -@itemx , -@kindex , -@findex c-electric-semi&comma -@findex electric-semi&comma (c-) -Typing a semicolon or comma (bound to @code{c-electric-semi&comma}) -reindents the current line. Also, a newline might be inserted if -auto-newline minor mode is enabled. @xref{Auto-newlines}. -Additionally, you can configure @ccmode{} so that when auto-newline -has inserted whitespace after a @samp{@}}, it will be removed again -when you type a semicolon or comma just after it. @xref{Clean-ups}. - -@end table - -@deffn Command c-electric-continued-statement -@findex electric-continued-statement (c-) - -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). - -An example: - -@example -@group -for (i = 0; i < 17; i++) - if (a[i]) - res += a[i]->offset; -else -@end group -@end example - -Here, the @code{else} should be indented like the preceding @code{if}, -since it continues that statement. @ccmode{} will automatically -reindent it after the @code{else} has been typed in full, since only -then is it possible to decide whether it's a new statement or a -continuation of the preceding @code{if}. - -@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 - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Auto-newlines, Hungry WS Deletion, Electric Keys, Commands -@comment node-name, next, previous, up -@section Auto-newline Insertion -@cindex auto-newline -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -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. - -Auto-newline only triggers when the following conditions hold: - -@itemize @bullet -@item -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 -The character was typed at the end of a line, or with only whitespace -after it, and possibly a @samp{\} escaping the newline. - -@item -The character is not on its own line already. (This applies only to -insertion of a newline @emph{before} the character.) - -@item -@cindex literal -@cindex syntactic whitespace -The character was not typed inside of a literal @footnote{A -@dfn{literal} is defined as any comment, string, or preprocessor macro -definition. These constructs are also known as @dfn{syntactic -whitespace} since they are usually ignored when scanning C code.}. - -@item -No numeric argument was supplied to the command (i.e. it was typed as -normal, with no @kbd{C-u} prefix). -@end itemize - -You can configure the precise circumstances in which newlines get -inserted (see @pxref{Custom Auto-newlines}). Typically, the style -system (@pxref{Styles}) will have set this up for you, so you probably -won't have to bother. - -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 WS Deletion, Subword Movement, Auto-newlines, Commands -@comment node-name, next, previous, up -@section Hungry Deletion of Whitespace -@cindex hungry-deletion -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -If you want to delete an entire block of whitespace at point, you can -use @dfn{hungry deletion}. This deletes all the contiguous whitespace -either before point or after point in a single operation. -``Whitespace'' here includes tabs and newlines, but not comments or -preprocessor commands. Hungry deletion can markedly cut down on the -number of times you have to hit deletion keys when, for example, -you've made a mistake on the preceding line and have already pressed -@kbd{C-j}. - -Hungry deletion is a simple feature that some people find extremely -useful. In fact, you might find yourself wanting it in @strong{all} -your editing modes! - -Loosely speaking, in what follows, @dfn{@key{DEL}} means ``the -backspace key'' and @dfn{@key{DELETE}} means ``the forward delete -key''. This is discussed in more detail below. - -There are two different ways you can use hungry deletion: - -@table @asis -@item Using @dfn{Hungry Delete Mode} with @kbd{@key{DEL}} and @kbd{C-d} -Here you toggle Hungry Delete minor mode with @kbd{M-x -c-toggle-hungry-state}@footnote{Prior to @ccmode{} 5.31, this command -was bound to @kbd{C-c C-d}. @kbd{C-c C-d} is now the default binding -for @code{c-hungry-delete-forward}.} (@pxref{Minor Modes}.) This -makes @kbd{@key{DEL}} and @kbd{C-d} do backwards and forward hungry -deletion. - -@table @asis -@item @kbd{@key{DEL}} (@code{c-electric-backspace}) -@kindex DEL -@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 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-) -@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 - -@item Using Distinct Bindings -The other (newer and recommended) way to use hungry deletion is to -perform @code{c-hungry-delete-backwards} and -@code{c-hungry-delete-forward} directly through their key sequences -rather than using the minor mode toggling. - -@table @asis -@item @kbd{C-c C-@key{DEL}}, or @kbd{C-c @key{DEL}} (@code{c-hungry-delete-backwards})@footnote{This command was formerly known as @code{c-hungry-backspace}.} -@kindex C-c C-<backspace> -@kindex C-c <backspace> -@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-<DELETE> -@kindex C-c <DELETE> -@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 - -@kindex <delete> -@kindex <backspace> - -When we talk about @kbd{@key{DEL}}, and @kbd{@key{DELETE}} above, we -actually do so without connecting them to the physical keys commonly -known as @key{Backspace} and @key{Delete}. The default bindings to -those two keys depends on the flavor of (X)Emacs you are using. - -@findex c-electric-delete -@findex electric-delete (c-) -@findex c-hungry-delete -@findex hungry-delete (c-) -@vindex delete-key-deletes-forward -In XEmacs 20.3 and beyond, the @key{Backspace} key is bound to -@code{c-electric-backspace} and the @key{Delete} key is bound to -@code{c-electric-delete}. You control the direction it deletes in by -setting the variable @code{delete-key-deletes-forward}, a standard -XEmacs variable. -@c This variable is encapsulated by XEmacs's (defsubst delete-forward-p ...). -When this variable is non-@code{nil}, @code{c-electric-delete} will do -forward deletion with @code{c-electric-delete-forward}, otherwise it -does backward deletion with @code{c-electric-backspace}. Similarly, -@kbd{C-c @key{Delete}} and @kbd{C-c C-@key{Delete}} are bound to -@code{c-hungry-delete} which is controlled in the same way by -@code{delete-key-deletes-forward}. - -@findex normal-erase-is-backspace-mode - -Emacs 21 and later automatically binds @key{Backspace} and -@key{Delete} to @kbd{DEL} and @kbd{C-d} according to your environment, -and @ccmode{} extends those bindings to @kbd{C-c C-@key{Backspace}} -etc. If you need to change the bindings through -@code{normal-erase-is-backspace-mode} then @ccmode{} will also adapt -its extended bindings accordingly. - -In earlier (X)Emacs versions, @ccmode{} doesn't bind either -@key{Backspace} or @key{Delete} directly. Only the key codes -@kbd{DEL} and @kbd{C-d} are bound, and it's up to the default bindings -to map the physical keys to them. You might need to modify this -yourself if the defaults are unsuitable. - -Getting your @key{Backspace} and @key{Delete} keys properly set up can -sometimes be tricky. The information in @ref{DEL Does Not -Delete,,,emacs, GNU Emacs Manual}, might be helpful if you're having -trouble with this in GNU Emacs. - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Subword Movement, Other Commands, Hungry WS Deletion, Commands -@comment node-name, next, previous, up -@section Subword Movement and Editing -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@cindex nomenclature -@cindex subword -In spite of the GNU Coding Standards, it is popular to name a symbol -by mixing uppercase and lowercase letters, e.g. @samp{GtkWidget}, -@samp{EmacsFrameClass}, or @samp{NSGraphicsContext}. Here we call -these mixed case symbols @dfn{nomenclatures}. Also, each capitalized -(or completely uppercase) part of a nomenclature is called a -@dfn{subword}. Here are some examples: - -@multitable {@samp{NSGraphicsContext}} {@samp{NS}, @samp{Graphics}, and @samp{Context}} -@c This could be converted to @headitem when we require Texinfo 4.7 -@iftex -@item @b{Nomenclature} - @tab @b{Subwords} -@end iftex -@ifnottex -@item Nomenclature - @tab Subwords -@item --------------------------------------------------------- -@end ifnottex -@item @samp{GtkWindow} - @tab @samp{Gtk} and @samp{Window} -@item @samp{EmacsFrameClass} - @tab @samp{Emacs}, @samp{Frame}, and @samp{Class} -@item @samp{NSGraphicsContext} - @tab @samp{NS}, @samp{Graphics}, and @samp{Context} -@end multitable - -The subword minor mode replaces the basic word oriented movement and -editing commands with variants that recognize subwords in a -nomenclature and treat them as separate words: - -@findex c-forward-subword -@findex forward-subword (c-) -@findex c-backward-subword -@findex backward-subword (c-) -@findex c-mark-subword -@findex mark-subword (c-) -@findex c-kill-subword -@findex kill-subword (c-) -@findex c-backward-kill-subword -@findex backward-kill-subword (c-) -@findex c-transpose-subwords -@findex transpose-subwords (c-) -@findex c-capitalize-subword -@findex capitalize-subword (c-) -@findex c-upcase-subword -@findex upcase-subword (c-) -@findex c-downcase-subword -@findex downcase-subword (c-) -@multitable @columnfractions .20 .40 .40 -@c This could be converted to @headitem when we require Texinfo 4.7 -@iftex -@item @b{Key} @tab @b{Word oriented command} @tab @b{Subword oriented command} -@end iftex -@ifnottex -@item Key @tab Word oriented command @tab Subword oriented command -@item ---------------------------------------------------------------------------- -@end ifnottex -@item @kbd{M-f} @tab @code{forward-word} @tab @code{c-forward-subword} -@item @kbd{M-b} @tab @code{backward-word} @tab @code{c-backward-subword} -@item @kbd{M-@@} @tab @code{mark-word} @tab @code{c-mark-subword} -@item @kbd{M-d} @tab @code{kill-word} @tab @code{c-kill-subword} -@item @kbd{M-DEL} @tab @code{backward-kill-word} @tab @code{c-backward-kill-subword} -@item @kbd{M-t} @tab @code{transpose-words} @tab @code{c-transpose-subwords} -@item @kbd{M-c} @tab @code{capitalize-word} @tab @code{c-capitalize-subword} -@item @kbd{M-u} @tab @code{upcase-word} @tab @code{c-upcase-subword} -@item @kbd{M-l} @tab @code{downcase-word} @tab @code{c-downcase-subword} -@end multitable - -Note that if you have changed the key bindings for the word oriented -commands in your @file{.emacs} or a similar place, the keys you have -configured are also used for the corresponding subword oriented -commands. - -Type @kbd{C-c C-w} to toggle subword mode on and off. To make the -mode turn on automatically, put the following code in your -@file{.emacs}: - -@example -(add-hook 'c-mode-common-hook - (lambda () (c-subword-mode 1))) -@end example - -As a bonus, you can also use @code{c-subword-mode} in non-@ccmode{} -buffers by typing @kbd{M-x c-subword-mode}. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Other Commands, , Subword Movement, Commands -@comment node-name, next, previous, up -@section Other Commands -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -Here are the various other commands that didn't fit anywhere else: - -@table @asis -@item @kbd{C-c .} (@code{c-set-style}) -@kindex C-c . -@findex c-set-style -@findex set-style (c-) -Switch to the specified style in the current buffer. Use like this: - -@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}. - -For details of the @ccmode{} style system, see @ref{Styles}. -@item @kbd{C-c :} (@code{c-scope-operator}) -@kindex C-c : -@findex c-scope-operator -@findex scope-operator (c-) -In C++, it is also sometimes desirable to insert the double-colon scope -operator without performing the electric behavior of colon insertion. -@kbd{C-c :} does just this. - -@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. - -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. - -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. - -To customize the precise workings of this command, @ref{Custom Macros}. -@end table - -@noindent -The recommended line breaking function, @code{c-context-line-break} -(@pxref{Filling and Breaking}), is especially nice if you edit -multiline macros frequently. When used inside a macro, it -automatically inserts and adjusts the mandatory backslash at the end -of the line to keep the macro together, and it leaves the point at the -right indentation column for the code. Thus you can write code inside -macros almost exactly as you can elsewhere, without having to bother -with the trailing backslashes. - -@table @asis -@item @kbd{C-c C-e} (@code{c-macro-expand}) -@kindex C-c C-e -@findex c-macro-expand -@findex macro-expand (c-) -This command expands C, C++, Objective C or Pike macros in the region, -using an appropriate external preprocessor program. Normally it -displays its output in a temporary buffer, but if you give it a prefix -arg (with @kbd{C-u C-c C-e}) it will overwrite the original region -with the expansion. - -The command does not work in any of the other modes, and the key -sequence is not bound in these other modes. - -@code{c-macro-expand} isn't actually part of @ccmode{}, even though it -is bound to a @ccmode{} key sequence. If you need help setting it up -or have other problems with it, you can either read its source code or -ask for help in the standard (X)Emacs forums. -@end table - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Font Locking, Config Basics, Commands, Top -@comment node-name, next, previous, up -@chapter Font Locking -@cindex font locking -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@cindex Font Lock mode - -@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. - -@strong{Please note:} The font locking in AWK mode is currently not -integrated with the rest of @ccmode{}. Only the last section of this -chapter, @ref{AWK Mode Font Locking}, applies to AWK. The other -sections apply to the other languages. - -@menu -* Font Locking Preliminaries:: -* Faces:: -* Doc Comments:: -* AWK Mode Font Locking:: -@end menu - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Font Locking Preliminaries, Faces, Font Locking, Font Locking -@comment node-name, next, previous, up -@section Font Locking Preliminaries -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -The font locking for most of the @ccmode{} languages were provided -directly by the Font Lock package prior to version 5.30 of @ccmode{}. -In the transition to @ccmode{} the patterns have been reworked -completely and are applied uniformly across all the languages except AWK -mode, just like the indentation rules (although each language still has -some peculiarities of its own, of course). Since the languages -previously had completely separate font locking patterns, this means -that it's a bit different in most languages now. - -The main goal for the font locking in @ccmode{} is accuracy, to provide -a dependable aid in recognizing the various constructs. Some, like -strings and comments, are easy to recognize while others, like -declarations and types, can be very tricky. @ccmode{} can go to great -lengths to recognize declarations and casts correctly, especially when -the types aren't recognized by standard patterns. This is a fairly -demanding analysis which can be slow on older hardware, and it can -therefore be disabled by choosing a lower decoration level with the -variable @code{font-lock-maximum-decoration} (@pxref{Font Lock,,, -emacs, GNU Emacs Manual}). - -@vindex font-lock-maximum-decoration - -The decoration levels are used as follows: - -@enumerate -@comment 1 -@item -Minimal font locking: Fontify only comments, strings and preprocessor -directives (in the languages that use cpp). - -@comment 2 -@item -Fast font locking: In addition to level 1, fontify keywords, simple -types and declarations that are easy to recognize. The variables -@code{*-font-lock-extra-types} (where @samp{*} is the name of the -language) are used to recognize types (see below). Documentation -comments like Javadoc are fontified according to -@code{c-doc-comment-style} (@pxref{Doc Comments}). - -Use this if you think the font locking is too slow. It's the closest -corresponding level to level 3 in the old font lock patterns. - -@comment 3 -@item -Accurate font locking: Like level 2 but uses a different approach that -can recognize types and declarations much more accurately. The -@code{*-font-lock-extra-types} variables are still used, but user -defined types are recognized correctly anyway in most cases. Therefore -those variables should be fairly restrictive and not contain patterns -that are uncertain. - -@cindex Lazy Lock mode -@cindex Just-in-time Lock mode - -This level is designed for fairly modern hardware and a font lock -support mode like Lazy Lock or Just-in-time Lock mode that only -fontifies the parts that are actually shown. Fontifying the whole -buffer at once can easily get bothersomely slow even on contemporary -hardware. @xref{Font Lock,,,@emacsman{}, @emacsmantitle{}}. -@end enumerate - -@cindex user defined types -@cindex types, user defined - -Since user defined types are hard to recognize you can provide -additional regexps to match those you use: - -@defopt c-font-lock-extra-types -@defoptx c++-font-lock-extra-types -@defoptx objc-font-lock-extra-types -@defoptx java-font-lock-extra-types -@defoptx idl-font-lock-extra-types -@defoptx pike-font-lock-extra-types -For each language there's a variable @code{*-font-lock-extra-types}, -where @samp{*} stands for the language in question. It contains a list -of regexps that matches identifiers that should be recognized as types, -e.g. @samp{\\sw+_t} to recognize all identifiers ending with @samp{_t} -as is customary in C code. Each regexp should not match more than a -single identifier. - -The default values contain regexps for many types in standard runtime -libraries that are otherwise difficult to recognize, and patterns for -standard type naming conventions like the @samp{_t} suffix in C and C++. -Java, Objective-C and Pike have as a convention to start class names -with capitals, so there are patterns for that in those languages. - -Despite the names of these variables, they are not only used for -fontification but in other places as well where @ccmode{} needs to -recognize types. -@end defopt - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Faces, Doc Comments, Font Locking Preliminaries, Font Locking -@comment node-name, next, previous, up -@section Faces -@cindex faces -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@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}. - -@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. - -@item -@vindex font-lock-string-face -String and character literals are fontified in -@code{font-lock-string-face}. - -@item -@vindex font-lock-keyword-face -Keywords are fontified with @code{font-lock-keyword-face}. - -@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. - -@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. - -@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. - -@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. - -@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. - -@item -Name qualifiers and identifiers for scope constructs are fontified like -labels. - -@item -Special markup inside documentation comments are also fontified like -labels. - -@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. - -@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 Doc Comments, AWK Mode Font Locking, Faces, Font Locking -@comment node-name, next, previous, up -@section Documentation Comments -@cindex documentation comments -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -There are various tools to supply documentation in the source as -specially structured comments, e.g. the standard Javadoc tool in Java. -@ccmode{} provides an extensible mechanism to fontify such comments and -the special markup inside them. - -@defopt c-doc-comment-style -@vindex doc-comment-style (c-) -This is a style variable that specifies which documentation comment -style to recognize, e.g. @code{javadoc} for Javadoc comments. - -The value may also be a list of styles, in which case all of them are -recognized simultaneously (presumably with markup cues that don't -conflict). - -The value may also be an association list to specify different comment -styles for different languages. The symbol for the major mode is then -looked up in the alist, and the value of that element is interpreted as -above if found. If it isn't found then the symbol `other' is looked up -and its value is used instead. - -The default value for @code{c-doc-comment-style} is -@w{@code{((java-mode . javadoc) (pike-mode . autodoc) (c-mode . gtkdoc))}}. - -Note that @ccmode{} uses this variable to set other variables that -handle fontification etc. That's done at mode initialization or when -you switch to a style which sets this variable. Thus, if you change it -in some other way, e.g. interactively in a CC Mode buffer, you will need -to do @kbd{M-x java-mode} (or whatever mode you're currently using) to -reinitialize. - -@findex c-setup-doc-comment-style -@findex setup-doc-comment-style (c-) -Note also that when @ccmode{} starts up, the other variables are -modified before the mode hooks are run. If you change this variable in -a mode hook, you'll have to call @code{c-setup-doc-comment-style} -afterwards to redo that work. -@end defopt - -@ccmode{} currently provides handing of the following doc comment -styles: - -@table @code -@item javadoc -@cindex Javadoc markup -Javadoc comments, the standard tool in Java. - -@item autodoc -@cindex Pike autodoc markup -For Pike autodoc markup, the standard in Pike. - -@item gtkdoc -@cindex GtkDoc markup -For GtkDoc markup, widely used in the Gnome community. -@end table - -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}). - -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}. - -If you add support for another doc comment style, please consider -contributing it - send a note to @email{bug-cc-mode@@gnu.org}. - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node AWK Mode Font Locking, , Doc Comments, Font Locking -@comment node-name, next, previous, up -@section AWK Mode Font Locking -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -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}. - -The following faces are, however, used in a non-standard fashion in -AWK mode: - -@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: - -@itemize @bullet -@item -An unterminated string or regular expression. Here the opening -delimiter (@samp{"} or @samp{/} or @samp{_"}) is displayed in -@code{font-lock-warning-face}. This is most noticeable when typing in a -new string/regular expression into a buffer, when the warning-face -serves as a continual reminder to terminate the construct. - -AWK mode fontifies unterminated strings/regular expressions -differently from other modes: Only the text up to the end of the line -is fontified as a string (escaped newlines being handled correctly), -rather than the text up to the next string quote. - -@item -A space between the function name and opening parenthesis when calling -a user function. The last character of the function name and the -opening parenthesis are highlighted. This font-locking rule will -spuriously highlight a valid concatenation expression where an -identifier precedes a parenthesised expression. Unfortunately. - -@item -Whitespace following the @samp{\} in what otherwise looks like an -escaped newline. The @samp{\} is highlighted. -@end itemize -@end table - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Config Basics, Custom Filling and Breaking, Font Locking, Top -@comment node-name, next, previous, up -@chapter Configuration Basics -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@cindex Emacs Initialization File -@cindex Configuration -You configure @ccmode{} by setting Lisp variables and calling (and -perhaps writing) Lisp functions@footnote{DON'T PANIC!!! This isn't -difficult.}, which is usually done by adding code to an Emacs -initialization file. This file might be @file{site-start.el} or -@file{.emacs} or @file{init.el} or @file{default.el} or perhaps some -other file. @xref{Init File,,,@emacsman{}, @emacsmantitle{}}. For -the sake of conciseness, we just call this file ``your @file{.emacs}'' -throughout the rest of the manual. - -Several of these variables (currently 16), are known collectively as -@dfn{style variables}. @ccmode{} provides a special mechanism, known -as @dfn{styles} to make it easier to set these variables as a group, -to ``inherit'' settings from one style into another, and so on. Style -variables remain ordinary Lisp variables, whose values can be read and -changed independently of the style system. @xref{Style Variables}. - -There are several ways you can write the code, depending on the -precise effect you want---they are described further down on this page. -If you are new to @ccmode{}, we suggest you begin with the simplest -method, ``Top-level commands or the customization interface''. - -If you make conflicting settings in several of these ways, the way -that takes precedence is the one that appears latest in this list: -@itemize @asis -@item -@table @asis -@item Style -@itemx Top-level command or ``customization interface'' -@itemx Hook -@itemx File Style -@end table -@end itemize - -Here is a summary of the different ways of writing your configuration -settings: - -@table @asis -@item Top-level commands or the ``customization interface'' -Most simply, you can write @code{setq} and similar commands at the top -level of your @file{.emacs} file. When you load a @ccmode{} buffer, -it initializes its configuration from these global values (at least, -for those settings you have given values to), so it makes sense to -have these @code{setq} commands run @emph{before} @ccmode{} is first -initialized---in particular, before any call to @code{desktop-read} -(@pxref{Saving Emacs Sessions,,, emacs, GNU Emacs Manual}). For -example, you might set c-basic-offset thus: - -@example -(setq c-basic-offset 4) -@end example - -You can use the more user friendly Customization interface instead, -but this manual does not cover in detail how that works. To do this, -start by typing @kbd{M-x customize-group @key{RET} c @key{RET}}. -@xref{Easy Customization,,,@emacsman{}, @emacsmantitle{}}. -@c The following note really belongs in the Emacs manual. -Emacs normally writes the customizations at the end of your -@file{.emacs} file. If you use @code{desktop-read}, you should edit -your @file{.emacs} to place the call to @code{desktop-read} @emph{after} -the customizations. - -The first initialization of @ccmode{} puts a snapshot of the -configuration settings into the special style @code{user}. -@xref{Built-in Styles}. - -For basic use of Emacs, either of these ways of configuring is -adequate. However, the settings are then the same in all @ccmode{} -buffers and it can be clumsy to communicate them between programmers. -For more flexibility, you'll want to use one (or both) of @ccmode{}'s -more sophisticated facilities, hooks and styles. - -@item Hooks -An Emacs @dfn{hook} is a place to put Lisp functions that you want -Emacs to execute later in specific circumstances. -@xref{Hooks,,,@lispref{}, @lispreftitle{}}. @ccmode{} supplies a main -hook and a language-specific hook for each language it supports - any -functions you put onto these hooks get executed as the last part of a -buffer's initialization. Typically you put most of your customization -within the main hook, and use the language-specific hooks to vary the -customization settings between language modes. For example, if you -wanted different (non-standard) values of @code{c-basic-offset} in C -Mode and Java Mode buffers, you could do it like this: - -@example -@group -(defun my-c-mode-hook () - (setq c-basic-offset 3)) -(add-hook 'c-mode-hook 'my-c-mode-hook) - -(defun my-java-mode-hook () - (setq c-basic-offset 6)) -(add-hook 'java-mode-hook 'my-java-mode-hook) -@end group -@end example - -See @ref{CC Hooks} for more details on the use of @ccmode{} hooks. - -@item Styles -A @ccmode{} @dfn{style} is a coherent collection of customizations -with a name. At any time, exactly one style is active in each -@ccmode{} buffer, either the one you have selected or a default. -@ccmode{} is delivered with several existing styles. Additionally, -you can create your own styles, possibly based on these existing -styles. If you worked in a programming team called the ``Free -Group'', which had its own coding standards, you might well have this -in your @file{.emacs} file: - -@example -(setq c-default-style '((java-mode . "java") - (awk-mode . "awk") - (other . "free-group-style"))) -@end example - -See @ref{Styles} for fuller details on using @ccmode{} styles and how -to create them. - -@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}: - -@example -@group -(defun my-c-mode-hook () - (c-set-style - (if (and (buffer-file-name) - (string-match "/usr/src/linux" (buffer-file-name))) - "linux" - "free-group-style"))) -(add-hook 'c-mode-hook 'my-c-mode-hook) -@end group -@end example - -In a programming team, a hook is a also a good place for each member -to put his own personal preferences. For example, you might be the -only person in your team who likes Auto-newline minor mode. You could -have it enabled by default by placing the following in your -@file{.emacs}: - -@example -@group -(defun my-turn-on-auto-newline () - (c-toggle-auto-newline 1)) -(add-hook 'c-mode-common-hook 'my-turn-on-auto-newline) -@end group -@end example -@end table - -@menu -* CC Hooks:: -* Style Variables:: -* Styles:: -@end menu - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node CC Hooks, Style Variables, Config Basics, Config Basics -@comment node-name, next, previous, up -@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 <CR> 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 - -@defvar c-mode-common-hook -@vindex mode-common-hook (c-) -Common hook across all languages. It's run immediately before the -language specific hook. -@end defvar - -@defvar c-mode-hook -@defvarx c++-mode-hook -@defvarx objc-mode-hook -@defvarx java-mode-hook -@defvarx idl-mode-hook -@defvarx pike-mode-hook -@defvarx awk-mode-hook -The language specific mode hooks. The appropriate one is run as the -last thing when you enter that language mode. -@end defvar - -Although these hooks are variables defined in @ccmode{}, you can give -them values before @ccmode{}'s code is loaded---indeed, this is the -only way to use @code{c-initialization-hook}. Their values aren't -overwritten when @ccmode{} gets loaded. - -Here's a simplified example of what you can add to your @file{.emacs} -file to do things whenever any @ccmode{} language is edited. See the -Emacs manuals for more information on customizing Emacs via hooks. -@xref{Sample .emacs File}, for a more complete sample @file{.emacs} -file. - -@example -(defun my-c-mode-common-hook () - ;; my customizations for all of c-mode and related modes - (no-case-fold-search) - ) -(add-hook 'c-mode-common-hook 'my-c-mode-common-hook) -@end example - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Style Variables, Styles, CC Hooks, Config Basics -@comment node-name, next, previous, up -@section Style Variables -@cindex styles -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@cindex style variables -The variables that @ccmode{}'s style system control are called -@dfn{style variables}. Note that style variables are ordinary Lisp -variables, which the style system initializes; you can change their -values at any time (e.g. in a hook function). The style system can -also set other variables, to some extent. @xref{Styles}. - -@dfn{Style variables} are handled specially in several ways: - -@itemize @bullet -@item -Style variables are by default buffer-local variables. However, they -can instead be made global by setting -@code{c-style-variables-are-local-p} to @code{nil} before @ccmode{} is -initialized. - -@item -@vindex c-old-style-variable-behavior -@vindex old-style-variable-behavior (c-) -The default global binding of any style variable (with two exceptions -- see below) is the special symbol @code{set-from-style}. When the -style system initializes a buffer-local copy of a style variable for a -@ccmode{} buffer, if its global binding is still that symbol then it -will be set from the current style. Otherwise it will retain its -global default@footnote{This is a big change from versions of -@ccmode{} earlier than 5.26, where such settings would get overridden -by the style system unless special precautions were taken. That was -changed since it was counterintuitive and confusing, especially to -novice users. If your configuration depends on the old overriding -behavior, you can set the variable -@code{c-old-style-variable-behavior} to non-@code{nil}.}. This -``otherwise'' happens, for example, when you've set the variable with -@code{setq} at the top level of your @file{.emacs} (@pxref{Config -Basics}). - -@item -The style variable @code{c-offsets-alist} (@pxref{c-offsets-alist}) is -an association list with an element for each syntactic symbol. It's -handled a little differently from the other style variables. It's -default global binding is the empty list @code{nil}, rather than -@code{set-from-style}. Before the style system is initialized, you -can add individual elements to @code{c-offsets-alist} by calling -@code{c-set-offset}(@pxref{c-offsets-alist}) just like you would set -other style variables with @code{setq}. Those elements will then -prevail when the style system later initializes a buffer-local copy of -@code{c-offsets-alist}. - -@item -The style variable @code{c-special-indent-hook} is also handled in a -special way. Styles can only add functions to this hook, not remove -them, so any global settings you put on it are always -preserved@footnote{This did not change in version 5.26.}. The value -you give this variable in a style definition can be either a function -or a list of functions. - -@item -The global bindings of the style variables get captured in the special -@code{user} style when the style system is first initialized. -@xref{Built-in Styles}, for details. -@end itemize - -The style variables are:@* -@code{c-indent-comment-alist}, -@code{c-indent-comments-syntactically-p} (@pxref{Indentation -Commands});@* -@code{c-doc-comment-style} (@pxref{Doc Comments});@* -@code{c-block-comment-prefix}, @code{c-comment-prefix-regexp} -(@pxref{Custom Filling and Breaking});@* -@code{c-hanging-braces-alist} (@pxref{Hanging Braces});@* -@code{c-hanging-colons-alist} (@pxref{Hanging Colons});@* -@code{c-hanging-semi&comma-criteria} (@pxref{Hanging Semicolons and -Commas});@* -@code{c-cleanup-list} (@pxref{Clean-ups});@* -@code{c-basic-offset} (@pxref{Customizing Indentation});@* -@code{c-offsets-alist} (@pxref{c-offsets-alist});@* -@code{c-comment-only-line-offset} (@pxref{Comment Line-Up});@* -@code{c-special-indent-hook}, @code{c-label-minimum-indentation} -(@pxref{Other Indentation});@* -@code{c-backslash-column}, @code{c-backslash-max-column} -(@pxref{Custom Macros}). - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Styles, , Style Variables, Config Basics -@comment node-name, next, previous, up -@section Styles -@cindex styles -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -By @dfn{style} we mean the layout of the code---things like how many -columns to indent a block of code, whether an opening brace gets -indented to the level of the code it encloses, or of the construct -that introduces it, or ``hangs'' at the end of a line. - -Most people only need to edit code formatted in just a few well-defined -and consistent styles. For example, their organization might impose a -``blessed'' style that all its programmers must conform to. Similarly, -people who work on GNU software will have to use the GNU coding style. -Some shops are more lenient, allowing a variety of coding styles, and as -programmers come and go, there could be a number of styles in use. For -this reason, @ccmode{} makes it convenient for you to set up logical -groupings of customizations called @dfn{styles}, associate a single name -for any particular style, and pretty easily start editing new or -existing code using these styles. - -@menu -* Built-in Styles:: -* Choosing a Style:: -* Adding Styles:: -* File Styles:: -@end menu - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Built-in Styles, Choosing a Style, Styles, Styles -@comment node-name, next, previous, up -@subsection Built-in Styles -@cindex styles, built-in -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -If you're lucky, one of @ccmode{}'s built-in styles might be just -what you're looking for. These are: - -@table @code -@item gnu -@cindex GNU style -Coding style blessed by the Free Software Foundation -for C code in GNU programs. - -@item k&r -@cindex K&R style -The classic Kernighan and Ritchie style for C code. - -@item bsd -@cindex BSD style -Also known as ``Allman style'' after Eric Allman. - -@item whitesmith -@cindex Whitesmith style -Popularized by the examples that came with Whitesmiths C, an early -commercial C compiler. - -@item stroustrup -@cindex Stroustrup style -The classic Stroustrup style for C++ code. - -@item ellemtel -@cindex Ellemtel style -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 -C coding standard for Linux (the kernel). - -@item python -@cindex Python style -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 -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 -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 - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Choosing a Style, Adding Styles, Built-in Styles, Styles -@comment node-name, next, previous, up -@subsection Choosing a Style -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -When you create a new buffer, its style will be set from -@code{c-default-style}. The factory default is the style @code{gnu}, -except in Java and AWK modes where it's @code{java} and @code{awk}. - -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. - -To set a buffer's style interactively, use the command @kbd{C-c .} -(@pxref{Other Commands}). To set it from a file's local variable -list, @ref{File Styles}. - -@defopt c-default-style -@vindex default-style (c-) -This variable specifies which style to install by default in new -buffers. It takes either a style name string, or an association list -of major mode symbols to style names: - -@enumerate -@item -When @code{c-default-style} is a string, it must be an existing style -name. This style is then used for all modes. - -@item -When @code{c-default-style} is an association list, the mode language -is looked up to find a style name string. - -@item -If @code{c-default-style} is an association list where the mode -language mode isn't found then the special symbol @samp{other} is -looked up. If it's found then the associated style is used. - -@item -If @samp{other} is not found then the @samp{gnu} style is used. -@end enumerate - -In all cases, the style described in @code{c-default-style} is installed -@emph{before} the language hooks are run, so you can always override -this setting by including an explicit call to @code{c-set-style} in your -language mode hook, or in @code{c-mode-common-hook}. - -The standard value of @code{c-default-style} is @w{@code{((java-mode -. "java") (awk-mode . "awk") (other . "gnu"))}}. -@end defopt - -@defvar c-indentation-style -@vindex indentation-style (c-) -This variable always contains the buffer's current style name, as a -string. -@end defvar - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Adding Styles, File Styles, Choosing a Style, Styles -@comment node-name, next, previous, up -@subsection Adding and Amending Styles -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -If none of the built-in styles is appropriate, you'll probably want to -create a new @dfn{style definition}, possibly based on an existing -style. To do this, put the new style's settings into a list with the -following format - the list can then be passed as an argument to the -function @code{c-add-style}. You can see an example of a style -definition in @ref{Sample .emacs File}. - -@cindex style definition -@c @defvr {List} style definition -@table @asis -@item Structure of a Style Definition List -([@var{base-style}] [(@var{variable} . @var{value}) @dots{}]) - -Optional @var{base-style}, if present, must be a string which is the -name of the @dfn{base style} from which this style inherits. At most -one @var{base-style} is allowed in a style definition. If -@var{base-style} is not specified, the style inherits from the table -of factory default values@footnote{This table is stored internally in -the variable c-fallback-style.} instead. All styles eventually -inherit from this internal table. Style loops generate errors. The -list of pre-existing styles can be seen in @ref{Built-in Styles}. - -The dotted pairs (@var{variable} . @var{value}) each consist of a -variable and the value it is to be set to when the style is later -activated.@footnote{Note that if the variable has been given a value -by the Customization interface or a @code{setq} at the top level of -your @file{.emacs}, this value will override the one the style system -tries to give it. @xref{Config Basics}.} The variable can be either a -@ccmode{} style variable or an arbitrary Emacs variable. In the -latter case, it is @emph{not} made buffer-local by the @ccmode{} style -system. -@c @end defvr - -Two variables are treated specially in the dotted pair list: - -@table @code -@item c-offsets-alist -The value is in turn a list of dotted pairs of the form - -@example -(@r{@var{syntactic-symbol}} . @r{@var{offset}}) -@end example - -as described in @ref{c-offsets-alist}. These are passed to -@code{c-set-offset} so there is no need to set every syntactic symbol -in your style, only those that are different from the inherited style. - -@item c-special-indent-hook -The value is added to @code{c-special-indent-hook} using -@code{add-hook}, so any functions already on it are kept. If the value -is a list, each element of the list is added with @code{add-hook}. -@end table -@end table - -Styles are kept in the @code{c-style-alist} variable, but you -should never modify this variable directly. Instead, @ccmode{} -provides the function @code{c-add-style} for this purpose. - -@defun c-add-style stylename description &optional set-p -@findex add-style (c-) -Add or update a style called @var{stylename}, a string. -@var{description} is the new style definition in the form described -above. If @var{stylename} already exists in @code{c-style-alist} then -it is replaced by @var{description}. (Note, this replacement is -total. The old style is @emph{not} merged into the new one.) -Otherwise, a new style is added. - -If the optional @var{set-p} is non-@code{nil} then the new style is -applied to the current buffer as well. The use of this facility is -deprecated and it might be removed from @ccmode{} in a future release. -You should use @code{c-set-style} instead. - -The sample @file{.emacs} file provides a concrete example of how a new -style can be added and automatically set. @xref{Sample .emacs File}. -@end defun - -@defvar c-style-alist -@vindex style-alist (c-) -This is the variable that holds the definitions for the styles. It -should not be changed directly; use @code{c-add-style} instead. -@end defvar - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node File Styles, , Adding Styles, Styles -@comment node-name, next, previous, up -@subsection File Styles -@cindex styles, file local -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@cindex file local variables - -The Emacs manual describes how you can customize certain variables on a -per-file basis by including a @dfn{file local variable} block at the end -of the file (@pxref{File Variables,, Local Variables in Files, @emacsman{}, -@emacsmantitle{}}). - -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: - -@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 - -@defvar c-file-offsets -@vindex file-offsets (c-) -Set this variable (in the Local Variables list) to an association list -of the same format as @code{c-offsets-alist}. From now on, when you -visit the file, @ccmode{} will automatically institute these offsets -using @code{c-set-offset}. -@end defvar - -Note that file style settings (i.e. @code{c-file-style}) are applied -before file offset settings -(i.e. @code{c-file-offsets})@footnote{Also, if either of these are set -in a file's local variable section, all the style variable values are -made local to that buffer, even if -@code{c-style-variables-are-local-p} is @code{nil}. Since this -variable is virtually always non-@code{nil} anyhow, you're unlikely to -notice this effect.}. - -If you set any variables, including style variables, by the file local -variables mechanism, these settings take priority over all other -settings, even those in your mode hooks (@pxref{CC Hooks}). If you -use @code{c-file-style} or @code{c-file-offsets} and also explicitly -set a style variable in a local variable block, the explicit setting -will take priority. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Custom Filling and Breaking, Custom Auto-newlines, Config Basics, Top -@comment node-name, next, previous, up -@chapter Customizing 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. It does -this by hooking in on the different line breaking functions and tuning -relevant variables as necessary. - -@vindex c-comment-prefix-regexp -@vindex comment-prefix-regexp (c-) -@cindex comment line prefix -@vindex comment-start -@vindex comment-end -@vindex comment-start-skip -@vindex paragraph-start -@vindex paragraph-separate -@vindex paragraph-ignore-fill-prefix -@vindex adaptive-fill-mode -@vindex adaptive-fill-regexp -@vindex adaptive-fill-first-line-regexp -To make Emacs recognize comments and treat text in them as normal -paragraphs, @ccmode{} makes several standard -variables@footnote{@code{comment-start}, @code{comment-end}, -@code{comment-start-skip}, @code{paragraph-start}, -@code{paragraph-separate}, @code{paragraph-ignore-fill-prefix}, -@code{adaptive-fill-mode}, @code{adaptive-fill-regexp}, and -@code{adaptive-fill-first-line-regexp}.} buffer-local and modifies them -according to the language syntax and the comment line prefix. - -@defopt c-comment-prefix-regexp -@vindex comment-prefix-regexp (c-) -This style variable contains the regexp used to recognize the -@dfn{comment line prefix}, which is the line decoration that starts -every line in a comment. The variable is either the comment line -prefix itself, or (more usually) an association list with different -values for different languages. The symbol for the major mode is -looked up in the alist to get the regexp for the language, and if it -isn't found then the special symbol @samp{other} is looked up instead. - -When a comment line gets divided by @kbd{M-j} or the like, @ccmode{} -inserts the comment line prefix from a neighbouring line at the start -of the new line. The default value of c-comment-prefix-regexp is -@samp{//+\\|\\**}, which matches C++ style line comments like - -@example -// blah blah -@end example - -@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 - -@noindent -with zero or more stars at the beginning of every line. If you change -this variable, please make sure it still matches the comment starter -(i.e. @code{//}) of line comments @emph{and} the line prefix inside -block comments. - -@findex c-setup-paragraph-variables -@findex setup-paragraph-variables (c-) -Also note that since @ccmode{} uses the value of -@code{c-comment-prefix-regexp} to set up several other variables at -mode initialization, there won't be any effect if you just change it -inside a @ccmode{} buffer. You need to call the command -@code{c-setup-paragraph-variables} too, to update those other -variables. That's also the case if you modify -@code{c-comment-prefix-regexp} in a mode hook, since @ccmode{} will -already have set up these variables before calling the hook. -@end defopt - -In comments, @ccmode{} uses @code{c-comment-prefix-regexp} to adapt -the line prefix from the other lines in the comment. - -@vindex adaptive-fill-mode -@cindex Adaptive Fill mode -@ccmode{} uses adaptive fill mode (@pxref{Adaptive Fill,,, emacs, GNU -Emacs Manual}) to make Emacs correctly keep the line prefix when -filling paragraphs. That also makes Emacs preserve the text -indentation @emph{inside} the comment line prefix. E.g. in the -following comment, both paragraphs will be filled with the left -margins of the texts kept intact: - -@example -@group -/* 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 - -@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 - -@defopt c-block-comment-prefix -@vindex block-comment-prefix (c-) -@vindex c-comment-continuation-stars -@vindex comment-continuation-stars (c-) -Normally the comment line prefix inserted for a new line inside a -comment is deduced from other lines in it. However there's one -situation when there's no hint about what the prefix should look like, -namely when a block comment is broken for the first time. This style -variable@footnote{In versions before 5.26, this variable was called -@code{c-comment-continuation-stars}. As a compatibility measure, -@ccmode{} still uses the value on that variable if it's set.} is used -then as the comment prefix. It defaults to @samp{* -}@footnote{Actually, this default setting of -@code{c-block-comment-prefix} typically gets overridden by the default -style @code{gnu}, which sets it to blank. You can see the line -splitting effect described here by setting a different style, -e.g. @code{k&r} @xref{Choosing a Style}.}, which makes a comment - -@example -/* Got O(n^2) here, which is a Bad Thing. */ -@end example - -@noindent -break into - -@example -@group -/* Got O(n^2) here, which - * is a Bad Thing. */ -@end group -@end example - -Note that it won't work to adjust the indentation by putting leading -spaces in @code{c-block-comment-prefix}, since @ccmode{} still uses the -normal indentation engine to indent the line. Thus, the right way to -fix the indentation is by customizing the @code{c} syntactic symbol. It -defaults to @code{c-lineup-C-comments}, which handles the indentation of -most common comment styles, see @ref{Line-Up Functions}. -@end defopt - -@defopt c-ignore-auto-fill -@vindex ignore-auto-fill (c-) -When auto fill mode is enabled, @ccmode{} can selectively ignore it -depending on the context the line break would occur in, e.g. to never -break a line automatically inside a string literal. This variable -takes a list of symbols for the different contexts where auto-filling -never should occur: - -@table @code -@item string -Inside a string or character literal. -@item c -Inside a C style block comment. -@item c++ -Inside a C++ style line comment. -@item cpp -Inside a preprocessor directive. -@item code -Anywhere else, i.e. in normal code. -@end table - -By default, @code{c-ignore-auto-fill} is set to @code{(string cpp -code)}, which means that when auto-fill mode is activated, -auto-filling only occurs in comments. In literals, it's often -desirable to have explicit control over newlines. In preprocessor -directives, the necessary @samp{\} escape character before the newline -is not automatically inserted, so an automatic line break would -produce invalid code. In normal code, line breaks are normally -dictated by some logical structure in the code rather than the last -whitespace character, so automatic line breaks there will produce poor -results in the current implementation. -@end defopt - -@vindex comment-multi-line -If inside a comment and @code{comment-multi-line} (@pxref{Auto Fill,,, -@emacsman{}, @emacsmantitle{}} is non-@code{nil}, the indentation and -line prefix are preserved. If inside a comment and -@code{comment-multi-line} is @code{nil}, a new comment of the same -type is started on the next line and indented as appropriate for -comments. - -Note that @ccmode{} sets @code{comment-multi-line} to @code{t} at -startup. The reason is that @kbd{M-j} could otherwise produce sequences -of single line block comments for texts that should logically be treated -as one comment, and the rest of the paragraph handling code -(e.g. @kbd{M-q} and @kbd{M-a}) can't cope with that, which would lead to -inconsistent behavior. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Custom Auto-newlines, Clean-ups, Custom Filling and Breaking, Top -@comment node-name, next, previous, up -@chapter Customizing Auto-newlines -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@ccmode{} determines whether to insert auto-newlines in two basically -different ways, depending on the character just typed: - -@table @asis -@item Braces and Colons -@ccmode{} first determines the syntactic context of the brace or colon -(@pxref{Syntactic Symbols}), then looks for a corresponding element in -an alist. This element specifies where to put newlines - this is any -combination of before and after the brace or colon. If no alist -element is found, newlines are inserted both before and after a brace, -but none are inserted around a colon. See @ref{Hanging Braces} and -@ref{Hanging Colons}. - -@item Semicolons and Commas -The variable @code{c-hanging-semi&comma-criteria} contains a list of -functions which determine whether to insert a newline after a newly -typed semicolon or comma. @xref{Hanging Semicolons and Commas}. -@end table - -The names of these configuration variables contain @samp{hanging} -because they let you @dfn{hang} the pertinent characters. A character -which introduces a C construct is said to @dfn{hang on the right} when -it appears at the end of a line after other code, being separated by a -line break from the construct it introduces, like the opening brace in: - -@example -@group -while (i < MAX) @{ - total += entry[i]; - entry [i++] = 0; -@} -@end group -@end example - -@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 syntactic symbol an @dfn{action function} in -@code{c-hanging-braces-alist}; this function determines the -``hanginess'' of a brace, usually by looking at the code near it. - -@cindex customization, brace hanging -An action function is called with two arguments: the syntactic symbol -for the brace (e.g. @code{substatement-open}), and the buffer position -where the brace has been inserted. Point is undefined on entry to an -action function, but the function must preserve it (e.g. by using -@code{save-excursion}). The return value should be a list containing -some combination of @code{before} and @code{after}, including neither -of them (i.e. @code{nil}). - -@defvar c-syntactic-context -@vindex syntactic-context (c-) -During the call to the indentation or brace hanging @var{action} -function, this variable is bound to the full syntactic analysis list. -This might be, for example, @samp{((block-close 73))}. Don't ever -give @code{c-syntactic-context} a value yourself---this would disrupt -the proper functioning of @ccmode{}. - -This variable is also bound in three other circumstances: -(i)@w{ }when calling a c-hanging-semi&comma-criteria function -(@pxref{Hanging Semicolons and Commas}); (ii)@w{ }when calling a -line-up function (@pxref{Custom Line-Up}); (iii)@w{ }when calling a -c-special-indent-hook function (@pxref{Other Indentation}). -@end defvar - -As an example, @ccmode{} itself uses this feature to dynamically -determine the hanginess of braces which close ``do-while'' -constructs: - -@example -void do_list( int count, char** atleast_one_string ) -@{ - int i=0; - do @{ - handle_string( atleast_one_string[i] ); - i++; - @} while( i < count ); -@} -@end example - -@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 -@code{c-snug-do-while}: - -@example -(defun c-snug-do-while (syntax pos) - "Dynamically calculate brace hanginess for do-while statements." - (save-excursion - (let (langelem) - (if (and (eq syntax 'block-close) - (setq langelem (assq 'block-close c-syntactic-context)) - (progn (goto-char (cdr langelem)) - (if (= (following-char) ?@{) - (forward-sexp -1)) - (looking-at "\\<do\\>[^_]"))) - '(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. - -@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-) - -@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 Hanging Semicolons and Commas, , Hanging Colons, Custom Auto-newlines -@comment node-name, next, previous, up -@section Hanging Semicolons and Commas -@cindex hanging semicolons -@cindex hanging commas -@cindex customization, semicolon newlines -@cindex customization, comma newlines -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@defopt c-hanging-semi&comma-criteria -@vindex hanging-semi&comma-criteria (c-) -This style variable takes a list of functions; these get called when -you type a semicolon or comma. The functions are called in order -without arguments. When these functions are entered, point is just -after the newly inserted @samp{;} or @samp{,} and they must preserve -point (e.g., by using @code{save-excursion}). During the call, the -variable @code{c-syntactic-context} is bound to the syntactic context -of the current line@footnote{This was first introduced in @ccmode{} -5.31.} @pxref{Custom Braces}. These functions don't insert newlines -themselves, rather they direct @ccmode{} whether or not to do so. -They should return one of the following values: - -@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 - -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. - -In AWK mode, this variable is set by default to @code{nil}. In the -other modes, the default value is a list containing a single function, -@code{c-semi&comma-inside-parenlist}. This inserts newlines after all -semicolons, apart from those separating @code{for}-clause statements. -@end defopt - -@defun c-semi&comma-no-newlines-before-nonblanks -@findex semi&comma-no-newlines-before-nonblanks (c-) -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 -(defun c-semi&comma-no-newlines-before-nonblanks () - (save-excursion - (if (and (eq last-command-char ?\;) - (zerop (forward-line 1)) - (not (looking-at "^[ \t]*$"))) - 'stop - nil))) -@end example -@end defun - -@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} -statements. In addition to -@code{c-semi&comma-no-newlines-before-nonblanks} described above, -@ccmode{} also comes with the criteria function -@code{c-semi&comma-no-newlines-for-oneline-inliners}, which suppresses -newlines after semicolons inside one-line inline method definitions -(e.g. in C++ or Java). -@end defun - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Clean-ups, Indentation Engine Basics, Custom Auto-newlines, Top -@comment node-name, next, previous, up -@chapter Clean-ups -@cindex clean-ups -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@dfn{Clean-ups} are mechanisms which remove (or exceptionally, add) -whitespace in specific circumstances and are complementary to colon -and brace hanging. You enable a clean-up by adding its symbol into -@code{c-cleanup-list}, e.g. like this: - -@example -(add-to-list 'c-cleanup-list 'space-before-funcall) -@end example - -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. - -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 - -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 - -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 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: - -@example -@group -void spam(int i) -@{ - if( i==7 ) @{ - dosomething(); - @} - else - @{ -@end group -@end example - -@noindent -appears like this after the last open brace is typed: - -@example -@group -void spam(int i) -@{ - if( i==7 ) @{ - dosomething(); - @} else @{ -@end group -@end example - -@item brace-elseif-brace -Similar to the @code{brace-else-brace} clean-up, but this cleans up -@samp{@} else if (...) @{} constructs. For example: - -@example -@group -void spam(int i) -@{ - if( i==7 ) @{ - dosomething(); - @} - else if( i==3 ) - @{ -@end group -@end example - -@noindent -appears like this after the last open parenthesis is typed: - -@example -@group -void spam(int i) -@{ - if( i==7 ) @{ - dosomething(); - @} else if( -@end group -@end example - -@noindent -and like this after the last open brace is typed: - -@example -@group -void spam(int i) -@{ - if( i==7 ) @{ - dosomething(); - @} else if( i==3 ) @{ -@end group -@end example - -@item brace-catch-brace -Analogous to @code{brace-elseif-brace}, but cleans up @samp{@} catch -(...) @{} in C++ and Java mode. - -@item empty-defun-braces -Clean up braces following a top-level function or class definition that -contains no body. Clean up occurs when the closing brace is typed. -Thus the following: - -@example -@group -class Spam -@{ -@} -@end group -@end example - -@noindent -is transformed into this when the close brace is typed: - -@example -@group -class Spam -@{@} -@end group -@end example - -@item defun-close-semi -Clean up the terminating semicolon on top-level function or class -definitions when they follow a close brace. Clean up occurs when the -semicolon is typed. So for example, the following: - -@example -@group -class Spam -@{ -... -@} -; -@end group -@end example - -@noindent -is transformed into this when the semicolon is typed: - -@example -@group -class Spam -@{ -... -@}; -@end group -@end example - -@item list-close-comma -Clean up commas following braces in array and aggregate initializers. -Clean up occurs when the comma is typed. The space before the comma -is zapped just like the space before the semicolon in -@code{defun-close-semi}. - -@item scope-operator -Clean up double colons which might designate a C++ scope operator split -across multiple lines@footnote{Certain C++ constructs introduce -ambiguous situations, so @code{scope-operator} clean-ups might not -always be correct. This usually only occurs when scoped identifiers -appear in switch label tags.}. Clean up occurs when the second colon is -typed. You will always want @code{scope-operator} in the -@code{c-cleanup-list} when you are editing C++ code. - -@item one-liner-defun -Clean up a single line of code enclosed by defun braces by removing -the whitespace before and after the code. The clean-up happens when -the closing brace is typed. If the variable -@code{c-max-one-liner-length} is set, the cleanup is only done if the -resulting line would be no longer than the value of that variable. - -For example, consider this AWK code: - -@example -@group -BEGIN @{ - FS = "\t" # use <TAB> as a field separator -@} -@end group -@end example - -@noindent -It gets compacted to the following when the closing brace is typed: - -@example -@group -BEGIN @{FS = "\t"@} # use <TAB> as a field separator -@end group -@end example - -@defopt c-max-one-liner-length -@vindex max-one-liner-length (c-) -The maximum length of the resulting line for which the clean-up -@code{one-liner-defun} will be triggered. This length is that of the entire -line, including any leading whitespace and any trailing comment. Its -default value is 80. If the value is zero or @code{nil}, no limit -applies. -@end defopt -@end table - -The following clean-ups are always active when they occur on -@code{c-cleanup-list}, regardless of whether Electric minor mode or -Auto-newline minor mode are enabled: - -@table @code -@item space-before-funcall -Insert a space between the function name and the opening parenthesis -of a function call. This produces function calls in the style -mandated by the GNU coding standards, e.g. @samp{signal@w{ }(SIGINT, -SIG_IGN)} and @samp{abort@w{ }()}. Clean up occurs when the opening -parenthesis is typed. This clean-up should never be active in AWK -Mode, since such a space is syntactically invalid for user defined -functions. - -@item compact-empty-funcall -Clean up any space between the function name and the opening parenthesis -of a function call that has no arguments. This is typically used -together with @code{space-before-funcall} if you prefer the GNU function -call style for functions with arguments but think it looks ugly when -it's only an empty parenthesis pair. I.e. you will get @samp{signal -(SIGINT, SIG_IGN)}, but @samp{abort()}. Clean up occurs when the -closing parenthesis is typed. - -@item comment-close-slash -When inside a block comment, terminate the comment when you type a slash -at the beginning of a line (i.e. immediately after the comment prefix). -This clean-up removes whitespace preceding the slash and if needed, -inserts a star to complete the token @samp{*/}. Type @kbd{C-q /} in this -situation if you just want a literal @samp{/} inserted. -@end table - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Indentation Engine Basics, Customizing Indentation, Clean-ups, Top -@comment node-name, next, previous, up -@chapter Indentation Engine Basics -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -This chapter will briefly cover how @ccmode{} indents lines of code. -It is helpful to understand the indentation model being used so that -you will know how to customize @ccmode{} for your personal coding -style. All the details are in @ref{Customizing Indentation}. - -@ccmode{} has an indentation engine that provides a flexible and -general mechanism for customizing indentation. When @ccmode{} indents -a line of code, it separates its calculations into two steps: - -@enumerate -@item -@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 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@cindex syntactic element -@cindex syntactic context -The first thing @ccmode{} does when indenting a line of code, is to -analyze the line, determining the @dfn{syntactic context} of the -(first) construct on that line. It's a list of @dfn{syntactic -elements}, where each syntactic element in turn is a list@footnote{In -@ccmode 5.28 and earlier, a syntactic element was a dotted pair; the -cons was the syntactic symbol and the cdr was the anchor position. -For compatibility's sake, the parameter passed to a line-up function -still has this dotted pair form (@pxref{Custom Line-Up}).} Here is a -brief and typical example: - -@example -((defun-block-intro 1959)) -@end example - -@cindex syntactic symbol -@noindent -The first thing inside each syntactic element is always a -@dfn{syntactic symbol}. It describes the kind of construct that was -recognized, e.g. @code{statement}, @code{substatement}, -@code{class-open}, @code{class-close}, etc. @xref{Syntactic Symbols}, -for a complete list of currently recognized syntactic symbols and -their semantics. The remaining entries are various data associated -with the recognized construct - there might be zero or more. - -@cindex anchor position -Conceptually, a line of code is always indented relative to some -position higher up in the buffer (typically the indentation of the -previous line). That position is the @dfn{anchor position} in the -syntactic element. If there is an entry after the syntactic symbol in -the syntactic element list then it's either nil or that anchor position. - -Here is an example. Suppose we had the following code as the only thing -in a C++ buffer @footnote{The line numbers in this and future examples -don't actually appear in the buffer, of course!}: - -@example - 1: void swap( int& a, int& b ) - 2: @{ - 3: int tmp = a; - 4: a = b; - 5: b = tmp; - 6: @} -@end example - -@noindent -We can use @kbd{C-c C-s} (@code{c-show-syntactic-information}) to -report what the syntactic analysis is for the current line: - -@table @asis -@item @kbd{C-c C-s} (@code{c-show-syntactic-information}) -@kindex C-c C-s -@findex c-show-syntactic-information -@findex show-syntactic-information (c-) -This command calculates the syntactic analysis of the current line and -displays it in the minibuffer. The command also highlights the anchor -position(s). -@end table - - Running this command on line 4 of this example, we'd see in the echo -area@footnote{With a universal argument (i.e. @kbd{C-u C-c C-s}) the -analysis is inserted into the buffer as a comment on the current -line.}: - -@example -((statement 35)) -@end example - -@noindent -and the @samp{i} of @code{int} on line 3 would be highlighted. This -tells us that the line is a statement and it is indented relative to -buffer position 35, the highlighted position. If you were to move -point to line 3 and hit @kbd{C-c C-s}, you would see: - -@example -((defun-block-intro 29)) -@end example - -@noindent -This indicates that the @samp{int} line is the first statement in a top -level function block, and is indented relative to buffer position 29, -which is the brace just after the function header. - -Here's another example: - -@example - 1: int add( int val, int incr, int doit ) - 2: @{ - 3: if( doit ) - 4: @{ - 5: return( val + incr ); - 6: @} - 7: return( val ); - 8: @} -@end example - -@noindent -Hitting @kbd{C-c C-s} on line 4 gives us: - -@example -((substatement-open 46)) -@end example - -@cindex substatement -@cindex substatement block -@noindent -which tells us that this is a brace that @emph{opens} a substatement -block. @footnote{A @dfn{substatement} is the line after a -conditional statement, such as @code{if}, @code{else}, @code{while}, -@code{do}, @code{switch}, etc. A @dfn{substatement -block} is a brace block following one of these conditional statements.} - -@cindex comment-only line -Syntactic contexts can contain more than one element, and syntactic -elements need not have anchor positions. The most common example of -this is a @dfn{comment-only line}: - -@example - 1: void draw_list( List<Drawables>& drawables ) - 2: @{ - 3: // call the virtual draw() method on each element in list - 4: for( int i=0; i < drawables.count(), ++i ) - 5: @{ - 6: drawables[i].draw(); - 7: @} - 8: @} -@end example - -@noindent -Hitting @kbd{C-c C-s} on line 3 of this example gives: - -@example -((comment-intro) (defun-block-intro 46)) -@end example - -@noindent -and you can see that the syntactic context contains two syntactic -elements. Notice that the first element, @samp{(comment-intro)}, has no -anchor position. - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Syntactic Symbols, Indentation Calculation, Syntactic Analysis, Indentation Engine Basics -@comment node-name, next, previous, up -@section Syntactic Symbols -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@cindex syntactic symbols, brief list -@vindex c-offsets-alist -@vindex offsets-alist (c-) -This section is a complete list of the syntactic symbols which appear -in the @code{c-offsets-alist} style variable, along with brief -descriptions. The previous section (@pxref{Syntactic Analysis}) -states what syntactic symbols are and how the indentation engine uses -them. - -More detailed descriptions of these symbols, together with snippets of -source code to which they apply, appear in the examples in the -subsections below. Note that, in the interests of brevity, the anchor -position associated with most syntactic symbols is @emph{not} -specified. In cases of doubt, type @kbd{C-c C-s} on a pertinent -line---this highlights the anchor position. - -@ssindex -open symbols -@ssindex -close symbols -@ssindex -block-intro symbols -The syntactic symbols which indicate brace constructs follow a general -naming convention. When a line begins with an open or close brace, -its syntactic symbol will contain the suffix @code{-open} or -@code{-close} respectively. The first line within the brace block -construct will contain the suffix @code{-block-intro}. - -@ssindex -intro symbols -@ssindex -cont symbols -In constructs which can span several lines, a distinction is usually -made between the first line that introduces the construct and the -lines that continue it. The syntactic symbols that indicate these -lines will contain the suffixes @code{-intro} or @code{-cont} -respectively. - -The best way to understand how all this works is by looking at some -examples. Remember that you can see the syntax of any source code -line by using @kbd{C-c C-s}. - -@table @code -@item string -Inside a multiline string. @ref{Literal Symbols}. -@item c -Inside a multiline C style block comment. @ref{Literal Symbols}. -@item defun-open -Brace that opens a top-level function definition. @ref{Function -Symbols}. -@item defun-close -Brace that closes a top-level function definition. @ref{Function -Symbols}. -@item defun-block-intro -The first line in a top-level defun. @ref{Function Symbols}. -@item class-open -Brace that opens a class definition. @ref{Class Symbols}. -@item class-close -Brace that closes a class definition. @ref{Class Symbols}. -@item inline-open -Brace that opens an in-class inline method. @ref{Class Symbols}. -@item inline-close -Brace that closes an in-class inline method. @ref{Class Symbols}. -@item func-decl-cont -The region between a function definition's argument list and the -function opening brace (excluding K&R argument declarations). In C, -you cannot put anything but whitespace and comments in this region, -however in C++ and Java, @code{throws} declarations and other things -can appear here. @ref{Literal Symbols}. @c @emph{FIXME!!! Can it not -@c go somewhere better?} -@item knr-argdecl-intro -First line of a K&R C argument declaration. @ref{K&R Symbols}. -@item knr-argdecl -Subsequent lines in a K&R C argument declaration. @ref{K&R Symbols}. -@item topmost-intro -The first line in a ``topmost'' definition. @ref{Function Symbols}. -@item topmost-intro-cont -Topmost definition continuation lines. This is only used in the parts -that aren't covered by other symbols such as @code{func-decl-cont} and -@code{knr-argdecl}. @ref{Function Symbols}. -@item member-init-intro -First line in a member initialization list. @ref{Class Symbols}. -@item member-init-cont -Subsequent member initialization list lines. @ref{Class Symbols}. -@item inher-intro -First line of a multiple inheritance list. @ref{Class Symbols}. -@item inher-cont -Subsequent multiple inheritance lines. @ref{Class Symbols}. -@item block-open -Statement block open brace. @ref{Literal Symbols}. -@item block-close -Statement block close brace. @ref{Conditional Construct Symbols}. -@item brace-list-open -Open brace of an enum or static array list. @ref{Brace List Symbols}. -@item brace-list-close -Close brace of an enum or static array list. @ref{Brace List Symbols}. -@item brace-list-intro -First line in an enum or static array list. @ref{Brace List Symbols}. -@item brace-list-entry -Subsequent lines in an enum or static array list. @ref{Brace List -Symbols}. -@item brace-entry-open -Subsequent lines in an enum or static array list where the line begins -with an open brace. @ref{Brace List Symbols}. -@item statement -A statement. @ref{Function Symbols}. -@item statement-cont -A continuation of a statement. @ref{Function Symbols}. -@item statement-block-intro -The first line in a new statement block. @ref{Conditional Construct -Symbols}. -@item statement-case-intro -The first line in a case block. @ref{Switch Statement Symbols}. -@item statement-case-open -The first line in a case block that starts with a brace. @ref{Switch -Statement Symbols}. -@item substatement -The first line after a conditional or loop construct. -@ref{Conditional Construct Symbols}. -@item substatement-open -The brace that opens a substatement block. @ref{Conditional Construct -Symbols}. -@item substatement-label -The first line after a conditional or loop construct if it's a label. -@ref{Conditional Construct Symbols}. -@item case-label -A label in a @code{switch} block. @ref{Switch Statement Symbols}. -@item access-label -C++ access control label. @ref{Class Symbols}. -@item label -Any other label. @ref{Literal Symbols}. -@item do-while-closure -The @code{while} line that ends a @code{do}-@code{while} construct. -@ref{Conditional Construct Symbols}. -@item else-clause -The @code{else} line of an @code{if}-@code{else} construct. -@ref{Conditional Construct Symbols}. -@item catch-clause -The @code{catch} or @code{finally} (in Java) line of a -@code{try}-@code{catch} construct. @ref{Conditional Construct -Symbols}. -@item comment-intro -A line containing only a comment introduction. @ref{Literal Symbols}. -@item arglist-intro -The first line in an argument list. @ref{Paren List Symbols}. -@item arglist-cont -Subsequent argument list lines when no arguments follow on the same -line as the arglist opening paren. @ref{Paren List Symbols}. -@item arglist-cont-nonempty -Subsequent argument list lines when at least one argument follows on -the same line as the arglist opening paren. @ref{Paren List Symbols}. -@item arglist-close -The solo close paren of an argument list. @ref{Paren List Symbols}. -@item stream-op -Lines continuing a stream operator (C++ only). @ref{Literal -Symbols}. @c @emph{FIXME!!! Can this not be moved somewhere better?} -@item inclass -The line is nested inside a class definition. @ref{Class Symbols}. -@item cpp-macro -The start of a preprocessor macro definition. @ref{Literal Symbols}. -@item cpp-define-intro -The first line inside a multiline preprocessor macro if -@code{c-syntactic-indentation-in-macros} is set. @ref{Multiline Macro -Symbols}. -@item cpp-macro-cont -All lines inside multiline preprocessor macros if -@code{c-syntactic-indentation-in-macros} is @code{nil}. -@ref{Multiline Macro Symbols}. -@item friend -A C++ friend declaration. @ref{Class Symbols}. -@item objc-method-intro -The first line of an Objective-C method definition. @ref{Objective-C -Method Symbols}. -@item objc-method-args-cont -Lines continuing an Objective-C method definition. @ref{Objective-C -Method Symbols}. -@item objc-method-call-cont -Lines continuing an Objective-C method call. @ref{Objective-C Method -Symbols}. -@item extern-lang-open -Brace that opens an @code{extern} block (e.g. @code{extern "C" -@{...@}}). @ref{External Scope Symbols}. -@item extern-lang-close -Brace that closes an @code{extern} block. @ref{External Scope -Symbols}. -@item inextern-lang -Analogous to @code{inclass} syntactic symbol, but used inside -@code{extern} blocks. @ref{External Scope Symbols}. -@item namespace-open -@itemx namespace-close -@itemx innamespace -These are analogous to the three @code{extern-lang} symbols above, but -are returned for C++ namespace blocks. @ref{External Scope Symbols}. -@item module-open -@itemx module-close -@itemx inmodule -Analogous to the above, but for CORBA IDL @code{module} blocks. -@ref{External Scope Symbols}. -@item composition-open -@itemx composition-close -@itemx incomposition -Analogous to the above, but for CORBA CIDL @code{composition} blocks. -@ref{External Scope Symbols}. -@item template-args-cont -C++ template argument list continuations. @ref{Class Symbols}. -@item inlambda -Analogous to @code{inclass} syntactic symbol, but used inside lambda -(i.e. anonymous) functions. Only used in Pike mode. @ref{Statement -Block Symbols}. -@item lambda-intro-cont -Lines continuing the header of a lambda function, i.e. between the -@code{lambda} keyword and the function body. Only used in Pike mode. -@ref{Statement Block Symbols}. -@item inexpr-statement -A statement block inside an expression. The gcc C and C++ extension -for this is recognized. It's also used for the special functions that -take a statement block as an argument in Pike. @ref{Statement Block -Symbols}. -@item inexpr-class -A class definition inside an expression. This is used for anonymous -classes in Java. It's also used for anonymous array initializers in -Java. @ref{Anonymous Class Symbol}. -@end table - -@menu -* Function Symbols:: -* Class Symbols:: -* Conditional Construct Symbols:: -* Switch Statement Symbols:: -* Brace List Symbols:: -* External Scope Symbols:: -* Paren List Symbols:: -* Literal Symbols:: -* Multiline Macro Symbols:: -* Objective-C Method Symbols:: -* Anonymous Class Symbol:: -* Statement Block Symbols:: -* K&R Symbols:: -@end menu - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Function Symbols, Class Symbols, Syntactic Symbols, Syntactic Symbols -@comment node-name, next, previous, up -@subsection Function Symbols -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -This example shows a typical function declaration. - -@example - 1: void - 2: swap( int& a, int& b ) - 3: @{ - 4: int tmp = a; - 5: a = b; - 6: b = tmp; - 7: int ignored = - 8: a + b; - 9: @} -@end example - -@ssindex topmost-intro -@ssindex topmost-intro-cont -@ssindex defun-open -@ssindex defun-close -@ssindex defun-block-intro -Line 1 shows a @code{topmost-intro} since it is the first line that -introduces a top-level construct. Line 2 is a continuation of the -top-level construct introduction so it has the syntax -@code{topmost-intro-cont}. Line 3 shows a @code{defun-open} since it is -the brace that opens a top-level function definition. Line 9 is the -corresponding -@code{defun-close} since it contains the brace that closes the top-level -function definition. Line 4 is a @code{defun-block-intro}, i.e. it is -the first line of a brace-block, enclosed in a -top-level function definition. - -@ssindex statement -@ssindex statement-cont -Lines 5, 6, and 7 are all given @code{statement} syntax since there -isn't much special about them. Note however that line 8 is given -@code{statement-cont} syntax since it continues the statement begun -on the previous line. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Class Symbols, Conditional Construct Symbols, Function Symbols, Syntactic Symbols -@comment node-name, next, previous, up -@subsection Class related Symbols -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -Here's an example which illustrates some C++ class syntactic symbols: - -@example - 1: class Bass - 2: : public Guitar, - 3: public Amplifiable - 4: @{ - 5: public: - 6: Bass() - 7: : eString( new BassString( 0.105 )), - 8: aString( new BassString( 0.085 )), - 9: dString( new BassString( 0.065 )), -10: gString( new BassString( 0.045 )) -11: @{ -12: eString.tune( 'E' ); -13: aString.tune( 'A' ); -14: dString.tune( 'D' ); -15: gString.tune( 'G' ); -16: @} -17: friend class Luthier; -18: @}; -@end example - -@ssindex class-open -@ssindex class-close -As in the previous example, line 1 has the @code{topmost-intro} syntax. -Here however, the brace that opens a C++ class definition on line 4 is -assigned the @code{class-open} syntax. Note that in C++, classes, -structs, and unions are essentially equivalent syntactically (and are -very similar semantically), so replacing the @code{class} keyword in the -example above with @code{struct} or @code{union} would still result in a -syntax of @code{class-open} for line 4 @footnote{This is the case even -for C and Objective-C. For consistency, structs in all supported -languages are syntactically equivalent to classes. Note however that -the keyword @code{class} is meaningless in C and Objective-C.}. -Similarly, line 18 is assigned @code{class-close} syntax. - -@ssindex inher-intro -@ssindex inher-cont -Line 2 introduces the inheritance list for the class so it is assigned -the @code{inher-intro} syntax, and line 3, which continues the -inheritance list is given @code{inher-cont} syntax. - -@ssindex access-label -@ssindex inclass -Hitting @kbd{C-c C-s} on line 5 shows the following analysis: - -@example -((inclass 58) (access-label 58)) -@end example - -@noindent -The primary syntactic symbol for this line is @code{access-label} as -this a label keyword that specifies access protection in C++. However, -because this line is also a top-level construct inside a class -definition, the analysis actually shows two syntactic symbols. The -other syntactic symbol assigned to this line is @code{inclass}. -Similarly, line 6 is given both @code{inclass} and @code{topmost-intro} -syntax: - -@example -((inclass 58) (topmost-intro 60)) -@end example - -@ssindex member-init-intro -@ssindex member-init-cont -Line 7 introduces a C++ member initialization list and as such is given -@code{member-init-intro} syntax. Note that in this case it is -@emph{not} assigned @code{inclass} since this is not considered a -top-level construct. Lines 8 through 10 are all assigned -@code{member-init-cont} since they continue the member initialization -list started on line 7. - -@cindex in-class inline methods -@ssindex inline-open -@ssindex inline-close -Line 11's analysis is a bit more complicated: - -@example -((inclass 58) (inline-open)) -@end example - -This line is assigned a syntax of both @code{inline-open} and -@code{inclass} because it opens an @dfn{in-class} C++ inline method -definition. This is distinct from, but related to, the C++ notion of an -inline function in that its definition occurs inside an enclosing class -definition, which in C++ implies that the function should be inlined. -However, if the definition of the @code{Bass} constructor appeared -outside the class definition, the construct would be given the -@code{defun-open} syntax, even if the keyword @code{inline} appeared -before the method name, as in: - -@example - 1: class Bass - 2: : public Guitar, - 3: public Amplifiable - 4: @{ - 5: public: - 6: Bass(); - 7: @}; - 8: - 9: inline -10: Bass::Bass() -11: : eString( new BassString( 0.105 )), -12: aString( new BassString( 0.085 )), -13: dString( new BassString( 0.065 )), -14: gString( new BassString( 0.045 )) -15: @{ -16: eString.tune( 'E' ); -17: aString.tune( 'A' ); -18: dString.tune( 'D' ); -19: gString.tune( 'G' ); -20: @} -@end example - -@ssindex friend -Returning to the previous example, line 16 is given @code{inline-close} -syntax, while line 12 is given @code{defun-block-open} syntax, and lines -13 through 15 are all given @code{statement} syntax. Line 17 is -interesting in that its syntactic analysis list contains three -elements: - -@example -((inclass 58) (topmost-intro 380) (friend)) -@end example - -The @code{friend} and @code{inline-open} syntactic symbols are -modifiers that do not have anchor positions. - -@ssindex template-args-cont -Template definitions introduce yet another syntactic symbol: - -@example - 1: ThingManager <int, - 2: Framework::Callback *, - 3: Mutex> 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<index; i++ ) - 4: @{ - 5: if( i == 10 ) - 6: do_something_special(); - 7: else - 8: silly_label: - 9: do_something( i ); -10: @} -11: do @{ -12: another_thing( i-- ); -13: @} -14: while( i > 0 ); -15: @} -@end example - -Only the lines that illustrate new syntactic symbols will be discussed. - -@ssindex substatement-open -@ssindex statement-block-intro -@ssindex block-close -Line 4 has a brace which opens a conditional's substatement block. It -is thus assigned @code{substatement-open} syntax, and since line 5 is -the first line in the substatement block, it is assigned -@code{statement-block-intro} syntax. Line 10 contains the brace -that closes the inner substatement block, and is therefore given the -syntax @code{block-close}@footnote{@code{block-open} is used only for -``free-standing'' blocks, and is somewhat rare (@pxref{Literal -Symbols} for an example.)}. Line 13 is treated the same way. - -@ssindex substatement -Lines 6 and 9 are also substatements of conditionals, but since they -don't start blocks they are given @code{substatement} syntax -instead of @code{substatement-open}. - -@ssindex substatement-label -Line 8 contains a label, which is normally given @code{label} syntax. -This one is however a bit special since it's between a conditional and -its substatement. It's analyzed as @code{substatement-label} to let you -handle this rather odd case differently from normal labels. - -@ssindex else-clause -@ssindex catch-clause -Line 7 start with an @code{else} that matches the @code{if} statement on -line 5. It is therefore given the @code{else-clause} syntax and is -anchored on the matching @code{if}. The @code{try}-@code{catch} -constructs in C++ and Java are treated this way too, except that -@code{catch} and (in Java) @code{finally}, are marked with -@code{catch-clause}. - -@ssindex do-while-closure -The @code{while} construct on line 14 that closes a @code{do} -conditional is given the special syntax @code{do-while-closure} if it -appears on a line by itself. Note that if the @code{while} appeared on -the same line as the preceding close brace, that line would still have -@code{block-close} syntax. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Switch Statement Symbols, Brace List Symbols, Conditional Construct Symbols, Syntactic Symbols -@comment node-name, next, previous, up -@subsection Switch Statement Symbols -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -Switch statements have their own set of syntactic symbols. Here's an -example: - -@example - 1: void spam( enum Ingredient i ) - 2: @{ - 3: switch( i ) @{ - 4: case Ham: - 5: be_a_pig(); - 6: break; - 7: case Salt: - 8: drink_some_water(); - 9: break; -10: default: -11: @{ -12: what_is_it(); -13: break; -14: @} -15: @} -14: @} -@end example - -@ssindex case-label -@ssindex statement-case-intro -@ssindex statement-case-open -Here, lines 4, 7, and 10 are all assigned @code{case-label} syntax, -while lines 5 and 8 are assigned @code{statement-case-intro}. Line 11 -is treated slightly differently since it contains a brace that opens a -block --- it is given @code{statement-case-open} syntax. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Brace List Symbols, External Scope Symbols, Switch Statement Symbols, Syntactic Symbols -@comment node-name, next, previous, up -@subsection Brace List Symbols -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@cindex brace lists -There are a set of syntactic symbols that are used to recognize -constructs inside of brace lists. A brace list is defined as an -@code{enum} or aggregate initializer list, such as might statically -initialize an array of structs. The three special aggregate constructs -in Pike, @code{(@{ @})}, @code{([ ])} and @code{(< >)}, are treated as -brace lists too. An example: - -@example - 1: static char* ingredients[] = - 2: @{ - 3: "Ham", - 4: "Salt", - 5: NULL - 6: @}; -@end example - -@ssindex brace-list-open -@ssindex brace-list-intro -@ssindex brace-list-close -@ssindex brace-list-entry -Following convention, line 2 in this example is assigned -@code{brace-list-open} syntax, and line 3 is assigned -@code{brace-list-intro} syntax. Likewise, line 6 is assigned -@code{brace-list-close} syntax. Lines 4 and 5 however, are assigned -@code{brace-list-entry} syntax, as would all subsequent lines in this -initializer list. - -@ssindex brace-entry-open -Your static initializer might be initializing nested structures, for -example: - -@example - 1: struct intpairs[] = - 2: @{ - 3: @{ 1, 2 @}, - 4: @{ - 5: 3, - 6: 4 - 7: @} - 8: @{ 1, - 9: 2 @}, -10: @{ 3, 4 @} -11: @}; -@end example - -Here, you've already seen the analysis of lines 1, 2, 3, and 11. On -line 4, things get interesting; this line is assigned -@code{brace-entry-open} syntactic symbol because it's a bracelist entry -line that starts with an open brace. Lines 5 and 6 (and line 9) are -pretty standard, and line 7 is a @code{brace-list-close} as you'd -expect. Once again, line 8 is assigned as @code{brace-entry-open} as is -line 10. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node External Scope Symbols, Paren List Symbols, Brace List Symbols, Syntactic Symbols -@comment node-name, next, previous, up -@subsection External Scope Symbols -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -External language definition blocks also have their own syntactic -symbols. In this example: - -@example - 1: extern "C" - 2: @{ - 3: int thing_one( int ); - 4: int thing_two( double ); - 5: @} -@end example - -@ssindex extern-lang-open -@ssindex extern-lang-close -@ssindex inextern-lang -@ssindex inclass -@noindent -line 2 is given the @code{extern-lang-open} syntax, while line 5 is given -the @code{extern-lang-close} syntax. The analysis for line 3 yields: - -@example -((inextern-lang) (topmost-intro 14)) -@end example - -@noindent -where @code{inextern-lang} is a modifier similar in purpose to -@code{inclass}. - -There are various other top level blocks like @code{extern}, and they -are all treated in the same way except that the symbols are named after -the keyword that introduces the block. E.g. C++ namespace blocks get -the three symbols @code{namespace-open}, @code{namespace-close} and -@code{innamespace}. The currently recognized top level blocks are: - -@table @asis -@item @code{extern-lang-open}, @code{extern-lang-close}, @code{inextern-lang} -@code{extern} blocks in C and C++.@footnote{These should logically be -named @code{extern-open}, @code{extern-close} and @code{inextern}, but -that isn't the case for historical reasons.} - -@item @code{namespace-open}, @code{namespace-close}, @code{innamespace} -@ssindex namespace-open -@ssindex namespace-close -@ssindex innamespace -@code{namespace} blocks in C++. - -@item @code{module-open}, @code{module-close}, @code{inmodule} -@ssindex module-open -@ssindex module-close -@ssindex inmodule -@code{module} blocks in CORBA IDL. - -@item @code{composition-open}, @code{composition-close}, @code{incomposition} -@ssindex composition-open -@ssindex composition-close -@ssindex incomposition -@code{composition} blocks in CORBA CIDL. -@end table - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Paren List Symbols, Literal Symbols, External Scope Symbols, Syntactic Symbols -@comment node-name, next, previous, up -@subsection Parenthesis (Argument) List Symbols -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -A number of syntactic symbols are associated with parenthesis lists, -a.k.a argument lists, as found in function declarations and function -calls. This example illustrates these: - -@example - 1: void a_function( int line1, - 2: int line2 ); - 3: - 4: void a_longer_function( - 5: int line1, - 6: int line2 - 7: ); - 8: - 9: void call_them( int line1, int line2 ) -10: @{ -11: a_function( -12: line1, -13: line2 -14: ); -15: -16: a_longer_function( line1, -17: line2 ); -18: @} -@end example - -@ssindex arglist-intro -@ssindex arglist-close -Lines 5 and 12 are assigned @code{arglist-intro} syntax since they are -the first line following the open parenthesis, and lines 7 and 14 are -assigned @code{arglist-close} syntax since they contain the parenthesis -that closes the argument list. - -@ssindex arglist-cont-nonempty -@ssindex arglist-cont -Lines that continue argument lists can be assigned one of two syntactic -symbols. For example, Lines 2 and 17 -are assigned @code{arglist-cont-nonempty} syntax. What this means -is that they continue an argument list, but that the line containing the -parenthesis that opens the list is @emph{not empty} following the open -parenthesis. Contrast this against lines 6 and 13 which are assigned -@code{arglist-cont} syntax. This is because the parenthesis that opens -their argument lists is the last character on that line. - -Syntactic elements with @code{arglist-intro}, -@code{arglist-cont-nonempty}, and @code{arglist-close} contain two -buffer positions: the anchor position (the beginning of the -declaration or statement) and the position of the open parenthesis. -The latter position can be used in a line-up function (@pxref{Line-Up -Functions}). - -Note that there is no @code{arglist-open} syntax. This is because any -parenthesis that opens an argument list, appearing on a separate line, -is assigned the @code{statement-cont} syntax instead. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Literal Symbols, Multiline Macro Symbols, Paren List Symbols, Syntactic Symbols -@comment node-name, next, previous, up -@subsection Comment String Label and Macro Symbols -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -A few miscellaneous syntactic symbols that haven't been previously -covered are illustrated by this C++ example: - -@example - 1: void Bass::play( int volume ) - 2: const - 3: @{ - 4: /* this line starts a multiline - 5: * comment. This line should get `c' syntax */ - 6: - 7: char* a_multiline_string = "This line starts a multiline \ - 8: string. This line should get `string' syntax."; - 9: -10: note: -11: @{ -12: #ifdef LOCK -13: Lock acquire(); -14: #endif // LOCK -15: slap_pop(); -16: cout << "I played " -17: << "a note\n"; -18: @} -19: @} -@end example - -The lines to note in this example include: - -@itemize @bullet -@item -@ssindex func-decl-cont -Line 2 is assigned the @code{func-decl-cont} syntax. - -@item -@ssindex comment-intro -Line 4 is assigned both @code{defun-block-intro} @emph{and} -@code{comment-intro} syntax. A syntactic element with -@code{comment-intro} has no anchor point --- It is always accompanied -by another syntactic element which does have one. - -@item -@ssindex c -Line 5 is assigned @code{c} syntax. - -@item -@cindex syntactic whitespace -Line 6 which, even though it contains nothing but whitespace, is -assigned @code{defun-block-intro}. Note that the appearance of the -comment on lines 4 and 5 do not cause line 6 to be assigned -@code{statement} syntax because comments are considered to be -@dfn{syntactic whitespace}, which are ignored when analyzing -code. - -@item -@ssindex string -Line 8 is assigned @code{string} syntax. - -@item -@ssindex label -Line 10 is assigned @code{label} syntax. - -@item -@ssindex block-open -Line 11 is assigned @code{block-open} as well as @code{statement} -syntax. A @code{block-open} syntactic element doesn't have an anchor -position, since it always appears with another syntactic element which -does have one. - -@item -@ssindex cpp-macro -Lines 12 and 14 are assigned @code{cpp-macro} syntax in addition to the -normal syntactic symbols (@code{statement-block-intro} and -@code{statement}, respectively). Normally @code{cpp-macro} is -configured to cancel out the normal syntactic context to make all -preprocessor directives stick to the first column, but that's easily -changed if you want preprocessor directives to be indented like the rest -of the code. Like @code{comment-intro}, a syntactic element with -@code{cpp-macro} doesn't contain an anchor position. - -@item -@ssindex stream-op -Line 17 is assigned @code{stream-op} syntax. -@end itemize - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Multiline Macro Symbols, Objective-C Method Symbols, Literal Symbols, Syntactic Symbols -@comment node-name, next, previous, up -@subsection Multiline Macro Symbols -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@cindex multiline macros -@cindex syntactic whitespace -@ssindex cpp-define-intro -@ssindex cpp-macro-cont -Multiline preprocessor macro definitions are normally handled just like -other code, i.e. the lines inside them are indented according to the -syntactic analysis of the preceding lines inside the macro. The first -line inside a macro definition (i.e. the line after the starting line of -the cpp directive itself) gets @code{cpp-define-intro}. In this example: - -@example - 1: #define LIST_LOOP(cons, listp) \ - 2: for (cons = listp; !NILP (cons); cons = XCDR (cons)) \ - 3: if (!CONSP (cons)) \ - 4: signal_error ("Invalid list format", listp); \ - 5: else -@end example - -@noindent -line 1 is given the syntactic symbol @code{cpp-macro}. The first line -of a cpp directive is always given that symbol. Line 2 is given -@code{cpp-define-intro}, so that you can give the macro body as a whole -some extra indentation. Lines 3 through 5 are then analyzed as normal -code, i.e. @code{substatement} on lines 3 and 4, and @code{else-clause} -on line 5. - -The syntactic analysis inside macros can be turned off with -@code{c-syntactic-indentation-in-macros} (@pxref{Custom Macros}). In -that case, lines 2 through 5 would all be given @code{cpp-macro-cont} -with an anchor position pointing to the @code{#} which starts the cpp -directive@footnote{This is how @ccmode{} 5.28 and earlier analyzed -macros.}. - -@xref{Custom Macros}, for more info about the treatment of macros. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Objective-C Method Symbols, Anonymous Class Symbol, Multiline Macro Symbols, Syntactic Symbols -@comment node-name, next, previous, up -@subsection Objective-C Method Symbols -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -In Objective-C buffers, there are three additional syntactic symbols -assigned to various message calling constructs. Here's an example -illustrating these: - -@example - 1: - (void)setDelegate:anObject - 2: withStuff:stuff - 3: @{ - 4: [delegate masterWillRebind:self - 5: toDelegate:anObject - 6: withExtraStuff:stuff]; - 7: @} -@end example - -@ssindex objc-method-intro -@ssindex objc-method-args-cont -@ssindex objc-method-call-cont -Here, line 1 is assigned @code{objc-method-intro} syntax, and line 2 is -assigned @code{objc-method-args-cont} syntax. Lines 5 and 6 are both -assigned @code{objc-method-call-cont} syntax. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Anonymous Class Symbol, Statement Block Symbols, Objective-C Method Symbols, Syntactic Symbols -@comment node-name, next, previous, up -@subsection Anonymous Class Symbol (Java) -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -Java has a concept of anonymous classes which can look something like -this: - -@example - 1: public void watch(Observable o) @{ - 2: o.addObserver(new Observer() @{ - 3: public void update(Observable o, Object arg) @{ - 4: history.addElement(arg); - 5: @} - 6: @}); - 7: @} -@end example - -@ssindex inexpr-class -The brace following the @code{new} operator opens the anonymous class. -Lines 3 and 6 are assigned the @code{inexpr-class} syntax, besides the -@code{inclass} symbol used in normal classes. Thus, the class will be -indented just like a normal class, with the added indentation given to -@code{inexpr-class}. An @code{inexpr-class} syntactic element doesn't -have an anchor position. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Statement Block Symbols, K&R Symbols, Anonymous Class Symbol, Syntactic Symbols -@comment node-name, next, previous, up -@subsection Statement Block Symbols -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -There are a few occasions where a statement block might be used inside -an expression. One is in C or C++ code using the gcc extension for -this, e.g: - -@example - 1: int res = (@{ - 2: int y = foo (); int z; - 3: if (y > 0) z = y; else z = - y; - 4: z; - 5: @}); -@end example - -@ssindex inexpr-statement -Lines 2 and 5 get the @code{inexpr-statement} syntax, besides the -symbols they'd get in a normal block. Therefore, the indentation put on -@code{inexpr-statement} is added to the normal statement block -indentation. An @code{inexpr-statement} syntactic element doesn't -contain an anchor position. - -In Pike code, there are a few other situations where blocks occur inside -statements, as illustrated here: - -@example - 1: array itgob() - 2: @{ - 3: string s = map (backtrace()[-2][3..], - 4: lambda - 5: (mixed arg) - 6: @{ - 7: return sprintf ("%t", arg); - 8: @}) * ", " + "\n"; - 9: return catch @{ -10: write (s + "\n"); -11: @}; -12: @} -@end example - -@ssindex inlambda -@ssindex lambda-intro-cont -Lines 4 through 8 contain a lambda function, which @ccmode{} recognizes -by the @code{lambda} keyword. If the function argument list is put -on a line of its own, as in line 5, it gets the @code{lambda-intro-cont} -syntax. The function body is handled as an inline method body, with the -addition of the @code{inlambda} syntactic symbol. This means that line -6 gets @code{inlambda} and @code{inline-open}, and line 8 gets -@code{inline-close}@footnote{You might wonder why it doesn't get -@code{inlambda} too. It's because the closing brace is relative to the -opening brace, which stands on its own line in this example. If the -opening brace was hanging on the previous line, then the closing brace -would get the @code{inlambda} syntax too to be indented correctly.}. - -@ssindex inexpr-statement -On line 9, @code{catch} is a special function taking a statement block -as its argument. The block is handled as an in-expression statement -with the @code{inexpr-statement} syntax, just like the gcc extended C -example above. The other similar special function, @code{gauge}, is -handled like this too. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node K&R Symbols, , Statement Block Symbols, Syntactic Symbols -@comment node-name, next, previous, up -@subsection K&R Symbols -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@ssindex knr-argdecl-intro -@ssindex knr-argdecl -Two other syntactic symbols can appear in old style, non-prototyped C -code @footnote{a.k.a. K&R C, or Kernighan & Ritchie C}: - -@example - 1: int add_three_integers(a, b, c) - 2: int a; - 3: int b; - 4: int c; - 5: @{ - 6: return a + b + c; - 7: @} -@end example - -Here, line 2 is the first line in an argument declaration list and so is -given the @code{knr-argdecl-intro} syntactic symbol. Subsequent lines -(i.e. lines 3 and 4 in this example), are given @code{knr-argdecl} -syntax. - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Indentation Calculation, , Syntactic Symbols, Indentation Engine Basics -@comment node-name, next, previous, up -@section Indentation Calculation -@cindex indentation -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -Indentation for a line is calculated from the syntactic context -(@pxref{Syntactic Analysis}). - -First, a buffer position is found whose column will be the base for the -indentation calculation. It's the anchor position in the first -syntactic element that provides one that is used. If no syntactic -element has an anchor position then column zero is used. - -Second, the syntactic symbols in each syntactic element are looked up -in the @code{c-offsets-alist} style variable -(@pxref{c-offsets-alist}), which is an association list of syntactic -symbols and the offsets to apply for those symbols. These offsets are -added together with the base column to produce the new indentation -column. - -Let's use our two code examples above to see how this works. Here is -our first example again: - -@example - 1: void swap( int& a, int& b ) - 2: @{ - 3: int tmp = a; - 4: a = b; - 5: b = tmp; - 6: @} -@end example - -Let's say point is on line 3 and we hit the @key{TAB} key to reindent -the line. The syntactic context for that line is: - -@example -((defun-block-intro 29)) -@end example - -@noindent -Since buffer position 29 is the first and only anchor position in the -list, @ccmode{} goes there and asks for the current column. This brace -is in column zero, so @ccmode{} uses @samp{0} as the base column. - -Next, @ccmode{} looks up @code{defun-block-intro} in the -@code{c-offsets-alist} style variable. Let's say it finds the value -@samp{4}; it adds this to the base column @samp{0}, yielding a running -total indentation of 4 spaces. - -Since there is only one syntactic element on the list for this line, -indentation calculation is complete, and the total indentation for the -line is 4 spaces. - -Here's another example: - -@example - 1: int add( int val, int incr, int doit ) - 2: @{ - 3: if( doit ) - 4: @{ - 5: return( val + incr ); - 6: @} - 7: return( val ); - 8: @} -@end example - -If we were to hit @kbd{TAB} on line 4 in the above example, the same -basic process is performed, despite the differences in the syntactic -context. The context for this line is: - -@example -((substatement-open 46)) -@end example - -Here, @ccmode{} goes to buffer position 46, which is the @samp{i} in -@code{if} on line 3. This character is in the fourth column on that -line so the base column is @samp{4}. Then @ccmode{} looks up the -@code{substatement-open} symbol in @code{c-offsets-alist}. Let's say it -finds the value @samp{4}. It's added with the base column and yields an -indentation for the line of 8 spaces. - -Simple, huh? - -Actually, it's a bit more complicated than that since the entries on -@code{c-offsets-alist} can be much more than plain offsets. -@xref{c-offsets-alist}, for the full story. - -Anyway, the mode usually just does The Right Thing without you having to -think about it in this much detail. But when customizing indentation, -it's helpful to understand the general indentation model being used. - -As you configure @ccmode{}, you might want to set the variable -@code{c-echo-syntactic-information-p} to non-@code{nil} so that the -syntactic context and calculated offset always is echoed in the -minibuffer when you hit @kbd{TAB}. - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Customizing Indentation, Custom Macros, Indentation Engine Basics, Top -@comment node-name, next, previous, up -@chapter Customizing Indentation -@cindex customization, indentation -@cindex indentation -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -The principal variable for customizing indentation is the style -variable @code{c-offsets-alist}, which gives an @dfn{offset} (an -indentation rule) for each syntactic symbol. Its structure and -semantics are completely described in @ref{c-offsets-alist}. The -various ways you can set the variable, including the use of the -@ccmode{} style system, are described in @ref{Config Basics} and its -sections, in particular @ref{Style Variables}. - -The simplest and most used kind of ``offset'' setting in -@code{c-offsets-alist} is in terms of multiples of -@code{c-basic-offset}: - -@defopt c-basic-offset -@vindex basic-offset (c-) -This style variable holds the basic offset between indentation levels. -It's factory default is 4, but all the built-in styles set it -themselves, to some value between 2 (for @code{gnu} style) and 8 (for -@code{bsd}, @code{linux}, and @code{python} styles). -@end defopt - -The most flexible ``offset'' setting you can make in -@code{c-offsets-alist} is a line-up function (or even a list of them), -either one supplied by @ccmode{} (@pxref{Line-Up Functions}) or one -you write yourself (@pxref{Custom Line-Up}). - -Finally, in @ref{Other Indentation} you'll find the tool of last -resort: a hook which is called after a line has been indented. You -can install functions here to make ad-hoc adjustments to any line's -indentation. - -@menu -* c-offsets-alist:: -* Interactive Customization:: -* Line-Up Functions:: -* Custom Line-Up:: -* Other Indentation:: -@end menu - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node c-offsets-alist, Interactive Customization, Customizing Indentation, Customizing Indentation -@comment node-name, next, previous, up -@section c-offsets-alist -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -This section explains the structure and semantics of the style -variable @code{c-offset-alist}, the principal variable for configuring -indentation. Details of how to set it up, and its relationship to -@ccmode{}'s style system are given in @ref{Style Variables}. - -@defopt c-offsets-alist -@vindex offsets-alist (c-) -This is an alist which associates an offset with each syntactic -symbol. This @dfn{offset} is a rule specifying how to indent a line -whose syntactic context matches the symbol. @xref{Syntactic -Analysis}. - -Note that the buffer-local binding of this alist in a @ccmode{} buffer -contains an entry for @emph{every} syntactic symbol. Its global -binding and its settings within style specifications usually contain -only a few entries. @xref{Style Variables}. - -The offset specification associated with any particular syntactic -symbol can be an integer, a variable name, a vector, a function or -lambda expression, a list, or one of the following special symbols: -@code{+}, @code{-}, @code{++}, @code{--}, @code{*}, or @code{/}. The -meanings of these values are described in detail below. - -Here is an example fragment of a @code{c-offsets-alist}, showing some -of these kinds of offsets: - -@example -((statement . 0) - (substatement . +) - (cpp-macro . [0]) - (topmost-intro-cont . c-lineup-topmost-intro-cont) - (statement-block-intro . (add c-lineup-whitesmith-in-block - c-indent-multi-line-block)) - @dots{} -@*) -@end example -@end defopt - -@deffn Command c-set-offset (@kbd{C-c C-o}) -@findex set-offset (c-) -@kindex C-c C-o -This command changes the entry for a syntactic symbol in the current -binding of @code{c-offsets-alist}, or it inserts a new entry if there -isn't already one for that syntactic symbol. - -You can use @code{c-set-offsets} interactively within a @ccmode{} -buffer to make experimental changes to your indentation settings. -@kbd{C-c C-o} prompts you for the syntactic symbol to change -(defaulting to that of the current line) and the new offset -(defaulting to the current offset). - -@code{c-set-offsets} takes two arguments when used programmatically: -@var{symbol}, the syntactic element symbol to change and @var{offset}, -the new offset for that syntactic element. You can call the command -in your @file{.emacs} to change the global binding of -@code{c-offsets-alist} (@pxref{Style Variables}); you can use it in a -hook function to make changes from the current style. @ccmode{} -itself uses this function when initializing styles. -@end deffn - -@cindex offset specification -The ``offset specifications'' in @code{c-offsets-alist} can be any of -the following: - -@table @asis -@item An integer -The integer specifies a relative offset. All relative -offsets@footnote{The syntactic context @code{@w{((defun-block-intro -2724) (comment-intro))}} would likely have two relative offsets.} will -be added together and used to calculate the indentation relative to an -anchor position earlier in the buffer. @xref{Indentation -Calculation}, for details. Most of the time, it's probably better to -use one of the special symbols like @code{+} than an integer (apart -from zero). - -@item One of the symbols @code{+}, @code{-}, @code{++}, @code{--}, @code{*}, or @code{/} -These special symbols describe a relative offset in multiples of -@code{c-basic-offset}: - -By defining a style's indentation in terms of @code{c-basic-offset}, -you can change the amount of whitespace given to an indentation level -while maintaining the same basic shape of your code. Here are the -values that the special symbols correspond to: - -@table @code -@item + -@code{c-basic-offset} times 1 -@item - -@code{c-basic-offset} times -1 -@item ++ -@code{c-basic-offset} times 2 -@item -- -@code{c-basic-offset} times -2 -@item * -@code{c-basic-offset} times 0.5 -@item / -@code{c-basic-offset} times -0.5 -@end table - -@item A vector -The first element of the vector, an integer, sets the absolute -indentation column. This will override any previously calculated -indentation, but won't override relative indentation calculated from -syntactic elements later on in the syntactic context of the line being -indented. @xref{Indentation Calculation}. Any elements in the vector -beyond the first will be ignored. - -@item A function or lambda expression -The function will be called and its return value will in turn be -evaluated as an offset specification. Functions are useful when more -context than just the syntactic symbol is needed to get the desired -indentation. @xref{Line-Up Functions}, and @ref{Custom Line-Up}, for -details about them. - -@item A symbol with a variable binding -If the symbol also has a function binding, the function takes -precedence over the variable. Otherwise the value of the variable is -used. It must be an integer (which is used as relative offset) or a -vector (an absolute offset). - -@item A list -The offset can also be a list containing several offset -specifications; these are evaluated recursively and combined. A list -is typically only useful when some of the offsets are line-up -functions. A common strategy is calling a sequence of functions in -turn until one of them recognizes that it is appropriate for the -source line and returns a non-@code{nil} value. - -@code{nil} values are always ignored when the offsets are combined. -The first element of the list specifies the method of combining the -non-@code{nil} offsets from the remaining elements: - -@table @code -@item first -Use the first offset that doesn't evaluate to @code{nil}. Subsequent -elements of the list don't get evaluated. -@item min -Use the minimum of all the offsets. All must be either relative or -absolute - they can't be mixed. -@item max -Use the maximum of all the offsets. All must be either relative or -absolute - they can't be mixed. -@item add -Add all the evaluated offsets together. Exactly one of them may be -absolute, in which case the result is absolute. Any relative offsets -that preceded the absolute one in the list will be ignored in that case. -@end table - -As a compatibility measure, if the first element is none of the above -then it too will be taken as an offset specification and the whole list -will be combined according to the method @code{first}. -@end table - -@vindex c-strict-syntax-p -@vindex strict-syntax-p (c-) -If an offset specification evaluates to @code{nil}, then a relative -offset of 0 (zero) is used@footnote{There is however a variable -@code{c-strict-syntax-p} that when set to non-@code{nil} will cause an -error to be signaled in that case. It's now considered obsolete since -it doesn't work well with some of the alignment functions that return -@code{nil} instead of zero. You should therefore leave -@code{c-strict-syntax-p} set to @code{nil}.}. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Interactive Customization, Line-Up Functions, c-offsets-alist, Customizing Indentation -@comment node-name, next, previous, up -@section Interactive Customization -@cindex customization, interactive -@cindex interactive customization -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -As an example of how to customize indentation, let's change the -style of this example@footnote{In this and subsequent examples, the -original code is formatted using the @samp{gnu} style unless otherwise -indicated. @xref{Styles}.}: - -@example -@group - 1: int add( int val, int incr, int doit ) - 2: @{ - 3: if( doit ) - 4: @{ - 5: return( val + incr ); - 6: @} - 7: return( val ); - 8: @} -@end group -@end example - -@noindent -to: - -@example -@group - 1: int add( int val, int incr, int doit ) - 2: @{ - 3: if( doit ) - 4: @{ - 5: return( val + incr ); - 6: @} - 7: return( val ); - 8: @} -@end group -@end example - -In other words, we want to change the indentation of braces that open a -block following a condition so that the braces line up under the -conditional, instead of being indented. Notice that the construct we -want to change starts on line 4. To change the indentation of a line, -we need to see which syntactic symbols affect the offset calculations -for that line. Hitting @kbd{C-c C-s} on line 4 yields: - -@example -((substatement-open 44)) -@end example - -@noindent -so we know that to change the offset of the open brace, we need to -change the indentation for the @code{substatement-open} syntactic -symbol. - -To do this interactively, just hit @kbd{C-c C-o}. This prompts -you for the syntactic symbol to change, providing a reasonable default. -In this case, the default is @code{substatement-open}, which is just the -syntactic symbol we want to change! - -After you hit return, @ccmode{} will then prompt you for the new -offset value, with the old value as the default. The default in this -case is @samp{+}, but we want no extra indentation so enter -@samp{0} and @kbd{RET}. This will associate the offset 0 with the -syntactic symbol @code{substatement-open}. - -To check your changes quickly, just hit @kbd{C-c C-q} -(@code{c-indent-defun}) to reindent the entire function. The example -should now look like: - -@example -@group - 1: int add( int val, int incr, int doit ) - 2: @{ - 3: if( doit ) - 4: @{ - 5: return( val + incr ); - 6: @} - 7: return( val ); - 8: @} -@end group -@end example - -Notice how just changing the open brace offset on line 4 is all we -needed to do. Since the other affected lines are indented relative to -line 4, they are automatically indented the way you'd expect. For more -complicated examples, this might not always work. The general approach -to take is to always start adjusting offsets for lines higher up in the -file, then reindent and see if any following lines need further -adjustments. - -@c Move this bit to "Styles" (2005/10/7) -@deffn Command c-set-offset symbol offset -@findex set-offset (c-) -@kindex C-c C-o -This is the command bound to @kbd{C-c C-o}. It provides a convenient -way to set offsets on @code{c-offsets-alist} both interactively (see -the example above) and from your mode hook. - -It takes two arguments when used programmatically: @var{symbol} is the -syntactic element symbol to change and @var{offset} is the new offset -for that syntactic element. -@end deffn -@c End of MOVE THIS BIT. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Line-Up Functions, Custom Line-Up, Interactive Customization, Customizing Indentation -@comment node-name, next, previous, up -@section Line-Up Functions -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@cindex line-up function -@cindex indentation function -Often there are cases when a simple offset setting on a syntactic -symbol isn't enough to get the desired indentation---for example, you -might want to line up a closing parenthesis with the matching opening -one rather than indenting relative to its ``anchor point''. @ccmode{} -provides this flexibility with @dfn{line-up functions}. - -The way you associate a line-up function with a syntactic symbol is -described in @ref{c-offsets-alist}. @ccmode{} comes with many -predefined line-up functions for common situations. If none of these -does what you want, you can write your own. @xref{Custom Line-Up}. -Sometimes, it is easier to tweak the standard indentation by adding a -function to @code{c-special-indent-hook} (@pxref{Other Indentation}). - -The line-up functions haven't been adapted for AWK buffers or tested -with them. Some of them might work serendipitously. There shouldn't be -any problems writing custom line-up functions for AWK mode. - -The calling convention for line-up functions is described fully in -@ref{Custom Line-Up}. Roughly speaking, the return value is either an -offset itself (such as @code{+} or @code{[0]}) or it's @code{nil}, -meaning ``this function is inappropriate in this case - try a -different one''. @xref{c-offsets-alist}. - -The subsections below describe all the standard line-up functions, -categorized by the sort of token the lining-up centers around. For -each of these functions there is a ``works with'' list that indicates -which syntactic symbols the function is intended to be used with. - -@macro workswith -@emph{Works with:@ } -@end macro -@ifinfo -@unmacro workswith -@macro workswith -Works with: -@end macro -@end ifinfo - -@macro sssTBasicOffset -<--> @i{c-basic-offset}@c -@end macro - -@macro sssTsssTBasicOffset -<--><--> @i{c-basic-offset}@c -@end macro - -@macro hereFn{func} -<- @i{\func\}@c -@end macro - -@c The TeX backend seems to insert extra spaces around the argument. :P -@iftex -@unmacro hereFn -@macro hereFn{func} -<-@i{\func\}@c -@end macro -@end iftex - -@menu -* Brace/Paren Line-Up:: -* List Line-Up:: -* Operator Line-Up:: -* Comment Line-Up:: -* Misc Line-Up:: -@end menu - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Brace/Paren Line-Up, List Line-Up, Line-Up Functions, Line-Up Functions -@comment node-name, next, previous, up -@subsection Brace and Parenthesis Line-Up Functions -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -The line-up functions here calculate the indentation for braces, -parentheses and statements within brace blocks. - -@defun c-lineup-close-paren -@findex lineup-close-paren (c-) -Line up the closing paren under its corresponding open paren if the -open paren is followed by code. If the open paren ends its line, no -indentation is added. E.g: - -@example -@group -main (int, - char ** - ) @hereFn{c-lineup-close-paren} -@end group -@end example - -@noindent -and - -@example -@group -main ( - int, char ** -) @hereFn{c-lineup-close-paren} -@end group -@end example - -As a special case, if a brace block is opened at the same line as the -open parenthesis of the argument list, the indentation is -@code{c-basic-offset} instead of the open paren column. See -@code{c-lineup-arglist} for further discussion of this ``DWIM'' measure. - -@workswith All @code{*-close} symbols. -@end defun - -@comment ------------------------------------------------------------ - -@anchor{c-lineup-arglist-close-under-paren} -@defun c-lineup-arglist-close-under-paren -@findex lineup-arglist-close-under-paren (c-) -Set your @code{arglist-close} syntactic symbol to this line-up function -so that parentheses that close argument lists will line up under the -parenthesis that opened the argument list. It can also be used with -@code{arglist-cont} and @code{arglist-cont-nonempty} to line up all -lines inside a parenthesis under the open paren. - -As a special case, if a brace block is opened at the same line as the -open parenthesis of the argument list, the indentation is -@code{c-basic-offset} only. See @code{c-lineup-arglist} for further -discussion of this ``DWIM'' measure. - -@workswith Almost all symbols, but are typically most useful on -@code{arglist-close}, @code{brace-list-close}, @code{arglist-cont} and -@code{arglist-cont-nonempty}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-indent-one-line-block -@findex indent-one-line-block (c-) -Indent a one line block @code{c-basic-offset} extra. E.g: - -@example -@group -if (n > 0) - @{m+=n; n=0;@} @hereFn{c-indent-one-line-block} -@sssTBasicOffset{} -@end group -@end example - -@noindent -and - -@example -@group -if (n > 0) -@{ @hereFn{c-indent-one-line-block} - m+=n; n=0; -@} -@end group -@end example - -The block may be surrounded by any kind of parenthesis characters. -@code{nil} is returned if the line doesn't start with a one line block, -which makes the function usable in list expressions. - -@workswith Almost all syntactic symbols, but most useful on the -@code{-open} symbols. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-indent-multi-line-block -@findex indent-multi-line-block (c-) -Indent a multiline block @code{c-basic-offset} extra. E.g: - -@example -@group -int *foo[] = @{ - NULL, - @{17@}, @hereFn{c-indent-multi-line-block} -@end group -@end example - -@noindent -and - -@example -@group -int *foo[] = @{ - NULL, - @{ @hereFn{c-indent-multi-line-block} - 17 - @}, - @sssTBasicOffset{} -@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 multiline -block, which makes the function usable in list expressions. - -@workswith Almost all syntactic symbols, but most useful on the -@code{-open} symbols. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-runin-statements -@findex lineup-runin-statements (c-) -Line up statements for coding standards which place the first statement -in a block on the same line as the block opening brace@footnote{Run-in -style doesn't really work too well. You might need to write your own -custom line-up functions to better support this style.}. E.g: - -@example -@group -int main() -@{ puts ("Hello!"); - return 0; @hereFn{c-lineup-runin-statements} -@} -@end group -@end example - -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. -@end defun - -@comment ------------------------------------------------------------ - -@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. - -@workswith @code{inlambda}, @code{inexpr-statement}, -@code{inexpr-class}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-after-whitesmith-blocks -@findex lineup-after-whitesmith-blocks (c-) -Compensate for Whitesmith style indentation of blocks. Due to the way -@ccmode{} calculates anchor positions for normal lines inside blocks, -this function is necessary for those lines to get correct Whitesmith -style indentation. Consider the following examples: - -@example -@group -int foo() - @{ - a; - x; @hereFn{c-lineup-after-whitesmith-blocks} -@end group -@end example - -@example -@group -int foo() - @{ - @{ - a; - @} - x; @hereFn{c-lineup-after-whitesmith-blocks} -@end group -@end example - -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. - -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}. - -@workswith @code{brace-list-entry}, @code{brace-entry-open}, -@code{statement}, @code{arglist-cont}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-whitesmith-in-block -@findex lineup-whitesmith-in-block (c-) -Line up lines inside a block in Whitesmith style. It's done in a way -that works both when the opening brace hangs and when it doesn't. E.g: - -@example -@group -something - @{ - foo; @hereFn{c-lineup-whitesmith-in-block} - @} -@end group -@end example - -@noindent -and - -@example -@group -something @{ - foo; @hereFn{c-lineup-whitesmith-in-block} - @} -@sssTBasicOffset{} -@end group -@end example - -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 List Line-Up, Operator Line-Up, Brace/Paren Line-Up, Line-Up Functions -@comment node-name, next, previous, up -@subsection List Line-Up Functions -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -The line-up functions here calculate the indentation for lines which -form lists of items, usually separated by commas. - -The function @ref{c-lineup-arglist-close-under-paren}, which is mainly -for indenting a close parenthesis, is also useful for the lines -contained within parentheses. - -@defun c-lineup-arglist -@findex lineup-arglist (c-) -Line up the current argument line under the first argument. - -As a special case, if an argument on the same line as the open -parenthesis starts with a brace block opener, the indentation is -@code{c-basic-offset} only. This is intended as a ``DWIM'' measure in -cases like macros that contain statement blocks, e.g: - -@example -@group -A_VERY_LONG_MACRO_NAME (@{ - some (code, with + long, lines * in[it]); - @}); -@sssTBasicOffset{} -@end group -@end example - -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. - -@workswith @code{arglist-cont-nonempty}, @code{arglist-close}. -@end defun - -@comment ------------------------------------------------------------ - -@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{defun-block-intro}, @code{brace-list-intro}, -@code{statement-block-intro}, @code{statement-case-intro}, -@code{arglist-intro}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-multi-inher -@findex lineup-multi-inher (c-) -Line up the classes in C++ multiple inheritance clauses and member -initializers under each other. E.g: - -@example -@group -Foo::Foo (int a, int b): - Cyphr (a), - Bar (b) @hereFn{c-lineup-multi-inher} -@end group -@end example - -@noindent -and - -@example -@group -class Foo - : public Cyphr, - 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) @hereFn{c-lineup-multi-inher} -@end group -@end example - -@workswith @code{inher-cont}, @code{member-init-cont}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-java-inher -@findex lineup-java-inher (c-) -Line up Java implements and extends declarations. If class names -follow on the same line as the @samp{implements}/@samp{extends} -keyword, they are lined up under each other. Otherwise, they are -indented by adding @code{c-basic-offset} to the column of the keyword. -E.g: - -@example -@group -class Foo - extends - Bar @hereFn{c-lineup-java-inher} - @sssTBasicOffset{} -@end group -@end example - -@noindent -and - -@example -@group -class Foo - extends Cyphr, - Bar @hereFn{c-lineup-java-inher} -@end group -@end example - -@workswith @code{inher-cont}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-java-throws -@findex lineup-java-throws (c-) -Line up Java throws declarations. If exception names follow on the -same line as the throws keyword, they are lined up under each other. -Otherwise, they are indented by adding @code{c-basic-offset} to the -column of the @samp{throws} keyword. The @samp{throws} keyword itself -is also indented by @code{c-basic-offset} from the function declaration -start if it doesn't hang. E.g: - -@example -@group -int foo() - 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, @hereFn{c-lineup-java-throws} - Vlod @hereFn{c-lineup-java-throws} -@end group -@end example - -@workswith @code{func-decl-cont}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-template-args -@findex lineup-template-args (c-) -Line up the arguments of a template argument list under each other, but -only in the case where the first argument is on the same line as the -opening @samp{<}. - -To allow this function to be used in a list expression, @code{nil} is -returned if there's no template argument on the first line. - -@workswith @code{template-args-cont}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-ObjC-method-call -@findex lineup-ObjC-method-call (c-) -For Objective-C code, line up selector args as Emacs Lisp mode does -with function args: go to the position right after the message receiver, -and if you are at the end of the line, indent the current line -c-basic-offset columns from the opening bracket; otherwise you are -looking at the first character of the first method call argument, so -lineup the current line with it. - -@workswith @code{objc-method-call-cont}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-ObjC-method-args -@findex lineup-ObjC-method-args (c-) -For Objective-C code, line up the colons that separate args. The colon -on the current line is aligned with the one on the first line. - -@workswith @code{objc-method-args-cont}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-ObjC-method-args-2 -@findex lineup-ObjC-method-args-2 (c-) -Similar to @code{c-lineup-ObjC-method-args} but lines up the colon on -the current line with the colon on the previous line. - -@workswith @code{objc-method-args-cont}. -@end defun - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Operator Line-Up, Comment Line-Up, List Line-Up, Line-Up Functions -@comment node-name, next, previous, up -@subsection Operator Line-Up Functions -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -The line-up functions here calculate the indentation for lines which -start with an operator, by lining it up with something on the previous -line. - -@defun c-lineup-argcont -@findex lineup-argcont (c-) -Line up a continued argument. E.g: - -@example -@group -foo (xyz, aaa + bbb + ccc - + ddd + eee + fff); @hereFn{c-lineup-argcont} -@end group -@end example - -Only continuation lines like this are touched, @code{nil} is returned on -lines which are the start of an argument. - -Within a gcc @code{asm} block, @code{:} is recognised as an argument -separator, but of course only between operand specifications, not in the -expressions for the operands. - -@workswith @code{arglist-cont}, @code{arglist-cont-nonempty}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-arglist-operators -@findex lineup-arglist-operators (c-) -Line up lines starting with an infix operator under the open paren. -Return @code{nil} on lines that don't start with an operator, to leave -those cases to other line-up functions. Example: - -@example -@group -if ( x < 10 - || at_limit (x, @hereFn{c-lineup-arglist-operators} - list) @hereFn{c-lineup-arglist-operators@r{ returns nil}} - ) -@end group -@end example - -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): - -@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 - -@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 - -In any other situation @code{nil} is returned to allow use in list -expressions. - -@workswith @code{topmost-intro-cont}, @code{statement-cont}, -@code{arglist-cont}, @code{arglist-cont-nonempty}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-streamop -@findex lineup-streamop (c-) -Line up C++ stream operators (i.e. @samp{<<} and @samp{>>}). - -@workswith @code{stream-op}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-string-cont -@findex lineup-string-cont (c-) -Line up a continued string under the one it continues. A continued -string in this sense is where a string literal follows directly after -another one. E.g: - -@example -@group -result = prefix + "A message " - "string."; @hereFn{c-lineup-string-cont} -@end group -@end example - -@code{nil} is returned in other situations, to allow stacking with other -lineup functions. - -@workswith @code{topmost-intro-cont}, @code{statement-cont}, -@code{arglist-cont}, @code{arglist-cont-nonempty}. -@end defun - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Comment Line-Up, Misc Line-Up, Operator Line-Up, Line-Up Functions -@comment node-name, next, previous, up -@subsection Comment Line-Up Functions -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -The lineup functions here calculate the indentation for several types -of comment structure. - -@defun c-lineup-C-comments -@findex lineup-C-comments (c-) -Line up C block comment continuation lines. Various heuristics are used -to handle most of the common comment styles. Some examples: - -@example -@group -/* /** /* - * text * text text - */ */ */ -@end group -@end example - -@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: - In comments with a long delimiter line at the - start, the indentation is kept unchanged for lines - that start with an empty comment line prefix. The - delimiter line is whatever matches the - @code{comment-start-skip} regexp. -**************************************************/ -@end group -@end example - -The style variable @code{c-comment-prefix-regexp} is used to recognize -the comment line prefix, e.g. the @samp{*} that usually starts every -line inside a comment. - -@workswith The @code{c} syntactic symbol. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-comment -@findex lineup-comment (c-) -Line up a comment-only line according to the style variable -@code{c-comment-only-line-offset}. If the comment is lined up with a -comment starter on the previous line, that alignment is preserved. - -@defopt c-comment-only-line-offset -@vindex comment-only-line-offset (c-) -This style variable specifies the extra offset for the line. It can -contain an integer or a cons cell of the form - -@example -(@r{@var{non-anchored-offset}} . @r{@var{anchored-offset}}) -@end example - -@noindent -where @var{non-anchored-offset} is the amount of offset given to -non-column-zero anchored lines, and @var{anchored-offset} is the amount -of offset to give column-zero anchored lines. Just an integer as value -is equivalent to @code{(@r{@var{value}} . -1000)}. -@end defopt - -@workswith @code{comment-intro}. -@end defun - -@comment ------------------------------------------------------------ - -@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 - -Return @code{nil} if called in any other situation, to be useful in list -expressions. - -@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 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -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-) -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 - -@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: - -@example -@group -const char msg[] = @hereFn{@r{The beginning of the preceding construct.}} - \"Some text.\"; - -#define X(A, B) \ -do @{ \ @hereFn{c-lineup-cpp-define} - printf (A, B); \ -@} while (0) -@end group -@end example - -@noindent -and: - -@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 - -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: - -@example -@group -const char msg[] = - \"Some text.\"; - -#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: - -@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 - -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. - -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. - -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. - -@workswith @code{cpp-define-intro}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-gcc-asm-reg -@findex lineup-gcc-asm-reg (c-) -Line up a gcc asm register under one on a previous line. - -@example -@group - asm ("foo %1, %0\n" - "bar %0, %1" - : "=r" (w), - "=r" (x) - : "0" (y), - "1" (z)); -@end group -@end example - -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 - -@workswith @code{arglist-cont}, @code{arglist-cont-nonempty}. -@end defun - -@comment ------------------------------------------------------------ - -@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: - -@example -@group -int -neg (int i) @hereFn{c-lineup-topmost-intro-cont} -@{ - return -i; -@} -@end group -@end example - -@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 - -@noindent -and - -@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 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -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 -@c FIXME!!! The following sentence might be better omitted, since the -@c information is in the cross reference "Syntactic Analysis". 2005/10/2. -where @var{syntactic-symbol} is the symbol that the function was -called for, and @var{anchor-position} is the anchor position (if any) -for the construct that triggered the syntactic symbol -(@pxref{Syntactic Analysis}). This cons cell is how the syntactic -element of a line used to be represented in @ccmode{} 5.28 and -earlier. Line-up functions are still passed this cons cell, so as to -preserve compatibility with older configurations. In the future, we -may decide to convert to using the full list format---you can prepare -your setup for this by using the access functions -(@code{c-langelem-sym}, etc.) described below. - -@vindex c-syntactic-element -@vindex syntactic-element (c-) -@vindex c-syntactic-context -@vindex syntactic-context (c-) -Some syntactic symbols, e.g. @code{arglist-cont-nonempty}, have more -info in the syntactic element - typically other positions that can be -interesting besides the anchor position. That info can't be accessed -through the passed argument, which is a cons cell. Instead, you can -get this information from the variable @code{c-syntactic-element}, -which is dynamically bound to the complete syntactic element. The -variable @code{c-syntactic-context} might also be useful - it gets -dynamically bound to the complete syntactic context. @xref{Custom -Braces}. - -@ccmode{} provides a few functions to access parts of syntactic -elements in a more abstract way. Besides making the code easier to -read, they also hide the difference between the old cons cell form -used in the line-up function argument and the new list form used in -@code{c-syntactic-element} and everywhere else. The functions are: - -@defun c-langelem-sym langelem -@findex langelem-sym (c-) -Return the syntactic symbol in @var{langelem}. -@end defun - -@defun c-langelem-pos langelem -@findex langelem-pos (c-) -Return the anchor position in @var{langelem}, or nil if there is none. -@end defun - -@defun c-langelem-col langelem &optional preserve-point -@findex langelem-col (c-) -Return the column of the anchor position in @var{langelem}. Also move -the point to that position unless @var{preserve-point} is -non-@code{nil}. -@end defun - -@defun c-langelem-2nd-pos langelem -@findex langelem-2nd-pos (c-) -Return the secondary position in @var{langelem}, or @code{nil} if there -is none. - -Note that the return value of this function is always @code{nil} if -@var{langelem} is in the old cons cell form. Thus this function is -only meaningful when used on syntactic elements taken from -@code{c-syntactic-element} or @code{c-syntactic-context}. -@end defun - -Custom line-up functions can be as simple or as complex as you like, and -any syntactic symbol that appears in @code{c-offsets-alist} can have a -custom line-up function associated with it. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node 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 Custom Macros, Odds and Ends, Customizing Indentation, Top -@comment node-name, next, previous, up -@chapter Customizing Macros -@cindex macros -@cindex preprocessor directives -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -Normally, the lines in a multi-line macro are indented relative to -each other as though they were code. You can suppress this behaviour -by setting the following user option: - -@defopt c-syntactic-indentation-in-macros -@vindex syntactic-indentation-in-macros (c-) -Enable syntactic analysis inside macros, which is the default. If this -is @code{nil}, all lines inside macro definitions are analyzed as -@code{cpp-macro-cont}. -@end defopt - -@ccmode{} provides some tools to help keep the line continuation -backslashes in macros neat and tidy. Their precise action is -customized with these variables: - -@defopt c-backslash-column -@vindex backslash-column (c-) -@defoptx c-backslash-max-column -@vindex backslash-max-column (c-) -These variables control the alignment columns for line continuation -backslashes in multiline macros. They are used by the functions that -automatically insert or align such backslashes, -e.g. @code{c-backslash-region} and @code{c-context-line-break}. - -@code{c-backslash-column} specifies the minimum column for the -backslashes. If any line in the macro goes past this column, then the -next tab stop (i.e. next multiple of @code{tab-width}) in that line is -used as the alignment column for all the backslashes, so that they -remain in a single column. However, if any lines go past -@code{c-backslash-max-column} then the backslashes in the rest of the -macro will be kept at that column, so that the lines which are too -long ``stick out'' instead. - -Don't ever set these variables to @code{nil}. If you want to disable -the automatic alignment of backslashes, use -@code{c-auto-align-backslashes}. -@end defopt - -@defopt c-auto-align-backslashes -@vindex auto-align-backslashes (c-) -Align automatically inserted line continuation backslashes if -non-@code{nil}. When line continuation backslashes are inserted -automatically for line breaks in multiline macros, e.g. by -@code{c-context-line-break}, they are aligned with the other -backslashes in the same macro if this flag is set. - -If @code{c-auto-align-backslashes} is @code{nil}, automatically -inserted backslashes are preceded by a single space, and backslashes -get aligned only when you explicitly invoke the command -@code{c-backslash-region} (@kbd{C-c C-\}). -@end defopt - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Odds and Ends, Sample .emacs File, Custom Macros, Top -@comment node-name, next, previous, up -@chapter Odds and Ends -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -The stuff that didn't fit in anywhere else is documented here. - -@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. - -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 - -@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, Performance Issues, Odds and Ends, Top -@comment node-name, next, previous, up -@appendix Sample .emacs File -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -Here's a sample .emacs file fragment that might help you along the way. -Just copy this region and paste it into your .emacs file. You might want -to change some of the actual values. - -@verbatim -;; Make a non-standard key binding. We can put this in -;; c-mode-base-map because c-mode-map, c++-mode-map, and so on, -;; inherit from it. -(defun my-c-initialization-hook () - (define-key c-mode-base-map "\C-m" 'c-context-line-break)) -(add-hook 'c-initialization-hook 'my-c-initialization-hook) - -;; offset customizations not in my-c-style -;; This will take precedence over any setting of the syntactic symbol -;; made by a style. -(setq c-offsets-alist '((member-init-intro . ++))) - -;; Create my personal style. -(defconst my-c-style - '((c-tab-always-indent . t) - (c-comment-only-line-offset . 4) - (c-hanging-braces-alist . ((substatement-open after) - (brace-list-open))) - (c-hanging-colons-alist . ((member-init-intro before) - (inher-intro) - (case-label after) - (label after) - (access-label after))) - (c-cleanup-list . (scope-operator - empty-defun-braces - defun-close-semi)) - (c-offsets-alist . ((arglist-close . c-lineup-arglist) - (substatement-open . 0) - (case-label . 4) - (block-open . 0) - (knr-argdecl-intro . -))) - (c-echo-syntactic-information-p . t)) - "My C Programming Style") -(c-add-style "PERSONAL" my-c-style) - -;; Customizations for all modes in CC Mode. -(defun my-c-mode-common-hook () - ;; 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, but not hungry-delete - (c-toggle-auto-newline 1)) -(add-hook 'c-mode-common-hook 'my-c-mode-common-hook) -@end verbatim - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Performance Issues, Limitations and Known Bugs, Sample .emacs File, Top -@comment node-name, next, previous, up -@chapter Performance Issues -@cindex performance -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@comment FIXME: (ACM, 2003/5/24). Check whether AWK needs mentioning here. - -C and its derivative languages are highly complex creatures. Often, -ambiguous code situations arise that require @ccmode{} to scan large -portions of the buffer to determine syntactic context. Such -pathological code can cause @ccmode{} to perform fairly badly. This -section gives some insight in how @ccmode{} operates, how that interacts -with some coding styles, and what you can use to improve performance. - -The overall goal is that @ccmode{} shouldn't be overly slow (i.e. take -more than a fraction of a second) in any interactive operation. -I.e. it's tuned to limit the maximum response time in single operations, -which is sometimes at the expense of batch-like operations like -reindenting whole blocks. If you find that @ccmode{} gradually gets -slower and slower in certain situations, perhaps as the file grows in -size or as the macro or comment you're editing gets bigger, then chances -are that something isn't working right. You should consider reporting -it, unless it's something that's mentioned in this section. - -Because @ccmode{} has to scan the buffer backwards from the current -insertion point, and because C's syntax is fairly difficult to parse in -the backwards direction, @ccmode{} often tries to find the nearest -position higher up in the buffer from which to begin a forward scan -(it's typically an opening or closing parenthesis of some kind). The -farther this position is from the current insertion point, the slower it -gets. - -@findex beginning-of-defun -In earlier versions of @ccmode{}, we used to recommend putting the -opening brace of a top-level construct@footnote{E.g. a function in C, -or outermost class definition in C++ or Java.} into the leftmost -column. Earlier still, this used to be a rigid Emacs constraint, as -embodied in the @code{beginning-of-defun} function. @ccmode now -caches syntactic information much better, so that the delay caused by -searching for such a brace when it's not in column 0 is minimal, -except perhaps when you've just moved a long way inside the file. - -@findex defun-prompt-regexp -@vindex c-Java-defun-prompt-regexp -@vindex Java-defun-prompt-regexp (c-) -A special note about @code{defun-prompt-regexp} in Java mode: The common -style is to hang the opening braces of functions and classes on the -right side of the line, and that doesn't work well with the Emacs -approach. @ccmode{} comes with a constant -@code{c-Java-defun-prompt-regexp} which tries to define a regular -expression usable for this style, but there are problems with it. In -some cases it can cause @code{beginning-of-defun} to hang@footnote{This -has been observed in Emacs 19.34 and XEmacs 19.15.}. For this reason, -it is not used by default, but if you feel adventurous, you can set -@code{defun-prompt-regexp} to it in your mode hook. In any event, -setting and relying on @code{defun-prompt-regexp} will definitely slow -things down because (X)Emacs will be doing regular expression searches a -lot, so you'll probably be taking a hit either way! - -@ccmode{} maintains a cache of the opening parentheses of the blocks -surrounding the point, and it adapts that cache as the point is moved -around. That means that in bad cases it can take noticeable time to -indent a line in a new surrounding, but after that it gets fast as long -as the point isn't moved far off. The farther the point is moved, the -less useful is the cache. Since editing typically is done in ``chunks'' -rather than on single lines far apart from each other, the cache -typically gives good performance even when the code doesn't fit the -Emacs approach to finding the defun starts. - -@vindex c-enable-xemacs-performance-kludge-p -@vindex enable-xemacs-performance-kludge-p (c-) -XEmacs users can set the variable -@code{c-enable-xemacs-performance-kludge-p} to non-@code{nil}. This -tells @ccmode{} to use XEmacs-specific built-in functions which, in some -circumstances, can locate the top-most opening brace much more quickly than -@code{beginning-of-defun}. Preliminary testing has shown that for -styles where these braces are hung (e.g. most JDK-derived Java styles), -this hack can improve performance of the core syntax parsing routines -from 3 to 60 times. However, for styles which @emph{do} conform to -Emacs' recommended style of putting top-level braces in column zero, -this hack can degrade performance by about as much. Thus this variable -is set to @code{nil} by default, since the Emacs-friendly styles should -be more common (and encouraged!). Note that this variable has no effect -in Emacs since the necessary built-in functions don't exist (in Emacs -22.1 as of this writing in February 2007). - -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, FAQ, Performance Issues, Top -@comment node-name, next, previous, up -@chapter Limitations and Known Bugs -@cindex limitations -@cindex bugs -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@itemize @bullet -@item -@ccmode{} doesn't support trigraphs. (These are character sequences -such as @samp{??(}, which represents @samp{[}. They date from a time -when some character sets didn't have all the characters that C needs, -and are now utterly obsolete.) - -@item -There is no way to apply auto newline settings (@pxref{Auto-newlines}) -on already typed lines. That's only a feature to ease interactive -editing. - -To generalize this issue a bit: @ccmode{} is not intended to be used as -a reformatter for old code in some more or less batch-like way. With -the exception of some functions like @code{c-indent-region}, it's only -geared to be used interactively to edit new code. There's currently no -intention to change this goal. - -If you want to reformat old code, you're probably better off using some -other tool instead, e.g. @ref{Top, , GNU indent, indent, The `indent' -Manual}, which has more powerful reformatting capabilities than -@ccmode{}. - -@item -The support for C++ templates (in angle brackets) is not yet complete. -When a non-nested template is used in a declaration, @ccmode{} indents -it and font-locks it OK. Templates used in expressions, and nested -templates do not fare so well. Sometimes a workaround is to refontify -the expression after typing the closing @samp{>}. - -@item -On loading @ccmode{}, sometimes this error message appears: - -@example -File mode specification error: (void-variable c-font-lock-keywords-3) -@end example - -This is due to a bug in the function @code{eval-after-load} in some -versions of (X)Emacs. It can manifest itself when there is a symbolic -link in the path of the directory which contains (X)Emacs. As a -workaround, put the following into your @file{.emacs} file, fairly -early on: - -@example -(defun my-load-cc-fonts () - (require "cc-fonts")) -(add-hook 'c-initialization-hook 'my-load-cc-fonts) -@end example -@end itemize - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node FAQ, Updating CC Mode, Limitations and Known Bugs, Top -@comment node-name, next, previous, up -@appendix Frequently Asked Questions -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@itemize @bullet -@item -@emph{How can I change the indent level from 4 spaces to 2 spaces?} - -Set the variable @code{c-basic-offset}. @xref{Getting Started}. - -@item -@kindex RET -@kindex C-j -@emph{Why doesn't the @kbd{RET} key indent the new line?} - -Emacs' convention is that @kbd{RET} just adds a newline, and that -@kbd{C-j} adds a newline and indents it. You can make @kbd{RET} do this -too by adding this to your @code{c-initialization-hook}: - -@example -(define-key c-mode-base-map "\C-m" 'c-context-line-break) -@end example - -@xref{Getting Started}. This is a very common question. If you want -this to be the default behavior, don't lobby us, lobby RMS! @t{:-)} - -@item -@emph{How do I stop my code jumping all over the place when I type?} - -Deactivate ``electric minor mode'' with @kbd{C-c C-l}. @xref{Getting -Started}. - -@item -@kindex C-x h -@kindex C-M-\ -@emph{How do I reindent the whole file?} - -Visit the file and hit @kbd{C-x h} to mark the whole buffer. Then hit -@kbd{C-M-\}. @xref{Indentation Commands}. - -@item -@kindex C-M-q -@kindex C-M-u -@emph{How do I reindent the current block?} - -First move to the brace which opens the block with @kbd{C-M-u}, then -reindent that expression with @kbd{C-M-q}. @xref{Indentation -Commands}. - -@item -@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 - -@item -@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 Bug Reports, GNU Free Documentation License, Updating CC Mode, Top -@comment node-name, next, previous, up -@appendix Mailing Lists and Submitting Bug Reports -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@kindex C-c C-b -@findex c-submit-bug-report -@findex submit-bug-report (c-) -To report bugs, use the @kbd{C-c C-b} (bound to -@code{c-submit-bug-report}) command. This provides vital information -we need to reproduce your problem. Make sure you include a concise, -but complete code example. Please try to boil your example down to -just the essential code needed to reproduce the problem, and include -an exact recipe of steps needed to expose the bug. Be especially sure -to include any code that appears @emph{before} your bug example, if -you think it might affect our ability to reproduce it. - -Please try to produce the problem in an Emacs instance without any -customizations loaded (i.e. start it with the @samp{-q --no-site-file} -arguments). If it works correctly there, the problem might be caused -by faulty customizations in either your own or your site -configuration. In that case, we'd appreciate it 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}. 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. :-( - - -@node GNU Free Documentation License, Command and Function Index, Mailing Lists and Bug Reports, Top -@appendix GNU Free Documentation License -@include doclicense.texi - - -@c Removed the tentative node "Mode Initialization" from here, 2005/8/27. -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Command and Function Index, Variable Index, GNU Free Documentation License, Top -@comment node-name, next, previous, up -@unnumbered Command and Function Index -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -Since most @ccmode{} commands are prepended with the string -@samp{c-}, each appears under its @code{c-@var{thing}} name and its -@code{@var{thing} (c-)} name. -@iftex -@sp 2 -@end iftex -@printindex fn - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Variable Index, Concept and Key Index, Command and Function Index, Top -@comment node-name, next, previous, up -@unnumbered Variable Index -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -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 vr - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Concept and Key Index, , Variable Index, Top -@comment node-name, next, previous, up -@unnumbered Concept and Key Index -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@printindex cp - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@comment Epilogue. -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@iftex -@page -@summarycontents -@contents -@end iftex - -@bye - -@ignore - arch-tag: c4cab162-5e57-4366-bdce-4a9db2fc97f0 -@end ignore