Mercurial > emacs
view man/cc-mode.texi @ 33093:46fe3d0d327b
*** empty log message ***
author | Gerd Moellmann <gerd@gnu.org> |
---|---|
date | Tue, 31 Oct 2000 11:57:12 +0000 |
parents | 460a86ced57c |
children | 33df9c2e70bf |
line wrap: on
line source
\input texinfo @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @comment %**start of header (This is for running Texinfo on a region) @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @comment No overfull hbox marks in the dvi file. @finalout @setfilename ../info/ccmode @settitle CC Mode Version 5 Documentation @footnotestyle end @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 Maintained by Martin Stjernholm <bug-cc-mode@gnu.org> @comment @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @comment Info directory entry for use by install-info @dircategory Emacs @direntry * CC Mode: (cc-mode). Emacs mode for editing C, C++, Objective-C, Java, Pike, and IDL code. @end direntry @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @comment The following line inserts the copyright notice @comment into the Info file. @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @ifinfo Copyright @copyright{} 1995-2000 Free Software Foundation, Inc. @end ifinfo @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @comment !!!The titlepage section does not appear in the Info file.!!! @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @titlepage @sp 10 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @comment The title is printed in a large font. @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @center @titlefont{CC Mode 5.27} @sp 2 @center @subtitlefont{A GNU Emacs mode for editing C and C-like languages} @sp 2 @center Current maintainer: @center Martin Stjernholm @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @comment The following two commands start the copyright page @comment for the printed manual. This will not appear in the Info file. @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @page @vskip 0pt plus 1filll Copyright @copyright{} 1995-2000 Free Software Foundation, Inc. @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 @macro ccmode CC Mode @end macro @ifinfo @top @ccmode{} @ccmode{} is a GNU Emacs mode for editing files containing C, C++, Objective-C, Java, CORBA IDL, and Pike code. It provides syntax-based indentation and has several handy commands and some minor modes to make the editing easier. Note that @ccmode{} does @emph{not} provide font-locking; there are other Emacs packages for that. @end ifinfo @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @menu * Introduction:: * Getting Connected:: * New Indentation Engine:: * Minor Modes:: * Text Filling and Line Breaking:: * Commands:: * Customizing Indentation:: * Syntactic Symbols:: * Indentation Functions:: * Performance Issues:: * Frequently Asked Questions:: * Getting the Latest CC Mode Release:: * Sample .emacs File:: * Limitations and Known Bugs:: * Mailing Lists and Submitting Bug Reports:: --- Indices --- * Concept Index:: * Command Index:: * Key Index:: * Variable Index:: --- The Detailed Node Listing --- New Indentation Engine * Syntactic Analysis:: * Indentation Calculation:: Minor Modes * Auto-newline Insertion:: * Hungry-deletion of Whitespace:: Auto-newline Insertion * Hanging Braces:: * Hanging Colons:: * Hanging Semi-colons and Commas:: * Other Electric Commands:: * Clean-ups:: Commands * Indentation Commands:: * Movement Commands:: * Other Commands:: Customizing Indentation * Interactive Customization:: * Permanent Customization:: * Hooks:: * Styles:: * Advanced Customizations:: Styles * Built-in Styles:: * Adding Styles:: * File Styles:: Advanced Customizations * Custom Indentation Functions:: * Custom Brace and Colon Hanging:: * Customizing Semi-colons and Commas:: * Other Special Indentations:: @end menu @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @node Introduction, Getting Connected, Top, Top @comment node-name, next, previous, up @chapter Introduction @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @cindex BOCM Welcome to @ccmode{}, a GNU Emacs mode for editing files containing C, C++, Objective-C, Java, CORBA IDL, and Pike code. This incarnation of the mode is descendant from @file{c-mode.el} (also called "Boring Old C Mode" or BOCM @t{:-)}, and @file{c++-mode.el} version 2, which Barry has been maintaining since 1992. @ccmode{} represents a significant milestone in the mode's life. It has been fully merged back with Emacs 19's @file{c-mode.el}. Also a new, more intuitive and flexible mechanism for controlling indentation has been developed. Late in 1997, Martin joined the @ccmode{} Maintainers Team, and implemented the Pike support. As of 2000 Martin has taken over as the sole maintainer. This manual describes @ccmode{} @comment The following line must appear on its own, so that the automated version 5.27. @comment Release.py script can update the version number automatically @ccmode{} supports the editing of K&R and ANSI C, @dfn{ARM} @footnote{@cite{The Annotated C++ Reference Manual}, by Ellis and Stroustrup.} C++, Objective-C, Java, CORBA's Interface Definition Language, and Pike@footnote{A C-like scripting language with its roots in the LPC language used in some MUD engines. See @uref{http://pike.idonex.se/}.} files. In this way, you can easily set up consistent coding styles for use in editing all of these languages. @ccmode{} does @emph{not} handle font-locking (a.k.a. syntax coloring, keyword highlighting) or anything of that nature, for any of these modes. Font-locking is handled by other Emacs packages. This manual will describe the following: @itemize @bullet @item How to get started using @ccmode{}. @item How the new indentation engine works. @item How to customize the new indentation engine. @end itemize @findex c-mode @findex c++-mode @findex objc-mode @findex java-mode @findex idl-mode @findex pike-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}, and @code{pike-mode} entry points are provided. This package is intended to be a replacement for @file{c-mode.el} and @file{c++-mode.el}. @cindex @file{cc-compat.el} file This distribution also contains a file called @file{cc-compat.el} which should ease your transition from BOCM to @ccmode{}. If you have a BOCM configuration you are really happy with, and want to postpone learning how to configure @ccmode{}, take a look at that file. It maps BOCM configuration variables to @ccmode{}'s new indentation model. It is not actively supported so for the long run, you should learn how to customize @ccmode{} to support your coding style. 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 Getting Connected, New Indentation Engine, Introduction, Top @comment node-name, next, previous, up @chapter Getting Connected @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! If you got this version of @ccmode{} with Emacs or XEmacs, it should work just fine right out of the box. Note however that you may not have the latest @ccmode{} release and may want to upgrade your copy. If you are upgrading an existing @ccmode{} installation, please see the @file{README} file for installation details. @ccmode{} may not work with older versions of Emacs or XEmacs. See the @ccmode{} release notes Web pages for the latest information on Emacs version and package compatibility (@pxref{Getting the Latest CC Mode Release}). @cindex @file{cc-mode-18.el} file @emph{Note that @ccmode{} no longer works with Emacs 18!}, so if you haven't upgraded from Emacs 18 by now, you are out of luck. @findex c-version @findex version (c-) You can find out what version of @ccmode{} you are using by visiting a C file and entering @kbd{M-x c-version RET}. You should see this message in the echo area: @example Using CC Mode version 5.XX @end example @noindent where @samp{XX} is the minor release number. @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @node New Indentation Engine, Minor Modes, Getting Connected, Top @comment node-name, next, previous, up @chapter New Indentation Engine @cindex indentation engine @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @ccmode{} has a new indentation engine, providing a simplified, yet flexible and general mechanism for customizing indentation. It separates indentation calculation into two steps: first, @ccmode{} analyzes the line of code being indented to determine the kind of language construct it's looking at, then it applies user defined offsets to the current line based on this analysis. This section will briefly cover how indentation is calculated in @ccmode{}. It is important to understand the indentation model being used so that you will know how to customize @ccmode{} for your personal coding style. @menu * Syntactic Analysis:: * Indentation Calculation:: @end menu @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @node Syntactic Analysis, Indentation Calculation, , New Indentation Engine @comment node-name, next, previous, up @section Syntactic Analysis @cindex syntactic analysis @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @cindex relative buffer position @cindex syntactic symbol @cindex syntactic component @cindex syntactic component list The first thing @ccmode{} does when indenting a line of code, is to analyze the line, determining the @dfn{syntactic component list} of the construct on that line. A syntactic component consists of a pair of information (in lisp parlance, a @emph{cons cell}), where the first part is a @dfn{syntactic symbol}, and the second part is a @dfn{relative buffer position}. Syntactic symbols describe elements of C code @footnote{Unless otherwise noted, the term ``C code'' to refers to all the C-like languages.}, e.g. @code{statement}, @code{substatement}, @code{class-open}, @code{class-close}, etc. @xref{Syntactic Symbols}, for a complete list of currently recognized syntactic symbols and their semantics. The style variable @code{c-offsets-alist} also contains the list of currently supported syntactic symbols. Conceptually, a line of C code is always indented relative to the indentation of some line higher up in the buffer. This is represented by the relative buffer position in the syntactic component. Here is an example. Suppose we had the following code as the only thing in a C++ buffer @footnote{The line numbers in this and future examples don't actually appear in the buffer, of course!}: @example @group 1: void swap( int& a, int& b ) 2: @{ 3: int tmp = a; 4: a = b; 5: b = tmp; 6: @} @end group @end example @kindex C-c C-s @findex c-show-syntactic-information @findex show-syntactic-information (c-) We can use the command @kbd{C-c C-s} (@code{c-show-syntactic-information}) to simply report what the syntactic analysis is for the current line. Running this command on line 4 of this example, we'd see in the echo area@footnote{With a universal argument (i.e. @kbd{C-u C-c C-s}) the analysis is inserted into the buffer as a comment on the current line.}: @example ((statement . 35)) @end example This tells us that the line is a statement and it is indented relative to buffer position 35, which happens to be the @samp{i} in @code{int} on line 3. If you were to move point to line 3 and hit @kbd{C-c C-s}, you would see: @example ((defun-block-intro . 29)) @end example This indicates that the @samp{int} line is the first statement in a top level function block, and is indented relative to buffer position 29, which is the brace just after the function header. Here's another example: @example @group 1: int add( int val, int incr, int doit ) 2: @{ 3: if( doit ) 4: @{ 5: return( val + incr ); 6: @} 7: return( val ); 8: @} @end group @end example @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 component lists can contain more than one component, and individual syntactic components need not have relative buffer positions. The most common example of this is a line that contains a @dfn{comment only line}. @example @group 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 group @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 component list contains two syntactic components. Also notice that the first component, @samp{(comment-intro)} has no relative buffer position. @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @node Indentation Calculation, , Syntactic Analysis, New Indentation Engine @comment node-name, next, previous, up @section Indentation Calculation @cindex indentation calculation @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! Indentation for a line is calculated using the syntactic component list derived in step 1 above (@pxref{Syntactic Analysis}). Each component contributes to the final total indentation of the line in two ways. First, the syntactic symbols are looked up in the @code{c-offsets-alist} style variable, which is an association list of syntactic symbols and the offsets to apply for those symbols. These offsets are added to a running total. Second, if the component has a relative buffer position, @ccmode{} adds the column number of that position to the running total. By adding up the offsets and columns for every syntactic component on the list, the final total indentation for the current line is computed. Let's use our two code examples above to see how this works. Here is our first example again: @example @group 1: void swap( int& a, int& b ) 2: @{ 3: int tmp = a; 4: a = b; 5: b = tmp; 6: @} @end group @end example Let's say point is on line 3 and we hit the @kbd{TAB} key to re-indent the line. Remember that the syntactic component list for that line is: @example ((defun-block-intro . 29)) @end example @noindent @ccmode{} looks up @code{defun-block-intro} in the @code{c-offsets-alist} style variable. Let's say it finds the value @samp{4}; it adds this to the running total (initialized to zero), yielding a running total indentation of 4 spaces. Next @ccmode{} goes to buffer position 29 and asks for the current column. This brace is in column zero, so @ccmode{} adds @samp{0} to the running total. Since there is only one syntactic component on the list for this line, indentation calculation is complete, and the total indentation for the line is 4 spaces. Here's another example: @example @group 1: int add( int val, int incr, int doit ) 2: @{ 3: if( doit ) 4: @{ 5: return( val + incr ); 6: @} 7: return( val ); 8: @} @end group @end example If we were to hit @kbd{TAB} on line 4 in the above example, the same basic process is performed, despite the differences in the syntactic component list. Remember that the list for this line is: @example ((substatement-open . 46)) @end example Here, @ccmode{} first looks up the @code{substatement-open} symbol in @code{c-offsets-alist}. Let's say it finds the value @samp{4}. This yields a running total of 4. @ccmode{} then goes to buffer position 46, which is the @samp{i} in @code{if} on line 3. This character is in the fourth column on that line so adding this to the running total yields an indentation for the line of 8 spaces. Simple, huh? Actually, the mode usually just does The Right Thing without you having to think about it in this much detail. But when customizing indentation, it's helpful to understand the general indentation model being used. @vindex c-echo-syntactic-information-p @vindex echo-syntactic-information-p (c-) As you configure @ccmode{}, you might want to set the variable @code{c-echo-syntactic-information-p} to non-@code{nil} so that the syntactic component list and calculated offset will always be echoed in the minibuffer when you hit @kbd{TAB}. @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @node Minor Modes, Text Filling and Line Breaking, New Indentation Engine, Top @comment node-name, next, previous, up @chapter Minor Modes @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @ccmode{} contains two minor-mode-like features that you should find useful while you enter new C code. The first is called @dfn{auto-newline} mode, and the second is called @dfn{hungry-delete} mode. These minor modes can be toggled on and off independently, and @ccmode{} can be configured so that it starts up with any combination of these minor modes. By default, both of these minor modes are turned off. The state of the minor modes is always reflected in the minor mode list on the modeline of the @ccmode{} buffer. When auto-newline mode is enabled, you will see @samp{C/a} on the mode line @footnote{The @samp{C} would be replaced with @samp{C++}, @samp{ObjC}, @samp{Java}, @samp{IDL}, or @samp{Pike} for the respective languages.}. When hungry delete mode is enabled you would see @samp{C/h} and when both modes are enabled, you'd see @samp{C/ah}. @kindex C-c C-a @kindex C-c C-d @kindex C-c C-t @findex c-toggle-hungry-state @findex c-toggle-auto-state @findex c-toggle-auto-hungry-state @findex toggle-hungry-state (c-) @findex toggle-auto-state (c-) @findex toggle-auto-hungry-state (c-) @ccmode{} provides keybindings which allow you to toggle the minor modes on the fly while editing code. To toggle just the auto-newline state, hit @kbd{C-c C-a} (@code{c-toggle-auto-state}). When you do this, you should see the @samp{a} indicator either appear or disappear on the modeline. Similarly, to toggle just the hungry-delete state, use @kbd{C-c C-d} (@code{c-toggle-hungry-state}), and to toggle both states, use @kbd{C-c C-t} (@code{c-toggle-auto-hungry-state}). To set up the auto-newline and hungry-delete states to your preferred values, you would need to add some lisp to your @file{.emacs} file that called one of the @code{c-toggle-*-state} functions directly. When called programmatically, each function takes a numeric value, where a positive number enables the minor mode, a negative number disables the mode, and zero toggles the current state of the mode. So for example, if you wanted to enable both auto-newline and hungry-delete for all your C file editing, you could add the following to your @file{.emacs} file: @example (add-hook 'c-mode-common-hook '(lambda () (c-toggle-auto-hungry-state 1))) @end example @cindex electric characters @menu * Auto-newline Insertion:: * Hungry-deletion of Whitespace:: @end menu @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @node Auto-newline Insertion, Hungry-deletion of Whitespace, , Minor Modes @comment node-name, next, previous, up @section Auto-newline Insertion @cindex auto-newline insertion @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @cindex electric commands Auto-newline minor mode works by enabling certain @dfn{electric commands}. Electric commands are typically bound to special characters such as the left and right braces, colons, semi-colons, etc., which when typed, perform some magic formatting in addition to inserting the typed character. As a general rule, electric commands are only electric when the following conditions apply: @itemize @bullet @item Auto-newline minor mode is enabled, as evidenced by a @samp{C/a} or @samp{C/ah} indicator on the modeline. @cindex literal @cindex syntactic whitespace @item The character was not typed inside of a literal @footnote{A @dfn{literal} is defined as any comment, string, or C preprocessor macro definition. These constructs are also known as @dfn{syntactic whitespace} since they are usually ignored when scanning C code.}. @item @kindex C-u No numeric argument was supplied to the command (i.e. it was typed as normal, with no @kbd{C-u} prefix). @end itemize @menu * Hanging Braces:: * Hanging Colons:: * Hanging Semi-colons and Commas:: * Other Electric Commands:: * Clean-ups:: @end menu @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @node Hanging Braces, Hanging Colons, , Auto-newline Insertion @comment node-name, next, previous, up @subsection Hanging Braces @cindex hanging braces @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @findex c-electric-brace @findex electric-brace (c-) @vindex c-hanging-braces-alist @vindex hanging-braces-alist (c-) When you type either an open or close brace (i.e. @kbd{@{} or @kbd{@}}), the electric command @code{c-electric-brace} gets run. This command has two electric formatting behaviors. First, it will perform some re-indentation of the line the brace was typed on, and second, it will add various newlines before and/or after the typed brace. Re-indentation occurs automatically whenever the electric behavior is enabled. If the brace ends up on a line other than the one it was typed on, then that line is also re-indented. @cindex class-open syntactic symbol @cindex class-close syntactic symbol @cindex defun-open syntactic symbol @cindex defun-close syntactic symbol @cindex inline-open syntactic symbol @cindex inline-close syntactic symbol @cindex brace-list-open syntactic symbol @cindex brace-list-close syntactic symbol @cindex brace-list-intro syntactic symbol @cindex brace-entry-open syntactic symbol @cindex block-open syntactic symbol @cindex block-close syntactic symbol @cindex substatement-open syntactic symbol @cindex statement-case-open syntactic symbol @cindex extern-lang-open syntactic symbol @cindex extern-lang-close syntactic symbol @cindex namespace-open syntactic symbol @cindex namespace-close syntactic symbol @cindex inexpr-class-open symbol @cindex inexpr-class-close symbol The default in auto-newline mode is to insert newlines both before and after a brace, but that can be controlled by the @code{c-hanging-braces-alist} style variable. This variable contains a mapping between syntactic symbols related to braces, and a list of places to insert a newline. The syntactic symbols that are useful for this list are: @code{class-open}, @code{class-close}, @code{defun-open}, @code{defun-close}, @code{inline-open}, @code{inline-close}, @code{brace-list-open}, @code{brace-list-close}, @code{brace-list-intro}, @code{brace-entry-open}, @code{block-open}, @code{block-close}, @code{substatement-open}, @code{statement-case-open}, @code{extern-lang-open}, @code{extern-lang-close}, @code{namespace-open}, @code{namespace-close}, @code{inexpr-class-open}, and @code{inexpr-class-close}@footnote{Note that the aggregate constructs in Pike mode, @samp{(@{}, @samp{@})}, @samp{([}, @samp{])}, and @samp{(<}, @samp{>)}, do not count as brace lists in this regard, even though they do for normal indentation purposes. It's currently not possible to set automatic newlines on these constructs.}. @xref{Syntactic Symbols}, for a more detailed description of these syntactic symbols, except for @code{inexpr-class-open} and @code{inexpr-class-close}, which aren't actual syntactic symbols. The braces of anonymous inner classes in Java are given the special symbols @code{inexpr-class-open} and @code{inexpr-class-close}, so that they can be distinguished from the braces of normal classes@footnote{The braces of anonymous classes produces a combination of @code{inexpr-class}, and @code{class-open} or @code{class-close} in normal indentation analysis.}. The value associated with each syntactic symbol in this association list is called an @var{ACTION} which can be either a function or a list. @xref{Custom Brace and Colon Hanging}, for a more detailed discussion of using a function as a brace hanging @var{ACTION}. When the @var{ACTION} is a list, it can contain any combination of the symbols @code{before} and @code{after}, directing @ccmode{} where to put newlines in relationship to the brace being inserted. Thus, if the list contains only the symbol @code{after}, then the brace is said to @dfn{hang} on the right side of the line, as in: @example @group // here, open braces always `hang' void spam( int i ) @{ if( i == 7 ) @{ dosomething(i); @} @} @end group @end example When the list contains both @code{after} and @code{before}, the braces will appear on a line by themselves, as shown by the close braces in the above example. The list can also be empty, in which case no newlines are added either before or after the brace. 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 @group ((brace-list-open) (brace-entry-open) (substatement-open after) (block-close . c-snug-do-while) (extern-lang-open after) (inexpr-class-open after) (inexpr-class-close before)) @end group @end example @noindent which says that @code{brace-list-open} and @code{brace-entry-open} braces should both hang on the right side, and allow subsequent text to follow on the same line as the brace. Also, @code{substatement-open}, @code{extern-lang-open}, and @code{inexpr-class-open} braces should hang on the right side, but subsequent text should follow on the next line. The opposite holds for @code{inexpr-class-close} braces; they won't hang, but the following text continues on the same line. Here, in the @code{block-close} entry, you also see an example of using a function as an @var{ACTION}. In all other cases, braces are put on a line by themselves. A word of caution: it is not a good idea to hang top-level construct introducing braces, such as @code{class-open} or @code{defun-open}. Emacs makes an assumption that such braces will always appear in column zero, hanging them can introduce performance problems. @xref{Performance Issues}, for more information. @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @node Hanging Colons, Hanging Semi-colons and Commas, Hanging Braces, Auto-newline Insertion @comment node-name, next, previous, up @subsection Hanging Colons @cindex hanging colons @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @vindex hanging-colons-alist (c-) @vindex c-hanging-colons-alist Using a mechanism similar to brace hanging (@pxref{Hanging Braces}), colons can also be made to hang using the style variable @code{c-hanging-colons-alist}. The syntactic symbols appropriate for this assocation list are: @code{case-label}, @code{label}, @code{access-label}, @code{member-init-intro}, and @code{inher-intro}. Note however that for @code{c-hanging-colons-alist}, @var{ACTION}s as functions are not supported. See also @ref{Custom Brace and Colon Hanging} for details. 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 Semi-colons and Commas, Other Electric Commands, Hanging Colons, Auto-newline Insertion @comment node-name, next, previous, up @subsection Hanging Semi-colons and Commas @cindex hanging semi-colons @cindex hanging commas @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! Semicolons and commas are also electric in @ccmode{}, but since these characters do not correspond directly to syntactic symbols, a different mechanism is used to determine whether newlines should be automatically inserted after these characters. @xref{Customizing Semi-colons and Commas}, for details. @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @node Other Electric Commands, Clean-ups, Hanging Semi-colons and Commas, Auto-newline Insertion @comment node-name, next, previous, up @subsection Other Electric Commands @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @kindex # @findex c-electric-pound @vindex c-electric-pound-behavior @findex electric-pound (c-) @vindex electric-pound-behavior (c-) A few other keys also provide electric behavior. For example @kbd{#} (@code{c-electric-pound}) is electric when typed as the first non-whitespace character on a line. In this case, the variable @code{c-electric-pound-behavior} is consulted for the electric behavior. This variable takes a list value, although the only element currently defined is @code{alignleft}, which tells this command to force the @samp{#} character into column zero. This is useful for entering C preprocessor macro definitions. @findex c-electric-star @findex c-electric-slash @findex electric-star (c-) @findex electric-slash (c-) Stars and slashes (i.e. @kbd{*} and @kbd{/}, @code{c-electric-star} and @code{c-electric-slash} respectively) are also electric under certain circumstances. If a star is inserted as the second character of a C style block comment on a comment-only line, then the comment delimiter is indented as defined by @code{c-offsets-alist}. A comment-only line is defined as a line which contains only a comment, as in: @example @group void spam( int i ) @{ // this is a comment-only line... if( i == 7 ) // but this is not @{ dosomething(i); @} @} @end group @end example Likewise, if a slash is inserted as the second slash in a C++ style line comment (also only on a comment-only line), then the line is indented as defined by @code{c-offsets-alist}. @findex c-electric-lt-gt @findex electric-lt-gt (c-) @kindex < @kindex > Less-than and greater-than signs (@code{c-electric-lt-gt}) are also electric, but only in C++ mode. Hitting the second of two @kbd{<} or @kbd{>} keys re-indents the line if it is a C++ style stream operator. @findex c-electric-paren @findex electric-paren (c-) @kindex ( @kindex ) The normal parenthesis characters @samp{(} and @samp{)} also reindent the current line if they are used in normal code. This is useful for getting the closing parenthesis of an argument list aligned automatically. @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @node Clean-ups, , Other Electric Commands, Auto-newline Insertion @comment node-name, next, previous, up @subsection Clean-ups @cindex clean-ups @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @dfn{Clean-ups} are a mechanism complementary to colon and brace hanging. On the surface, it would seem that clean-ups overlap the functionality provided by the @code{c-hanging-*-alist} variables, and similarly, clean-ups are only enabled when auto-newline minor mode is enabled. Clean-ups are used however to adjust code ``after-the-fact'', i.e. to eliminate some whitespace that is inserted by electric commands, or whitespace that contains intervening constructs. @vindex c-cleanup-list @vindex cleanup-list (c-) @cindex literal You can configure @ccmode{}'s clean-ups by setting the style variable @code{c-cleanup-list}, which is a list of clean-up symbols. By default, @ccmode{} cleans up only the @code{scope-operator} construct, which is necessary for proper C++ support. Note that clean-ups are only performed when the construct does not occur within a literal (@pxref{Auto-newline Insertion}), and when there is nothing but whitespace appearing between the individual components of the construct. There are currently only five specific constructs that @ccmode{} can clean up, as indicated by these symbols: @itemize @bullet @item @code{brace-else-brace} --- cleans up @samp{@} else @{} constructs by placing the entire construct on a single line. Clean-up occurs when the open brace after the @samp{else} is typed. So for example, this: @example @group void spam(int i) @{ if( i==7 ) @{ dosomething(); @} else @{ @end group @end example @noindent appears like this after the open brace is typed: @example @group void spam(int i) @{ if( i==7 ) @{ dosomething(); @} else @{ @end group @end example @item @code{brace-elseif-brace} --- similar to the @code{brace-else-brace} clean-up, but this cleans up @samp{@} else if (...) @{} constructs. For example: @example @group void spam(int i) @{ if( i==7 ) @{ dosomething(); @} else if( i==3 ) @{ @end group @end example @noindent appears like this after the open parenthesis is typed: @example @group void spam(int i) @{ if( i==7 ) @{ dosomething(); @} else if( i==3 ) @{ @end group @end example @noindent and like this after the open brace is typed: @example @group void spam(int i) @{ if( i==7 ) @{ dosomething(); @} else if( i==3 ) @{ @end group @end example @item @code{brace-catch-brace} --- analogous to @code{brace-elseif-brace}, but cleans up @samp{@} catch (...) @{} in C++ and Java mode. @item @code{empty-defun-braces} --- cleans up braces following a top-level function or class definition that contains no body. Clean up occurs when the closing brace is typed. Thus the following: @example @group class Spam @{ @} @end group @end example @noindent is transformed into this when the close brace is typed: @example @group class Spam @{@} @end group @end example @item @code{defun-close-semi} --- cleans up the terminating semi-colon on top-level function or class definitions when they follow a close brace. Clean up occurs when the semi-colon is typed. So for example, the following: @example @group class Spam @{ @} ; @end group @end example @noindent is transformed into this when the semi-colon is typed: @example @group class Spam @{ @}; @end group @end example @item @code{list-close-comma} --- cleans up commas following braces in array and aggregate initializers. Clean up occurs when the comma is typed. @item @code{scope-operator} --- cleans up double colons which may designate a C++ scope operator split across multiple lines@footnote{Certain C++ constructs introduce ambiguous situations, so @code{scope-operator} clean-ups may not always be correct. This usually only occurs when scoped identifiers appear in switch label tags.}. Clean up occurs when the second colon is typed. You will always want @code{scope-operator} in the @code{c-cleanup-list} when you are editing C++ code. @end itemize @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @node Hungry-deletion of Whitespace, , Auto-newline Insertion, Minor Modes @comment node-name, next, previous, up @section Hungry-deletion of Whitespace @cindex hungry-deletion of whitespace @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! Hungry deletion of whitespace, or as it more commonly called, @dfn{hungry-delete mode}, is a simple feature that some people find extremely useful. In fact, you might find yourself wanting hungry-delete in @strong{all} your editing modes! @kindex DEL @kindex Backspace In a nutshell, when hungry-delete mode is enabled, hitting the @key{Backspace} key@footnote{I say ``hit the @key{Backspace} key'' but what I really mean is ``when Emacs receives the @code{BackSpace} key event''. The difference usually isn't significant to most users, but advanced users will realize that under window systems such as X, any physical key (keycap) on the keyboard can be configured to generate any keysym, and thus any Emacs key event. Also, the use of Emacs on TTYs will affect which keycap generates which key event. From a pedantic point of view, here we are only concerned with the key event that Emacs receives.} will consume all preceding whitespace, including newlines and tabs. This can really cut down on the number of @key{Backspace}'s you have to type if, for example you made a mistake on the preceding line. @findex c-electric-backspace @findex electric-backspace (c-) @vindex c-backspace-function @vindex backspace-function (c-) @findex c-electric-delete @findex electric-delete (c-) @vindex c-delete-function @vindex delete-function (c-) @cindex literal @findex backward-delete-char-untabify By default, when you hit the @key{Backspace} key @ccmode{} runs the command @code{c-electric-backspace}, which deletes text in the backwards direction. When deleting a single character, or when @key{Backspace} is hit in a literal (@pxref{Auto-newline Insertion}), or when hungry-delete mode is disabled, the function contained in the @code{c-backspace-function} variable is called with one argument (the number of characters to delete). This variable is set to @code{backward-delete-char-untabify} by default. @vindex delete-key-deletes-forward @findex delete-char The default behavior of the @key{Delete} key depends on the flavor of Emacs you are using. By default in XEmacs 20.3 and beyond, the @key{Delete} key is bound to @code{c-electric-delete}. You control the direction that the @key{Delete} key deletes by setting the variable @code{delete-key-deletes-forward}, a standard XEmacs variable. When this variable is non-@code{nil} and hungry-delete mode is enabled, @code{c-electric-delete} will consume all whitespace @emph{following} point. When @code{delete-key-deletes-forward} is @code{nil}, it deletes all whitespace @emph{preceding} point@footnote{i.e. it literally calls @code{c-electric-backspace}.} When deleting a single character, or if @key{Delete} is hit in a literal, or hungry-delete mode is disabled, the function contained in @code{c-delete-function} is called with one argument: the number of characters to delete. This variable is set to @code{delete-char} by default. In Emacs 19 or Emacs 20, both the @key{Delete} and @key{Backspace} keys are bound to @code{c-electric-backspace}, however you can change this by explicitly binding @code{[delete]}@footnote{E.g. to @code{c-electric-delete} in your @file{.emacs} file. Note however, that Emacs 20 does not have a standard variable such as @code{delete-key-deletes-forward}.}. XEmacsen older than 20.3 behave similar to Emacs 19 and Emacs 20. @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @node Text Filling and Line Breaking, Commands, Minor Modes, Top @comment node-name, next, previous, up @chapter Text Filling and Line Breaking @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! Since there's a lot of normal text in comments and string literals, @ccmode{} provides features to edit these like in text mode. The goal is to do it as seamlessly as possible, i.e. you can use auto fill mode, sentence and paragraph movement, paragraph filling, adaptive filling etc wherever there's a piece of normal text without having to think much about it. @ccmode{} should keep the indentation, fix the comment line decorations, and so on, for you. It does that by hooking in on the different line breaking functions and tuning relevant variables as necessary. @vindex c-comment-prefix-regexp @vindex comment-prefix-regexp (c-) @cindex comment line prefix @vindex comment-start @vindex comment-end @vindex comment-start-skip @vindex paragraph-start @vindex paragraph-separate @vindex paragraph-ignore-fill-prefix @vindex adaptive-fill-mode @vindex adaptive-fill-regexp @vindex adaptive-fill-first-line-regexp To make Emacs recognize comments and treat text in them as normal paragraphs, @ccmode{} makes several standard variables@footnote{@code{comment-start}, @code{comment-end}, @code{comment-start-skip}, @code{paragraph-start}, @code{paragraph-separate}, @code{paragraph-ignore-fill-prefix}, @code{adaptive-fill-mode}, @code{adaptive-fill-regexp}, and @code{adaptive-fill-first-line-regexp}.} buffer local and modifies them according to the language syntax and the style of line decoration that starts every line in a comment. The style variable @code{c-comment-prefix-regexp} contains the regexp used to recognize this @dfn{comment line prefix}. The default is @samp{//+\\|\\**}, which matches C++ style line comments like @example // blah blah @end example @noindent with two or more slashes in front of them, and 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 that variable, please make sure it still matches the comment starter (i.e. @code{//}) of line comments @emph{and} the line prefix inside block comments. Also note that since @ccmode{} uses the value of @code{c-comment-prefix-regexp} to set up several other variables at mode initialization, you need to reinitialize the program mode if you change it inside a @ccmode{} buffer. @findex auto-fill-mode @cindex auto fill mode @cindex paragraph fill Line breaks are by default handled (almost) the same regardless whether they are made by auto fill mode (@pxref{Auto Fill,,, emacs, The Emacs Editor}), paragraph filling (e.g. with @kbd{M-q}), or explicitly with @kbd{M-j} or similar methods. In string literals, the new line gets the same indentation as the previous nonempty line (may be changed with the @code{string} syntactic symbol). In comments, @ccmode{} uses @code{c-comment-prefix-regexp} to adapt the line prefix from the other lines in the comment. @vindex adaptive-fill-mode @cindex adaptive fill mode @ccmode{} uses adaptive fill mode (@pxref{Adaptive Fill,,, emacs, The Emacs Editor}) to make Emacs correctly keep the line prefix when filling paragraphs. That also makes Emacs preserve the text indentation @emph{inside} the comment line prefix. E.g. in the following comment, both paragraphs will be filled with the left margins kept intact: @example @group /* 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 site}.}, which handles things like bulleted lists nicely. There's a convenience function @code{c-setup-filladapt} that tunes the relevant variables in Filladapt for use in @ccmode{}. Call it from a mode hook, e.g. with something like this in your @file{.emacs}: @example @group (defun my-c-mode-common-hook () (c-setup-filladapt) (filladapt-mode 1)) (add-hook 'c-mode-common-hook 'my-c-mode-common-hook) @end group @end example @vindex c-block-comment-prefix @vindex block-comment-prefix (c-) @vindex c-comment-continuation-stars @vindex comment-continuation-stars (c-) Normally the comment line prefix inserted for a new line inside a comment is deduced from other lines in it. However there's one situation when there's no clue about how the prefix should look, namely when a block comment is broken for the first time. The string in the style variable @code{c-block-comment-prefix}@footnote{In versions before 5.26, this variable was called @code{c-comment-continuation-stars}. As a compatibility measure, @ccmode{} still uses the value on that variable if it's set.} is used in that case. It defaults to @samp{* }, which makes a comment @example /* 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 justify the indentation by putting leading spaces in the @code{c-block-comment-prefix} string, since @ccmode{} still uses the normal indentation engine to indent the line. Thus, the right way to fix the indentation is by setting the @code{c} syntactic symbol. It defaults to @code{c-lineup-C-comments}, which handles the indentation of most common comment styles, see @ref{Indentation Functions}. @vindex c-ignore-auto-fill @vindex ignore-auto-fill (c-) When auto fill mode is enabled, @ccmode{} can selectively ignore it depending on the context the line break would occur in, e.g. to never break a line automatically inside a string literal. This behavior can be controlled with the @code{c-ignore-auto-fill} variable. It takes a list of symbols for the different contexts where auto-filling never should occur: @itemize @bullet @item @code{string} --- Inside a string or character literal. @item @code{c} --- Inside a C style block comment. @item @code{c++} --- Inside a C++ style line comment. @item @code{cpp} --- Inside a preprocessor directive. @item @code{code} --- Anywhere else, i.e. in normal code. @end itemize By default, @code{c-ignore-auto-fill} is set to @code{'(string cpp code)}, which means that auto-filling only occurs in comments when auto-fill mode is activated. In literals, it's often desirable to have explicit control over newlines. In preprocessor directives, the necessary @samp{\} escape character before the newline is not automatically inserted, so an automatic line break would produce invalid code. In normal code, line breaks are normally dictated by some logical structure in the code rather than the last whitespace character, so automatic line breaks there will produce poor results in the current implementation. The commands that does the actual work follows. @table @asis @kindex M-q @findex c-fill-paragraph @findex fill-paragraph (c-) @cindex Javadoc markup @item @kbd{M-q} (@code{c-fill-paragraph}) This is the replacement for @code{fill-paragraph} in @ccmode{} buffers. It's used to fill multiline string literals and both block and line style comments. In Java buffers, the Javadoc markup words are recognized as paragraph starters. The function keeps the comment starters and enders of block comments as they were before the filling. This means that a comment ender on the same line as the paragraph being filled will be filled with the paragraph, and one on a line by itself will stay as it is. The comment starter is handled similarly@footnote{This means that the variables @code{c-hanging-comment-starter-p} and @code{c-hanging-comment-ender-p}, which controlled this behavior in earlier versions of @ccmode{}, are now obsolete.}. @kindex M-j @findex c-indent-new-comment-line @findex indent-new-comment-line (c-) @item @kbd{M-j} (@code{c-indent-new-comment-line}) This is the replacement for @code{indent-new-comment-line}. It breaks the line at point and indents the new line like the current one. @vindex comment-multi-line If inside a comment and @code{comment-multi-line} is non-@code{nil}, the indentation and line prefix are preserved. If inside a comment and @code{comment-multi-line} is @code{nil}, a new comment of the same type is started on the next line and indented as appropriate for comments. @findex c-context-line-break @findex context-line-break (c-) @item @kbd{M-x c-context-line-break} This is a function that works like @code{indent-new-comment-line} in comments and @code{newline-and-indent} elsewhere, thus combining those two in a way that uses each one in the context it's best suited for. I.e. in comments the comment line prefix and indentation is kept for the new line, and in normal code it's indented according to context by the indentation engine. It's not bound to a key by default, but it's intended to be used on the @kbd{RET} key. If you like the behavior of @code{newline-and-indent} on @kbd{RET}, you might consider switching to this function. @end table @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @node Commands, Customizing Indentation, Text Filling and Line Breaking, Top @comment node-name, next, previous, up @chapter Commands @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @menu * Indentation Commands:: * Movement Commands:: * Other Commands:: @end menu See also @ref{Text Filling and Line Breaking}, for commands concerning that bit. @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @node Indentation Commands, Movement Commands, , Commands @comment node-name, next, previous,up @section Indentation Commands @cindex indentation commands @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! The following list of commands re-indent C constructs. Note that when you change your coding style, either interactively or through some other means, your file does @emph{not} automatically get re-indented. You will need to execute one of the following commands to see the effects of your changes. @cindex GNU indent program Also, variables like @code{c-hanging-*} and @code{c-cleanup-list} only affect how on-the-fly code is formatted. Changing the ``hanginess'' of a brace and then re-indenting, will not move the brace to a different line. For this, you're better off getting an external program like GNU @code{indent}, which will re-arrange brace location, among other things. Re-indenting large sections of code can take a long time. When @ccmode{} reindents a region of code, it is essentially equivalent to hitting @kbd{TAB} on every line of the region. Especially vulnerable is code generator output@footnote{In particular, I have had people complain about the speed with which @code{lex(1)} output is re-indented. Lex, yacc, and other code generators usually output some pretty perversely formatted code. Re-indenting such code will be slow.}. These commands are useful when indenting code: @table @asis @kindex TAB @findex c-indent-command @findex indent-command (c-) @item @kbd{TAB} (@code{c-indent-command}) Indents the current line. The actual behavior is controlled by several variables, described below. See @code{c-tab-always-indent}, @code{c-insert-tab-function}, and @code{indent-tabs-mode}. With a numeric argument, this command rigidly indents the region, preserving the relative indentation among the lines. @kindex M-C-q @findex c-indent-exp @findex indent-exp (c-) @item @kbd{M-C-q} (@code{c-indent-exp}) Indent an entire balanced brace or parenthesis expression. Note that point must be on the opening brace or parenthesis of the expression you want to indent. @kindex C-c C-q @findex c-indent-defun @findex indent-defun (c-) @item @kbd{C-c C-q} (@code{c-indent-defun}) Indents the entire top-level function or class definition encompassing point. It leaves point unchanged. This function can't be used to re-indent a nested brace construct, such as a nested class or function, or a Java method. The top-level construct being re-indented must be complete, i.e. it must have both a beginning brace and an ending brace. @kindex M-C-\ @findex indent-region @item @kbd{M-C-\} (@code{indent-region}) Indents an arbitrary region of code. This is a standard Emacs command, tailored for C code in a @ccmode{} buffer. Note that of course, point and mark must delineate the region you want to indent. @kindex M-C-h @findex c-mark-function @findex mark-function (c-) @item @kbd{M-C-h} (@code{c-mark-function}) While not strictly an indentation command, this is useful for marking the current top-level function or class definition as the current region. As with @code{c-indent-defun}, this command operates on top-level constructs, and can't be used to mark say, a Java method. @end table These variables are also useful when indenting code: @table @code @vindex c-tab-always-indent @vindex tab-always-indent (c-) @kindex TAB @cindex literal @item c-tab-always-indent This variable controls how @kbd{TAB} @code{c-indent-command} operates. When this variable is @code{t}, @kbd{TAB} always just indents the current line. When it is @code{nil}, the line is indented only if point is at the left margin, or on or before the first non-whitespace character on the line, otherwise some whitespace is inserted. If this variable is the symbol @code{other}, then some whitespace is inserted only within strings and comments (literals), an inside preprocessor directives, but the line is always reindented. @vindex c-insert-tab-function @vindex insert-tab-function (c-) @findex tab-to-tab-stop @item c-insert-tab-function When ``some whitespace'' is inserted as described above, what actually happens is that the function stored in @code{c-insert-tab-function} is called. Normally, this just inserts a real tab character, or the equivalent number of spaces, depending on @code{indent-tabs-mode}. Some people, however, set @code{c-insert-tab-function} to @code{tab-to-tab-stop} so as to get hard tab stops when indenting. @vindex indent-tabs-mode @item indent-tabs-mode This is a standard Emacs variable that controls how line indentation is composed. When this variable is non-@code{nil}, then tabs can be used in a line's indentation, otherwise only spaces can be used. @vindex c-progress-interval @vindex progress-interval (c-) @item c-progress-interval When indenting large regions of code, this variable controls how often a progress message is displayed. Set this variable to @code{nil} to inhibit the progress messages, or set it to an integer which is the interval in seconds that progress messages are displayed. @end table @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @node Movement Commands, Other Commands, Indentation Commands, Commands @comment node-name, next, previous, up @section Movement Commands @cindex movement commands @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @ccmode{} contains some useful command for moving around in C code. @table @asis @findex c-beginning-of-defun @findex beginning-of-defun (c-) @findex beginning-of-defun @item @kbd{M-x c-beginning-of-defun} Moves point back to the least-enclosing brace. This function is analogous to the Emacs built-in command @code{beginning-of-defun}, except it eliminates the constraint that the top-level opening brace must be in column zero. See @code{beginning-of-defun} for more information. Depending on the coding style being used, you might prefer @code{c-beginning-of-defun} to @code{beginning-of-defun}. If so, consider binding @kbd{C-M-a} to the former instead. For backwards compatibility reasons, the default binding remains in effect. @findex c-end-of-defun @findex end-of-defun (c-) @findex end-of-defun @item @kbd{M-x c-end-of-defun} Moves point to the end of the current top-level definition. This function is analogous to the Emacs built-in command @code{end-of-defun}, except it eliminates the constraint that the top-level opening brace of the defun must be in column zero. See @code{beginning-of-defun} for more information. Depending on the coding style being used, you might prefer @code{c-end-of-defun} to @code{end-of-defun}. If so, consider binding @kbd{C-M-e} to the former instead. For backwards compatibility reasons, the default binding remains in effect. @kindex C-c C-u @findex c-up-conditional @findex up-conditional (c-) @item @kbd{C-c C-u} (@code{c-up-conditional}) Move point back to the containing preprocessor conditional, leaving the mark behind. A prefix argument acts as a repeat count. With a negative argument, move point forward to the end of the containing preprocessor conditional. @samp{#elif} is treated like @samp{#else} followed by @samp{#if}, so the function stops at them when going backward, but not when going forward. @findex c-up-conditional-with-else @findex up-conditional-with-else (c-) @item @kbd{M-x c-up-conditional-with-else} A variety of @code{c-up-conditional} that also stops at @samp{#else} lines. Normally those lines are ignored. @findex c-down-conditional @findex down-conditional (c-) @item @kbd{M-x c-down-conditional} Move point forward into the next nested preprocessor conditional, leaving the mark behind. A prefix argument acts as a repeat count. With a negative argument, move point backward into the previous nested preprocessor conditional. @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. @findex c-down-conditional-with-else @findex down-conditional-with-else (c-) @item @kbd{M-x c-down-conditional-with-else} A variety of @code{c-down-conditional} that also stops at @samp{#else} lines. Normally those lines are ignored. @kindex C-c C-p @findex c-backward-conditional @findex backward-conditional (c-) @item @kbd{C-c C-p} (@code{c-backward-conditional}) Move point back over a preprocessor conditional, leaving the mark behind. A prefix argument acts as a repeat count. With a negative argument, move forward. @kindex C-c C-n @findex c-forward-conditional @findex forward-conditional (c-) @item @kbd{C-c C-n} (@code{c-forward-conditional}) Move point forward across a preprocessor conditional, leaving the mark behind. A prefix argument acts as a repeat count. With a negative argument, move backward. @kindex M-a @findex c-beginning-of-statement @findex beginning-of-statement (c-) @item @kbd{M-a} (@code{c-beginning-of-statement}) Move point to the beginning of the innermost C statement. If point is already at the beginning of a statement, it moves to the beginning of the closest preceding statement, even if that means moving into a block (you can use @kbd{M-C-b} to move over a balanced block). With prefix argument @var{n}, move back @var{n} @minus{} 1 statements. If point is within a comment, or next to a comment, this command moves by sentences instead of statements. When called from a program, this function takes three optional arguments: the numeric prefix argument, a buffer position limit which is the farthest back to search, and a flag to enable moving by sentence inside comments. @kindex M-e @findex c-end-of-statement @findex end-of-statement (c-) @item @kbd{M-e} (@code{c-end-of-statement}) Move point to the end of the innermost C statement. If point is at the end of a statement, move to the end of the next statement, even if it's inside a nested block (use @kbd{M-C-f} to move to the other side of the block). With prefix argument @var{n}, move forward @var{n} @minus{} 1 statements. If point is within a comment, or next to a comment, this command moves by sentences instead of statements. When called from a program, this function takes three optional arguments: the numeric prefix argument, a buffer position limit which is the farthest back to search, and a flag to enable moving by sentence inside comments. @findex c-forward-into-nomenclature @findex forward-into-nomenclature (c-) @item @kbd{M-x c-forward-into-nomenclature} A popular programming style, especially for object-oriented languages such as C++ is to write symbols in a mixed case format, where the first letter of each word is capitalized, and not separated by underscores. E.g. @samp{SymbolsWithMixedCaseAndNoUnderlines}. This command moves point forward to next capitalized word. With prefix argument @var{n}, move @var{n} times. @findex c-backward-into-nomenclature @findex backward-into-nomenclature (c-) @item @kbd{M-x c-backward-into-nomenclature} Move point backward to beginning of the next capitalized word. With prefix argument @var{n}, move @var{n} times. If @var{n} is negative, move forward. @end table @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @node Other Commands, , Movement Commands, Commands @comment node-name, next, previous, up @section Other Commands @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @ccmode{} contains a few other useful commands: @table @asis @kindex C-c : @findex c-scope-operator @findex scope-operator (c-) @item @kbd{C-c :} (@code{c-scope-operator}) In C++, it is also sometimes desirable to insert the double-colon scope operator without performing the electric behavior of colon insertion. @kbd{C-c :} does just this. @kindex C-c C-\ @findex c-backslash-region @findex backslash-region (c-) @item @kbd{C-c C-\} (@code{c-backslash-region}) This function is handy when editing macros split over several lines by ending each line with a backslash. It inserts and aligns, or deletes these end-of-line backslashes in the current region. @vindex c-backslash-column @vindex backslash-column (c-) With no prefix argument, it inserts any missing backslashes and aligns them to the column specified by the @code{c-backslash-column} style variable. With a prefix argument, it deletes any backslashes. The function does not modify blank lines at the start of the region. If the region ends at the start of a line, it always deletes the backslash (if any) at the end of the previous line. @end table @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @node Customizing Indentation, Syntactic Symbols, Commands, Top @comment node-name, next, previous, up @chapter Customizing Indentation @cindex customizing indentation @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @vindex c-offsets-alist @vindex offsets-alist (c-) The style variable @code{c-offsets-alist} contains the mappings between syntactic symbols and the offsets to apply for those symbols. It's set at mode initialization from a @emph{style} you may specify. Styles are groupings of syntactic symbol offsets and other style variable values. Most likely, you'll find that one of the pre-defined styles will suit your needs. @xref{Styles}, for an explanation of how to set up named styles. Only syntactic symbols not already bound on @code{c-offsets-alist} will be set from styles. This means that any association you set on it, be it before or after mode initialization, will not be changed. The @code{c-offsets-alist} variable may therefore be used from e.g. the Customization interface@footnote{Available in Emacs 20 and later, and XEmacs 19.15 and later.} to easily change indentation offsets without having to bother about styles. Initially @code{c-offsets-alist} is empty, so that all syntactic symbols are set by the style system. @kindex C-c C-o @findex c-set-offset @findex set-offset (c-) You can use the command @kbd{C-c C-o} (@code{c-set-offset}) as the way to set offsets, both interactively and from your mode hook@footnote{Obviously, you use the keybinding interactively, and the function call programmatically!}. @vindex c-basic-offset @vindex basic-offset (c-) The offset associated with any particular syntactic symbol can be any of an integer, a function or lambda expression, a variable name, or one of the following symbols: @code{+}, @code{-}, @code{++}, @code{--}, @code{*}, or @code{/}. These latter describe offset in multiples of the value of the style variable @code{c-basic-offset}. By defining a style's indentation in terms of this fundamental variable, you can change the amount of whitespace given to an indentation level while maintaining the same basic shape of your code. Here are the values that the special symbols correspond to: @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 @cindex indentation functions When a function is used as offset, it's called an @dfn{indentation function}. Such functions are useful when more context than just the syntactic symbol is needed to get the desired indentation. @xref{Indentation Functions}, and @ref{Custom Indentation Functions}, for details about them. @vindex c-strict-syntax-p @vindex strict-syntax-p (c-) The offset can also be a list, in which case it is evaluated recursively using the semantics described above. The first element of the list that returns a non-@code{nil} value succeeds and the evaluation stops. If none of the list elements return a non-@code{nil} value, then an offset of 0 (zero) is used@footnote{There is however a variable @code{c-strict-syntax-p} that, when set to non-@code{nil}, will cause an error to be signalled in that case. It's now considered obsolete since it doesn't work well with some of the alignment functions that now returns @code{nil} instead of zero to be more usable in lists. You should therefore leave @code{c-strict-syntax-p} set to @code{nil}.}. So, for example, because most of the default offsets are defined in terms of @code{+}, @code{-}, and @code{0}, if you like the general indentation style, but you use 4 spaces instead of 2 spaces per level, you can probably achieve your style just by changing @code{c-basic-offset} like so@footnote{You can try this interactively in a C buffer by typing the text that appears in italics.}: @example @emph{M-x set-variable RET} Set variable: @emph{c-basic-offset RET} Set c-basic-offset to value: @emph{4 RET} @end example @noindent This would change @example @group int add( int val, int incr, int doit ) @{ if( doit ) @{ return( val + incr ); @} return( val ); @} @end group @end example @noindent to @example @group int add( int val, int incr, int doit ) @{ if( doit ) @{ return( val + incr ); @} return( val ); @} @end group @end example To change indentation styles more radically, you will want to change the offsets associated with other syntactic symbols. First, I'll show you how to do that interactively, then I'll describe how to make changes to your @file{.emacs} file so that your changes are more permanent. @menu * Interactive Customization:: * Permanent Customization:: * Hooks:: * Styles:: * Advanced Customizations:: @end menu @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @node Interactive Customization, Permanent Customization, , Customizing Indentation @comment node-name, next, previous, up @section Interactive Customization @cindex interactive customization @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! As an example of how to customize indentation, let's change the style of this example@footnote{In this an subsequent examples, the original code is formatted using the @samp{gnu} style unless otherwise indicated. @xref{Styles}.}: @example @group 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 components 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 may not always work. The general approach to take is to always start adjusting offsets for lines higher up in the file, then re-indent and see if any following lines need further adjustments. @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @node Permanent Customization, Hooks, Interactive Customization, Customizing Indentation @comment node-name, next, previous, up @section Permanent Customization @cindex permanent customization @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! To make your changes permanent, you need to add some lisp code to your @file{.emacs} file. @ccmode{} supports many different ways to be configured, from the straightforward way by setting variables globally in @file{.emacs} or in the Customization interface, to the complex and precisely controlled way by using styles and hook functions. The simplest way of customizing @ccmode{} permanently is to set the variables in your @file{.emacs} with @code{setq} and similar commands. So to make the setting of @code{substatement-open} permanent, add this to the @file{.emacs} file: @example @group (require 'cc-mode) (c-set-offset 'substatement-open 0) @end group @end example The @code{require} line is only needed once in the beginning to make sure @ccmode{} is loaded so that the @code{c-set-offset} function is defined. You can also use the more user friendly Customization interface, but this manual does not cover how that works. Variables set like this at the top level in @file{.emacs} take effect in all @ccmode{} buffers, regardless of language. The indentation style related variables, e.g. @code{c-basic-offset}, that you don't set this way get their value from the style system (@pxref{Styles}), and they therefore depend on the setting of @code{c-default-style}. Note that if you use Customize, this means that the greyed-out default values presented there might not be the ones you actually get, since the actual values depend on the style, which may very well be different for different languages. If you want to make more advanced configurations, e.g. language-specific customization, global variable settings isn't enough. For that you can use the language hooks, see @ref{Hooks}, and/or the style system, see @ref{Styles}. @vindex c-style-variables-are-local-p @vindex style-variables-are-local-p (c-) By default, all style variables are global, so that every buffer will share the same style settings. This is fine if you primarily edit one style of code, but if you edit several languages and want to use different styles for them, you need finer control by making the style variables buffer local. The recommended way to do this is to set the variable @code{c-style-variables-are-local-p} to @code{t}. The variables will be made buffer local when @ccmode{} is activated in a buffer for the first time in the Emacs session. Note that once the style variables are made buffer local, they cannot be made global again, without restarting Emacs. @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @node Hooks, Styles, Permanent Customization, Customizing Indentation @comment node-name, next, previous, up @section Hooks @cindex hooks @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @vindex c-mode-common-hook @vindex mode-common-hook (c-) @vindex c-mode-hook @vindex c++-mode-hook @vindex objc-mode-hook @vindex java-mode-hook @vindex idl-mode-hook @vindex pike-mode-hook @vindex c-initialization-hook @vindex initialization-hook (c-) @ccmode{} provides several hooks that you can use to customize the mode according to your coding style. Each language mode has its own hook, adhering to standard Emacs major mode conventions. There is also one general hook and one package initialization hook: @itemize @bullet @item @code{c-mode-hook} --- For C buffers only. @item @code{c++-mode-hook} --- For C++ buffers only. @item @code{objc-mode-hook} --- For Objective-C buffers only. @item @code{java-mode-hook} --- For Java buffers only. @item @code{idl-mode-hook} --- For CORBA IDL buffers only. @item @code{pike-mode-hook} --- For Pike buffers only. @item @code{c-mode-common-hook} --- Common across all languages. @item @code{c-initialization-hook} --- Hook run only once per Emacs session, when @ccmode{} is initialized. @end itemize The language hooks get run as the last thing when you enter that language mode. The @code{c-mode-common-hook} is run by all supported modes @emph{before} the language specific hook, and thus can contain customizations that are common across all languages. Most of the examples in this section will assume you are using the common hook.@footnote{@code{java-mode} and the hook variables interact in a slightly different way than the other modes. @code{java-mode} normally sets the style of the buffer to @samp{java} @emph{before} running the @code{c-mode-common-hook} or @code{java-mode-hook}. You need to be aware of this so that style settings in @code{c-mode-common-hook} don't clobber your Java style. This is arguably bogus, but it's kept for historical reasons. @xref{Built-in Styles}, the documentation of @code{c-default-style}, for details.} Here's a simplified example of what you can add to your @file{.emacs} file to do things whenever any @ccmode{} language is edited. See the Emacs manuals for more information on customizing Emacs via hooks. @xref{Sample .emacs File}, for a more complete sample @file{.emacs} file. @example @group (defun my-c-mode-common-hook () ;; my customizations for all of c-mode and related modes (no-case-fold-search) ) (add-hook 'c-mode-common-hook 'my-c-mode-common-hook) @end group @end example @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @node Styles, Advanced Customizations, Hooks, Customizing Indentation @comment node-name, next, previous, up @section Styles @cindex styles @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! 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. @cindex style variables The variables that the style system affect are called @dfn{style variables}. They are handled specially in several ways: @itemize @bullet @item Style variables are by default global variables, i.e. they have the same value in all Emacs buffers. However, they can instead be made always buffer local by setting @code{c-style-variables-are-local-p} to non-@code{nil} before @ccmode{} is initialized. @vindex c-old-style-variable-behavior @vindex old-style-variable-behavior (c-) @item The default value of any style variable (with two exceptions --- see below) is the special symbol @code{set-from-style}. Variables that are still set to that symbol when a @ccmode{} buffer is initialized will be set according to the current style, otherwise they will keep their current value@footnote{This is a big change from versions of @ccmode{} earlier than 5.26, where such settings would get overridden by the style system unless special precautions were taken. That was changed since it was counterintuitive and confusing, especially to novice users. If your configuration depends on the old overriding behavior, you can set the variable @code{c-old-style-variable-behavior} to non-@code{nil}.}. Note that when we talk about the ``default value'' for a style variable, we don't mean the @code{set-from-style} symbol that all style variables are set to initially, but instead the value it will get at mode initialization when neither a style nor a global setting has set its value. The style variable @code{c-offsets-alist} is handled a little differently from the other style variables. It's an association list, and is thus by default set to the empty list, @code{nil}. When the style system is initialized, any syntactic symbols already on it are kept --- only the missing ones are filled in from the chosen style. The style variable @code{c-special-indent-hook} is also handled in a special way. Styles may only add more functions on this hook, so the global settings on it are always preserved@footnote{This did not change in version 5.26.}. @item The global settings of style variables get captured in the special @code{user} style, which is used as the base for all the other styles. @xref{Built-in Styles}, for details. @end itemize The style variables are: @code{c-basic-offset}, @code{c-comment-only-line-offset}, @code{c-block-comment-prefix}, @code{c-comment-prefix-regexp}, @code{c-cleanup-list}, @code{c-hanging-braces-alist}, @code{c-hanging-colons-alist}, @code{c-hanging-semi&comma-criteria}, @code{c-backslash-column}, @code{c-special-indent-hook}, @code{c-label-minimum-indentation}, and @code{c-offsets-alist}. @menu * Built-in Styles:: * Adding Styles:: * File Styles:: @end menu @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @node Built-in Styles, Adding Styles, , Styles @comment node-name, next, previous, up @subsection Built-in Styles @cindex built-in styles @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! If you're lucky, one of @ccmode{}'s built-in styles might be just what you're looking for. These include: @itemize @bullet @cindex GNU style @item @code{gnu} --- Coding style blessed by the Free Software Foundation for C code in GNU programs. @cindex K&R style @item @code{k&r} --- The classic Kernighan and Ritchie style for C code. @cindex BSD style @item @code{bsd} --- Also known as ``Allman style'' after Eric Allman. @cindex Whitesmith style @item @code{whitesmith} --- Popularized by the examples that came with Whitesmiths C, an early commercial C compiler. @cindex Stroustrup style @item @code{stroustrup} --- The classic Stroustrup style for C++ code. @cindex Ellemtel style @item @code{ellemtel} --- Popular C++ coding standards as defined by ``Programming in C++, Rules and Recommendations'', Erik Nyquist and Mats Henricson, Ellemtel@footnote{This document is available at @uref{http://www.doc.ic.ac.uk/lab/cplus/c++.rules/} among other places.}. @cindex Linux style @item @code{linux} --- C coding standard for Linux development. @cindex Python style @item @code{python} --- C coding standard for Python extension modules@footnote{Python is a high level scripting language with a C/C++ foreign function interface. For more information, see @uref{http://www.python.org/}.}. @cindex Java style @findex java-mode @item @code{java} --- The style for editing Java code. Note that this style is automatically installed when you enter @code{java-mode}. @cindex User style @item @code{user} --- This is a special style for several reasons. First, the @ccmode{} customizations you do by using either the Customization interface, or by writing @code{setq}'s at the top level of your @file{.emacs} file, will be captured in the @code{user} style. Also, all other styles implicitly inherit their settings from @code{user} style. This means that for any styles you add via @code{c-add-style} (@pxref{Adding Styles}) you need only define the differences between your new style and @code{user} style. @end itemize @vindex c-default-style @vindex default-style (c-) The default style in all newly created buffers is @code{gnu}, but you can change this by setting variable @code{c-default-style}. Although the @code{user} style is not the default style, any style variable settings you do with the Customization interface or on the top level in your @file{.emacs} file will by default override the style system, so you don't need to set @code{c-default-style} to @code{user} to see the effect of these settings. @code{c-default-style} takes either a style name string, or an association list of major mode symbols to style names. Thus you can control exactly which default style is used for which @ccmode{} language mode. Here are the rules: @vindex c-style-alist @vindex style-alist (c-) @vindex c-mode-common-hook @vindex mode-common-hook (c-) @enumerate @item When @code{c-default-style} is a string, it must be an existing style name as found in @code{c-style-alist}. This style is then used for all modes @emph{except} @code{java-mode}, where the style @samp{java} is used by default@footnote{This is for backwards compatibility reasons. The hard-coding of @code{java-mode} style is admittedly bogus!}. @item When @code{c-default-style} is an association list, the current major mode is looked up to find a style name string. In this case, this style is always used exactly as specified and an error will occur if the named style does not exist. @item If @code{c-default-style} is an association list, but the current major mode isn't found, then the special symbol @samp{other} is looked up. If this value is found, the associated style is used. @item If @samp{other} is not found, then the @samp{gnu} style is used. @item 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}. @end enumerate @findex c-set-style @findex set-style (c-) @kindex C-c . If you'd like to experiment with these built-in styles you can simply type the following in a @ccmode{} buffer: @example @group @kbd{C-c . @var{STYLE-NAME} RET} @end group @end example @noindent @kbd{C-c .} runs the command @code{c-set-style}. Note that all style names are case insensitive, even the ones you define. Setting a style in this way does @emph{not} automatically re-indent your file. For commands that you can use to view the effect of your changes, see @ref{Commands}. @vindex c-indentation-style @vindex indentation-style (c-) Note that for BOCM compatibility, @samp{gnu} is the default style, and any non-style based customizations you make (i.e. in @code{c-mode-common-hook} in your @file{.emacs} file) will be based on @samp{gnu} style unless you set @code{c-default-style} or do a @code{c-set-style} as the first thing in your hook. The variable @code{c-indentation-style} always contains the buffer's current style name, as a string. @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @node Adding Styles, File Styles, Built-in Styles, Styles @comment node-name, next, previous, up @subsection Adding Styles @cindex adding styles @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @vindex c-style-alist @vindex style-alist (c-) @findex c-add-style @findex add-style (c-) If none of the built-in styles is appropriate, you'll probably want to add a new @dfn{style definition}. Styles are kept in the @code{c-style-alist} variable, but you should never modify this variable directly. Instead, @ccmode{} provides the function @code{c-add-style} that you can use to easily add new styles or change existing styles. This function takes two arguments, a @var{stylename} string, and an association list @var{description} of style customizations. If @var{stylename} is not already in @code{c-style-alist}, the new style is added, otherwise the style is changed to the new @var{description}. This function also takes an optional third argument, which if non-@code{nil}, automatically applies the new style to the current buffer. @comment TBD: The next paragraph is bogus. I really need to better @comment document adding styles, including setting up inherited styles. The sample @file{.emacs} file provides a concrete example of how a new style can be added and automatically set. @xref{Sample .emacs File}. @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @node File Styles, , Adding Styles, Styles @comment node-name, next, previous, up @subsection File Styles @cindex file styles @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @cindex local variables The Emacs manual describes how you can customize certain variables on a per-file basis by including a @dfn{Local Variable} block at the end of the file. So far, you've only seen a functional interface to @ccmode{} customization, which is highly inconvenient for use in a Local Variable block. @ccmode{} provides two variables that make it easier for you to customize your style on a per-file basis. @vindex c-file-style @vindex file-style (c-) @vindex c-file-offsets @vindex file-offsets (c-) The variable @code{c-file-style} can be set to a style name string. When the file is visited, @ccmode{} will automatically set the file's style to this style using @code{c-set-style}. Another variable, @code{c-file-offsets}, takes an association list similar to what is allowed in @code{c-offsets-alist}. When the file is visited, @ccmode{} will automatically institute these offsets using @code{c-set-offset}. Note that file style settings (i.e. @code{c-file-style}) are applied before file offset settings (i.e. @code{c-file-offsets}). Also, if either of these are set in a file's local variable section, all the style variable values are made local to that buffer. @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @node Advanced Customizations, , Styles, Customizing Indentation @comment node-name, next, previous, up @section Advanced Customizations @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @vindex c-style-alist @vindex style-alist (c-) For most users, @ccmode{} will support their coding styles with very little need for more advanced customizations. Usually, one of the standard styles defined in @code{c-style-alist} will do the trick. At most, perhaps one of the syntactic symbol offsets will need to be tweaked slightly, or maybe @code{c-basic-offset} will need to be changed. However, some styles require a more flexible framework for customization, and one of the real strengths of @ccmode{} is that the syntactic analysis model provides just such a framework. This allows you to implement custom indentation calculations for situations not handled by the mode directly. @menu * Custom Indentation Functions:: * Custom Brace and Colon Hanging:: * Customizing Semi-colons and Commas:: * Other Special Indentations:: @end menu @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @node Custom Indentation Functions, Custom Brace and Colon Hanging, , Advanced Customizations @comment node-name, next, previous, up @subsection Custom Indentation Functions @cindex custom indentation functions @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! The most flexible way to customize @ccmode{} is by writing custom indentation functions, and associating them with specific syntactic symbols (@pxref{Syntactic Symbols}). @ccmode{} itself uses indentation functions to provide more sophisticated indentation, for example when lining up C++ stream operator blocks: @example @group 1: void main(int argc, char**) 2: @{ 3: cout << "There were " 4: << argc 5: << "arguments passed to the program" 6: << endl; 7: @} @end group @end example In this example, lines 4 through 6 are assigned the @code{stream-op} syntactic symbol. Here, @code{stream-op} has an offset of @code{+}, and with a @code{c-basic-offset} of 2, you can see that lines 4 through 6 are simply indented two spaces to the right of line 3. But perhaps we'd like @ccmode{} to be a little more intelligent so that it aligns all the @samp{<<} symbols in lines 3 through 6. To do this, we have to write a custom indentation function which finds the column of first stream operator on the first line of the statement. Here is sample lisp code implementing this: @example @group (defun c-lineup-streamop (langelem) ;; lineup stream operators (save-excursion (let* ((relpos (cdr langelem)) (curcol (progn (goto-char relpos) (current-column)))) (re-search-forward "<<\\|>>" (c-point 'eol) 'move) (goto-char (match-beginning 0)) (- (current-column) curcol)))) @end group @end example @noindent Indentation functions take a single argument, which is a syntactic component cons cell (@pxref{Syntactic Analysis}). The function returns an integer offset value that will be added to the running total indentation for the line. Note that what actually gets returned is the difference between the column that the first stream operator is on, and the column of the buffer relative position passed in the function's argument. Remember that @ccmode{} automatically adds in the column of the component's relative buffer position and we don't the column offset added in twice. The function should return @code{nil} if it's used in a situation where it doesn't want to do any decision. If the function is used in a list expression (@pxref{Customizing Indentation}), that will cause @ccmode{} to go on and check the next entry in the list. @cindex stream-op syntactic symbol @findex c-lineup-streamop @findex lineup-streamop (c-) Now, to associate the function @code{c-lineup-streamop} with the @code{stream-op} syntactic symbol, we can add something like the following to our @code{c++-mode-hook}@footnote{It probably makes more sense to add this to @code{c++-mode-hook} than @code{c-mode-common-hook} since stream operators are only relevant for C++.}: @example (c-set-offset 'stream-op 'c-lineup-streamop) @end example Now the function looks like this after re-indenting (using @kbd{C-c C-q}): @example @group 1: void main(int argc, char**) 2: @{ 3: cout << "There were " 4: << argc 5: << " arguments passed to the program" 6: << endl; 7: @} @end group @end example Custom indentation functions can be as simple or as complex as you like, and any syntactic symbol that appears in @code{c-offsets-alist} can have a custom indentation function associated with it. @ccmode{} comes with an extensive set of predefined indentation functions, not all of which are used by the default styles. So there's a good chance the function you want already exists. @xref{Indentation Functions}, for a list of them. If you have written an indentation function that you think is generally useful, you're very welcome to contribute it; please contact @email{bug-cc-mode@@gnu.org}. @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @node Custom Brace and Colon Hanging, Customizing Semi-colons and Commas, Custom Indentation Functions, Advanced Customizations @comment node-name, next, previous, up @subsection Custom Brace and Colon Hanging @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @vindex c-hanging-braces-alist @vindex hanging-braces-alist (c-) Syntactic symbols aren't the only place where you can customize @ccmode{} with the lisp equivalent of callback functions. Brace ``hanginess'' can also be determined by custom functions associated with syntactic symbols on the @code{c-hanging-braces-alist} style variable. Remember that @var{ACTION}'s are typically a list containing some combination of the symbols @code{before} and @code{after} (@pxref{Hanging Braces}). However, an @var{ACTION} can also be a function which gets called when a brace matching that syntactic symbol is entered. @cindex customizing brace hanging These @var{ACTION} functions are called with two arguments: the syntactic symbol for the brace, and the buffer position at which the brace was inserted. The @var{ACTION} function is expected to return a list containing some combination of @code{before} and @code{after}, including neither of them (i.e. @code{nil}). This return value has the normal brace hanging semantics. As an example, @ccmode{} itself uses this feature to dynamically determine the hanginess of braces which close ``do-while'' constructs: @example @group void do_list( int count, char** atleast_one_string ) @{ int i=0; do @{ handle_string( atleast_one_string[i] ); i++; @} while( i < count ); @} @end group @end example @findex c-snug-do-while @findex snug-do-while (c-) @ccmode{} assigns the @code{block-close} syntactic symbol to the brace that closes the @code{do} construct, and normally we'd like the line that follows a @code{block-close} brace to begin on a separate line. However, with ``do-while'' constructs, we want the @code{while} clause to follow the closing brace. To do this, we associate the @code{block-close} symbol with the @var{ACTION} function @code{c-snug-do-while}: @example (defun c-snug-do-while (syntax pos) "Dynamically calculate brace hanginess for do-while statements. Using this function, `while' clauses that end a `do-while' block will remain on the same line as the brace that closes that block. See `c-hanging-braces-alist' for how to utilize this function as an ACTION associated with `block-close' syntax." (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 This function simply looks to see if the brace closes a ``do-while'' clause and if so, returns the list @samp{(before)} indicating that a newline should be inserted before the brace, but not after it. In all other cases, it returns the list @samp{(before after)} so that the brace appears on a line by itself. @vindex c-syntactic-context @vindex syntactic-context (c-) During the call to the brace hanging @var{ACTION} function, the variable @code{c-syntactic-context} is bound to the full syntactic analysis list. @cindex customizing colon hanging @vindex c-hanging-colon-alist @vindex hanging-colon-alist (c-) Note that for symmetry, colon hanginess should be customizable by allowing function symbols as @var{ACTION}s on the @code{c-hanging-colon-alist} style variable. Since no use has actually been found for this feature, it isn't currently implemented! @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @node Customizing Semi-colons and Commas, Other Special Indentations, Custom Brace and Colon Hanging, Advanced Customizations @comment node-name, next, previous, up @subsection Customizing Semi-colons and Commas @cindex customizing semi-colons and commas @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @vindex c-hanging-semi&comma-criteria @vindex hanging-semi&comma-criteria (c-) You can also customize the insertion of newlines after semi-colons and commas, when the auto-newline minor mode is enabled (@pxref{Minor Modes}). This is controlled by the style variable @code{c-hanging-semi&comma-criteria}, which contains a list of functions that are called in the order they appear. Each function is called with zero arguments, and is expected to return one of the following values: @itemize @bullet @item non-@code{nil} --- A newline is inserted, and no more functions from the list are called. @item @code{stop} --- No more functions from the list are called, but no newline is inserted. @item @code{nil} --- No determination is made, and the next function in the list is called. @end itemize If every function in the list is called without a determination being made, then no newline is added. The default value for this variable is a list containing a single function which inserts newlines only after semi-colons which do not appear inside parenthesis lists (i.e. those that separate @code{for}-clause statements). @findex c-semi&comma-no-newlines-before-nonblanks @findex semi&comma-no-newlines-before-nonblanks (c-) Here's an example of a criteria function, provided by @ccmode{}, that will prevent newlines from being inserted after semicolons when there is a non-blank following line. Otherwise, it makes no determination. To use, add this to the front of the @code{c-hanging-semi&comma-criteria} list. @example @group (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 group @end example @findex c-semi&comma-inside-parenlist @findex c-semi&comma-no-newlines-for-oneline-inliners @findex semi&comma-inside-parenlist (c-) @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 (i.e. in C++ or Java). @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @node Other Special Indentations, , Customizing Semi-colons and Commas, Advanced Customizations @comment node-name, next, previous, up @subsection Other Special Indentations @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @vindex c-label-minimum-indentation @vindex label-minimum-indentation (c-) In @samp{gnu} style (@pxref{Built-in Styles}), a minimum indentation is imposed on lines inside top-level constructs. This minimum indentation is controlled by the style variable @code{c-label-minimum-indentation}. The default value for this variable is 1. @vindex c-special-indent-hook @vindex special-indent-hook (c-) One other customization variable is available in @ccmode{}: The style variable @code{c-special-indent-hook}. This is a standard hook variable that is called after every line is indented by @ccmode{}. You can use it to do any special indentation or line adjustments your style dictates, such as adding extra indentation to constructors or destructor declarations in a class definition, etc. Note however, that you should not change point or mark inside your @code{c-special-indent-hook} functions (i.e. you'll probably want to wrap your function in a @code{save-excursion}). Setting @code{c-special-indent-hook} in your style definition is handled slightly differently than other variables. In your style definition, you should set the value for @code{c-special-indent-hook} to a function or list of functions, which will be appended to @code{c-special-indent-hook} using @code{add-hook}. That way, the current setting for the buffer local value of @code{c-special-indent-hook} won't be overridden. @kindex M-; @findex indent-for-comment @vindex c-indent-comments-syntactically-p @vindex indent-comments-syntactically-p (c-) @vindex comment-column Normally, the standard Emacs command @kbd{M-;} (@code{indent-for-comment}) will indent comment only lines to @code{comment-column}. Some users however, prefer that @kbd{M-;} act just like @kbd{TAB} for purposes of indenting comment-only lines; i.e. they want the comments to always indent as they would for normal code, regardless of whether @kbd{TAB} or @kbd{M-;} were used. This behavior is controlled by the variable @code{c-indent-comments-syntactically-p}. When @code{nil} (the default), @kbd{M-;} indents comment-only lines to @code{comment-column}, otherwise, they are indented just as they would be if @kbd{TAB} were typed. Note that this has no effect for comment lines that are inserted with @kbd{M-;} at the end of regular code lines. These comments will always start at @code{comment-column}. @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @node Syntactic Symbols, Indentation Functions, Customizing Indentation, Top @comment node-name, next, previous, up @chapter Syntactic Symbols @cindex syntactic symbols @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @vindex c-offsets-alist @vindex offsets-alist (c-) Here is a complete list of the recognized syntactic symbols as described in the @code{c-offsets-alist} style variable, along with a brief description. More detailed descriptions follow. @table @code @item string Inside a multi-line string. @item c Inside a multi-line C style block comment. @item defun-open Brace that opens a top-level function definition. @item defun-close Brace that closes a top-level function definition. @item defun-block-intro The first line in a top-level defun. @item class-open Brace that opens a class definition. @item class-close Brace that closes a class definition. @item inline-open Brace that opens an in-class inline method. @item inline-close Brace that closes an in-class inline method. @item func-decl-cont The region between a function definition's argument list and the function opening brace (excluding K&R argument declarations). In C, you cannot put anything but whitespace and comments in this region, however in C++ and Java, @code{throws} declarations and other things can appear here. @item knr-argdecl-intro First line of a K&R C argument declaration. @item knr-argdecl Subsequent lines in a K&R C argument declaration. @item topmost-intro The first line in a ``topmost'' definition. @item topmost-intro-cont Topmost definition continuation lines. @item member-init-intro First line in a member initialization list. @item member-init-cont Subsequent member initialization list lines. @item inher-intro First line of a multiple inheritance list. @item inher-cont Subsequent multiple inheritance lines. @item block-open Statement block open brace. @item block-close Statement block close brace. @item brace-list-open Open brace of an enum or static array list. @item brace-list-close Close brace of an enum or static array list. @item brace-list-intro First line in an enum or static array list. @item brace-list-entry Subsequent lines in an enum or static array list. @item brace-entry-open Subsequent lines in an enum or static array list where the line begins with an open brace. @item statement A statement. @item statement-cont A continuation of a statement. @item statement-block-intro The first line in a new statement block. @item statement-case-intro The first line in a case block. @item statement-case-open The first line in a case block that starts with a brace. @item substatement The first line after a conditional or loop construct. @item substatement-open The brace that opens a substatement block. @item case-label A @code{case} or @code{default} label. @item access-label C++ access control label. @item label Any non-special C label. @item do-while-closure The @code{while} line that ends a @code{do}-@code{while} construct. @item else-clause The @code{else} line of an @code{if}-@code{else} construct. @item catch-clause The @code{catch} or @code{finally} (in Java) line of a @code{try}-@code{catch} construct. @item comment-intro A line containing only a comment introduction. @item arglist-intro The first line in an argument list. @item arglist-cont Subsequent argument list lines when no arguments follow on the same line as the the arglist opening paren. @item arglist-cont-nonempty Subsequent argument list lines when at least one argument follows on the same line as the arglist opening paren. @item arglist-close The solo close paren of an argument list. @item stream-op Lines continuing a stream operator (C++ only). @item inclass The line is nested inside a class definition. @item cpp-macro The start of a C preprocessor macro definition. @item cpp-macro-cont Subsequent lines of a multi-line C preprocessor macro definition. @item friend A C++ friend declaration. @item objc-method-intro The first line of an Objective-C method. definition. @item objc-method-args-cont Lines continuing an Objective-C method. definition @item objc-method-call-cont Lines continuing an Objective-C method call. @item extern-lang-open Brace that opens an external language block. @item extern-lang-close Brace that closes an external language block. @item inextern-lang Analogous to @code{inclass} syntactic symbol, but used inside external language blocks (e.g. @code{extern "C" @{}). @item namespace-open Brace that opens a C++ namespace block. @item namespace-close Brace that closes a C++ namespace block. @item innamespace Analogous to @code{inextern-lang} syntactic symbol, but used inside C++ namespace blocks. @item template-args-cont C++ template argument list continuations. @item inlambda Analogous to @code{inclass} syntactic symbol, but used inside lambda (i.e. anonymous) functions. Only used in Pike mode. @item lambda-intro-cont Lines continuing the header of a lambda function, i.e. between the @code{lambda} keyword and the function body. Only used in Pike mode. @item inexpr-statement A statement block inside an expression. The gcc C extension of this is recognized. It's also used for the special functions that takes a statement block as an argument in Pike. @item inexpr-class A class definition inside an expression. This is used for anonymous classes in Java. It's also used for anonymous array initializers in Java. @end table @cindex -open syntactic symbols @cindex -close syntactic symbols Most syntactic symbol names follow a general naming convention. When a line begins with an open or close brace, the syntactic symbol will contain the suffix @code{-open} or @code{-close} respectively. @cindex -intro syntactic symbols @cindex -cont syntactic symbols @cindex -block-intro syntactic symbols Usually, a distinction is made between the first line that introduces a construct and lines that continue a construct, and the syntactic symbols that represent these lines will contain the suffix @code{-intro} or @code{-cont} respectively. As a sub-classification of this scheme, a line which is the first of a particular brace block construct will contain the suffix @code{-block-intro}. Let's look at some examples to understand how this works. Remember that you can check the syntax of any line by using @kbd{C-c C-s}. @example @group 1: void 2: swap( int& a, int& b ) 3: @{ 4: int tmp = a; 5: a = b; 6: b = tmp; 7: int ignored = 8: a + b; 9: @} @end group @end example @cindex topmost-intro syntactic symbol @cindex topmost-intro-cont syntactic symbol @cindex defun-open syntactic symbol @cindex defun-close syntactic symbol @cindex defun-block-intro syntactic symbol Line 1 shows a @code{topmost-intro} since it is the first line that introduces a top-level construct. Line 2 is a continuation of the top-level construct introduction so it has the syntax @code{topmost-intro-cont}. Line 3 shows a @code{defun-open} since it is the brace that opens a top-level function definition. Line 9 is the corresponding @code{defun-close} since it contains the brace that closes the top-level function definition. Line 4 is a @code{defun-block-intro}, i.e. it is the first line of a brace-block, enclosed in a top-level function definition. @cindex statement syntactic symbol @cindex statement-cont syntactic symbol Lines 5, 6, and 7 are all given @code{statement} syntax since there isn't much special about them. Note however that line 8 is given @code{statement-cont} syntax since it continues the statement begun on the previous line. Here's another example, which illustrates some C++ class syntactic symbols: @example @group 1: class Bass 2: : public Guitar, 3: public Amplifiable 4: @{ 5: public: 6: Bass() 7: : eString( new BassString( 0.105 )), 8: aString( new BassString( 0.085 )), 9: dString( new BassString( 0.065 )), 10: gString( new BassString( 0.045 )) 11: @{ 12: eString.tune( 'E' ); 13: aString.tune( 'A' ); 14: dString.tune( 'D' ); 15: gString.tune( 'G' ); 16: @} 17: friend class Luthier; 18: @} @end group @end example @cindex class-open syntactic symbol @cindex class-close syntactic symbol As in the previous example, line 1 has the @code{topmost-intro} syntax. Here however, the brace that opens a C++ class definition on line 4 is assigned the @code{class-open} syntax. Note that in C++, classes, structs, and unions are essentially equivalent syntactically (and are very similar semantically), so replacing the @code{class} keyword in the example above with @code{struct} or @code{union} would still result in a syntax of @code{class-open} for line 4 @footnote{This is the case even for C and Objective-C. For consistency, structs in all supported languages are syntactically equivalent to classes. Note however that the keyword @code{class} is meaningless in C and Objective-C.}. Similarly, line 18 is assigned @code{class-close} syntax. @cindex inher-intro syntactic symbol @cindex inher-cont syntactic symbol Line 2 introduces the inheritance list for the class so it is assigned the @code{inher-intro} syntax, and line 3, which continues the inheritance list is given @code{inher-cont} syntax. @cindex access-label syntactic symbol @cindex inclass syntactic symbol Hitting @kbd{C-c C-s} on line 5 shows the following analysis: @example @group @code{((inclass . 58) (access-label . 67))} @end group @end example @noindent The primary syntactic symbol for this line is @code{access-label} as this a label keyword that specifies access protection in C++. However, because this line is also a top-level construct inside a class definition, the analysis actually shows two syntactic symbols. The other syntactic symbol assigned to this line is @code{inclass}. Similarly, line 6 is given both @code{inclass} and @code{topmost-intro} syntax: @example @group @code{((inclass . 58) (topmost-intro . 60))} @end group @end example @cindex member-init-intro syntactic symbol @cindex member-init-cont syntactic symbol Line 7 introduces a C++ member initialization list and as such is given @code{member-init-intro} syntax. Note that in this case it is @emph{not} assigned @code{inclass} since this is not considered a top-level construct. Lines 8 through 10 are all assigned @code{member-init-cont} since they continue the member initialization list started on line 7. @cindex in-class inline methods @cindex inline-open syntactic symbol @cindex inline-close syntactic symbol Line 11's analysis is a bit more complicated: @example @group @code{((inclass . 58) (inline-open))} @end group @end example This line is assigned a syntax of both @code{inline-open} and @code{inclass} because it opens an @dfn{in-class} C++ inline method definition. This is distinct from, but related to, the C++ notion of an inline function in that its definition occurs inside an enclosing class definition, which in C++ implies that the function should be inlined. If though, the definition of the @code{Bass} constructor appeared outside the class definition, the construct would be given the @code{defun-open} syntax, even if the keyword @code{inline} appeared before the method name, as in: @example @group class Bass : public Guitar, public Amplifiable @{ public: Bass(); @} inline Bass::Bass() : eString( new BassString( 0.105 )), aString( new BassString( 0.085 )), dString( new BassString( 0.065 )), gString( new BassString( 0.045 )) @{ eString.tune( 'E' ); aString.tune( 'A' ); dString.tune( 'D' ); gString.tune( 'G' ); @} @end group @end example @cindex friend syntactic symbol Returning to the previous example, line 16 is given @code{inline-close} syntax, while line 12 is given @code{defun-block-open} syntax, and lines 13 through 15 are all given @code{statement} syntax. Line 17 is interesting in that its syntactic analysis list contains three elements: @example @code{((friend) (inclass . 58) (topmost-intro . 380))} @end example The @code{friend} syntactic symbol is a modifier that typically does not have a relative buffer position. Template definitions introduce yet another syntactic symbol: @example @group 1: ThingManager <int, 2: Framework::Callback *, 3: Mutex> framework_callbacks; @end group @end example Here, line 1 is analyzed as a @code{topmost-intro}, but lines 2 and 3 are both analyzed as @code{template-args-cont} lines. Here is another (totally contrived) example which illustrates how syntax is assigned to various conditional constructs: @example @group 1: void spam( int index ) 2: @{ 3: for( int i=0; i<index; i++ ) 4: @{ 5: if( i == 10 ) 6: @{ 7: do_something_special(); 8: @} 9: else 10: do_something( i ); 11: @} 12: do @{ 13: another_thing( i-- ); 14: @} 15: while( i > 0 ); 16: @} @end group @end example @noindent Only the lines that illustrate new syntactic symbols will be discussed. @cindex substatement-open syntactic symbol @cindex substatement-block-intro syntactic symbol @cindex block-close syntactic symbol Line 4 has a brace which opens a conditional's substatement block. It is thus assigned @code{substatement-open} syntax, and since line 5 is the first line in the substatement block, it is assigned @code{substatement-block-intro} syntax. Lines 6 and 7 are assigned similar syntax. Line 8 contains the brace that closes the inner substatement block. It is given the syntax @code{block-close}, as are lines 11 and 14. @cindex else-clause syntactic symbol @cindex catch-clause syntactic symbol Line 9 is a little different --- since it contains the keyword @code{else} matching the @code{if} statement introduced on line 5, it is given the @code{else-clause} syntax. The @code{try}-@code{catch} constructs in C++ and Java are treated this way too, with the only difference that the @code{catch}, and in Java also @code{finally}, is marked with @code{catch-clause}. @cindex substatement syntactic symbol Line 10 is also slightly different. Because @code{else} is considered a conditional introducing keyword @footnote{The list of conditional keywords are (in C, C++, Objective-C, Java, and Pike): @code{for}, @code{if}, @code{do}, @code{else}, @code{while}, and @code{switch}. C++ and Java have two additional conditional keywords: @code{try} and @code{catch}. Java also has the @code{finally} and @code{synchronized} keywords.}, and because the following substatement is not a brace block, line 10 is assigned the @code{substatement} syntax. @cindex do-while-closure syntactic symbol One other difference is seen on line 15. The @code{while} construct that closes a @code{do} conditional is given the special syntax @code{do-while-closure} if it appears on a line by itself. Note that if the @code{while} appeared on the same line as the preceding close brace, that line would have been assigned @code{block-close} syntax instead. Switch statements have their own set of syntactic symbols. Here's an example: @example @group 1: void spam( enum Ingredient i ) 2: @{ 3: switch( i ) @{ 4: case Ham: 5: be_a_pig(); 6: break; 7: case Salt: 8: drink_some_water(); 9: break; 10: default: 11: @{ 12: what_is_it(); 13: break; 14: @} 15: @} 14: @} @end group @end example @cindex case-label syntactic symbol @cindex statement-case-intro syntactic symbol @cindex statement-case-open syntactic symbol Here, lines 4, 7, and 10 are all assigned @code{case-label} syntax, while lines 5 and 8 are assigned @code{statement-case-intro}. Line 11 is treated slightly differently since it contains a brace that opens a block --- it is given @code{statement-case-open} syntax. @cindex brace lists There are a set of syntactic symbols that are used to recognize constructs inside of brace lists. A brace list is defined as an @code{enum} or aggregate initializer list, such as might statically initialize an array of structs. The three special aggregate constructs in Pike, @code{(@{ @})}, @code{([ ])} and @code{(< >)}, are treated as brace lists too. An example: @example @group 1: static char* ingredients[] = 2: @{ 3: "Ham", 4: "Salt", 5: NULL 6: @} @end group @end example @cindex brace-list-open syntactic symbol @cindex brace-list-intro syntactic symbol @cindex brace-list-close syntactic symbol @cindex brace-list-entry syntactic symbol Following convention, line 2 in this example is assigned @code{brace-list-open} syntax, and line 3 is assigned @code{brace-list-intro} syntax. Likewise, line 6 is assigned @code{brace-list-close} syntax. Lines 4 and 5 however, are assigned @code{brace-list-entry} syntax, as would all subsequent lines in this initializer list. @cindex brace-entry-open syntactic symbol Your static initializer might be initializing nested structures, for example: @example @group 1: struct intpairs[] = 2: @{ 3: @{ 1, 2 @}, 4: @{ 5: 3, 6: 4 7: @} 8: @{ 1, 9: 2 @}, 10: @{ 3, 4 @} 11: @} @end group @end example Here, you've already seen the analysis of lines 1, 2, 3, and 11. On line 4, things get interesting; this line is assigned @code{brace-entry-open} syntactic symbol because it's a bracelist entry line that starts with an open brace. Lines 5 and 6 (and line 9) are pretty standard, and line 7 is a @code{brace-list-close} as you'd expect. Once again, line 8 is assigned as @code{brace-entry-open} as is line 10. External language definition blocks also have their own syntactic symbols. In this example: @example @group 1: extern "C" 2: @{ 3: int thing_one( int ); 4: int thing_two( double ); 5: @} @end group @end example @cindex extern-lang-open syntactic symbol @cindex extern-lang-close syntactic symbol @cindex inextern-lang syntactic symbol @cindex inclass syntactic symbol @noindent line 2 is given the @code{extern-lang-open} syntax, while line 5 is given the @code{extern-lang-close} syntax. The analysis for line 3 yields: @code{((inextern-lang) (topmost-intro . 14))}, where @code{inextern-lang} is a modifier similar in purpose to @code{inclass}. Similarly, C++ namespace constructs have their own associated syntactic symbols. In this example: @example @group 1: namespace foo 2: @{ 3: void xxx() @{@} 4: @} @end group @end example @cindex namespace-open syntactic symbol @cindex namespace-close syntactic symbol @cindex innamespace syntactic symbol @noindent line 2 is given the @code{namespace-open} syntax, while line 4 is given the @code{namespace-close} syntax. The analysis for line 3 yields: @code{((innamespace) (topmost-intro . 17))}, where @code{innamespace} is a modifier similar in purpose to @code{inextern-lang} and @code{inclass}. A number of syntactic symbols are associated with parenthesis lists, a.k.a argument lists, as found in function declarations and function calls. This example illustrates these: @example @group 1: void a_function( int line1, 2: int line2 ); 3: 4: void a_longer_function( 5: int line1, 6: int line2 7: ); 8: 9: void call_them( int line1, int line2 ) 10: @{ 11: a_function( 12: line1, 13: line2 14: ); 15: 16: a_longer_function( line1, 17: line2 ); 18: @} @end group @end example @cindex arglist-intro syntactic symbol @cindex arglist-close syntactic symbol Lines 5 and 12 are assigned @code{arglist-intro} syntax since they are the first line following the open parenthesis, and lines 7 and 14 are assigned @code{arglist-close} syntax since they contain the parenthesis that closes the argument list. @cindex arglist-cont-nonempty syntactic symbol @cindex arglist-cont syntactic symbol Lines that continue argument lists can be assigned one of two syntactic symbols. For example, Lines 2 and 17 are assigned @code{arglist-cont-nonempty} syntax. What this means is that they continue an argument list, but that the line containing the parenthesis that opens the list is @emph{not empty} following the open parenthesis. Contrast this against lines 6 and 13 which are assigned @code{arglist-cont} syntax. This is because the parenthesis that opens their argument lists is the last character on that line. 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. A few miscellaneous syntactic symbols that haven't been previously covered are illustrated by this C++ example: @example @group 1: void Bass::play( int volume ) 2: const 3: @{ 4: /* this line starts a multi-line 5: * comment. This line should get `c' syntax */ 6: 7: char* a_multiline_string = "This line starts a multi-line \ 8: string. This line should get `string' syntax."; 9: 10: note: 11: @{ 12: #ifdef LOCK 13: Lock acquire(); 14: #endif // LOCK 15: slap_pop(); 16: cout << "I played " 17: << "a note\n"; 18: @} 19: @} @end group @end example The lines to note in this example include: @itemize @bullet @cindex func-decl-cont syntactic symbol @item Line 2 is assigned the @code{func-decl-cont} syntax. @cindex comment-intro syntactic symbol @item Line 4 is assigned both @code{defun-block-intro} @emph{and} @code{comment-intro} syntax. @cindex c syntactic symbol @item 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. @cindex string syntactic symbol @item Line 8 is assigned @code{string} syntax. @cindex label syntactic symbol @item Line 10 is assigned @code{label} syntax. @cindex block-open syntactic symbol @item Line 11 is assigned @code{block-open} syntax. @cindex cpp-macro syntactic symbol @cindex cpp-macro-cont syntactic symbol @item Lines 12 and 14 are assigned @code{cpp-macro} syntax in addition to the normal syntactic symbols (@code{statement-block-intro} and @code{statement}, respectively). Normally @code{cpp-macro} is configured to cancel out the normal syntactic context to make all preprocessor directives stick to the first column, but that's easily changed if you want preprocessor directives to be indented like the rest of the code. @cindex stream-op syntactic symbol @item Line 17 is assigned @code{stream-op} syntax. @end itemize @cindex multi-line macros @cindex syntactic whitespace Multi-line C preprocessor macros are now (somewhat) supported. At least @ccmode{} now recognizes the fact that it is inside a multi-line macro, and it properly skips such macros as syntactic whitespace. In this example: @example @group 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 group @end example @noindent line 1 is given the syntactic symbol @code{cpp-macro}. This first line of a macro is always given this symbol. The second and subsequent lines (e.g. lines 2 through 5) are given the @code{cpp-macro-cont} syntactic symbol, with a relative buffer position pointing to the @code{#} which starts the macro definition. In Objective-C buffers, there are three additional syntactic symbols assigned to various message calling constructs. Here's an example illustrating these: @example @group 1: - (void)setDelegate:anObject 2: withStuff:stuff 3: @{ 4: [delegate masterWillRebind:self 5: toDelegate:anObject 6: withExtraStuff:stuff]; 7: @} @end group @end example @cindex objc-method-intro syntactic symbol @cindex objc-method-args-cont syntactic symbol @cindex objc-method-call-cont syntactic symbol Here, line 1 is assigned @code{objc-method-intro} syntax, and line 2 is assigned @code{objc-method-args-cont} syntax. Lines 5 and 6 are both assigned @code{objc-method-call-cont} syntax. Java has a concept of anonymous classes, which may look something like this: @example @group 1: public void watch(Observable o) @{ 2: o.addObserver(new Observer() @{ 3: public void update(Observable o, Object arg) @{ 4: history.addElement(arg); 5: @} 6: @}); 7: @} @end group @end example @cindex inexpr-class syntactic symbol The brace following the @code{new} operator opens the anonymous class. Lines 3 and 6 are assigned the @code{inexpr-class} syntax, besides the @code{inclass} symbol used in normal classes. Thus, the class will be indented just like a normal class, with the added indentation given to @code{inexpr-class}. There are a few occasions where a statement block may be used inside an expression. One is in C code using the gcc extension for this, e.g: @example @group 1: int res = (@{ 2: int y = foo (); int z; 3: if (y > 0) z = y; else z = - y; 4: z; 5: @}); @end group @end example @cindex inexpr-statement syntactic symbol Lines 2 and 5 get the @code{inexpr-statement} syntax, besides the symbols they'd get in a normal block. Therefore, the indentation put on @code{inexpr-statement} is added to the normal statement block indentation. In Pike code, there are a few other situations where blocks occur inside statements, as illustrated here: @example @group 1: array itgob() 2: @{ 3: string s = map (backtrace()[-2][3..], 4: lambda 5: (mixed arg) 6: @{ 7: return sprintf ("%t", arg); 8: @}) * ", " + "\n"; 9: return catch @{ 10: write (s + "\n"); 11: @}; 12: @} @end group @end example @cindex inlambda syntactic symbol @cindex lambda-intro-cont syntactic symbol Lines 4 through 8 contain a lambda function, which @ccmode{} recognizes by the @code{lambda} keyword. If the function argument list is put on a line of its own, as in line 5, it gets the @code{lambda-intro-cont} syntax. The function body is handled as an inline method body, with the addition of the @code{inlambda} syntactic symbol. This means that line 6 gets @code{inlambda} and @code{inline-open}, and line 8 gets @code{inline-close}@footnote{You might wonder why it doesn't get @code{inlambda} too. It's because the closing brace is relative to the opening brace, which stands on its own line in this example. If the opening brace was hanging on the previous line, then the closing brace would get the @code{inlambda} syntax too to be indented correctly.}. @cindex inexpr-statement syntactic symbol On line 9, @code{catch} is a special function taking a statement block as its argument. The block is handled as an in-expression statement with the @code{inexpr-statement} syntax, just like the gcc extended C example above. The other similar special function, @code{gauge}, is handled like this too. @cindex knr-argdecl-intro syntactic symbol @cindex knr-argdecl syntactic symbol Two other syntactic symbols can appear in old style, non-prototyped C code @footnote{a.k.a. K&R C, or Kernighan & Ritchie C}: @example @group 1: int add_three_integers(a, b, c) 2: int a; 3: int b; 4: int c; 5: @{ 6: return a + b + c; 7: @} @end group @end example Here, line 2 is the first line in an argument declaration list and so is given the @code{knr-argdecl-intro} syntactic symbol. Subsequent lines (i.e. lines 3 and 4 in this example), are given @code{knr-argdecl} syntax. @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @node Indentation Functions, Performance Issues, Syntactic Symbols, Top @comment node-name, next, previous, up @chapter Indentation Functions @cindex indentation functions @cindex line-up functions @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! Often there are cases when a simple offset setting on a syntactic symbol isn't enough to get the desired indentation. Therefore, it's also possible to use a @dfn{indentation function} (a.k.a. line-up function) for a syntactic symbol. @ccmode{} comes with many predefined indentation functions for common situations. If none of these does what you want, you can write your own, see @ref{Custom Indentation Functions}. If you do, it's probably a good idea to start working from one of these predefined functions, they can be found in the file @file{cc-align.el}. For every function below there is a ``works with'' list that indicates which syntactic symbols the function is intended to be used with. @macro workswith @emph{Works with:} @end macro @ifinfo @unmacro workswith @macro workswith Works with: @end macro @end ifinfo @table @code @findex c-lineup-arglist @findex lineup-arglist (c-) @item c-lineup-arglist Line up the current argument line under the first argument. @workswith @code{arglist-cont-nonempty}. @findex c-lineup-arglist-intro-after-paren @findex lineup-arglist-intro-after-paren (c-) @item c-lineup-arglist-intro-after-paren Line up a line just after the open paren of the surrounding paren or brace block. @workswith @code{defun-block-intro}, @code{brace-list-intro}, @code{statement-block-intro}, @code{statement-case-intro}, @code{arglist-intro}. @findex c-lineup-arglist-close-under-paren @findex lineup-arglist-close-under-paren (c-) @item c-lineup-arglist-close-under-paren Set e.g. your @code{arglist-close} syntactic symbol to this line-up function so that parentheses that close argument lists will line up under the parenthesis that opened the argument list. @workswith @code{defun-close}, @code{class-close}, @code{inline-close}, @code{block-close}, @code{brace-list-close}, @code{arglist-close}, @code{extern-lang-close}, @code{namespace-close} (for most of these, a zero offset will normally produce the same result, though). @findex c-lineup-close-paren @findex lineup-close-paren (c-) @item c-lineup-close-paren Line up the closing paren under its corresponding open paren if the open paren is followed by code. If the open paren ends its line, no indentation is added. E.g: @example @group main (int, char ** ) // c-lineup-close-paren @end group @end example @noindent and @example @group main ( int, char ** ) // c-lineup-close-paren @end group @end example @workswith @code{defun-close}, @code{class-close}, @code{inline-close}, @code{block-close}, @code{brace-list-close}, @code{arglist-close}, @code{extern-lang-close}, @code{namespace-close}. @findex c-lineup-streamop @findex lineup-streamop (c-) @item c-lineup-streamop Line up C++ stream operators (i.e. @samp{<<} and @samp{>>}). @workswith @code{stream-op}. @findex c-lineup-multi-inher @findex lineup-multi-inher (c-) @item c-lineup-multi-inher Line up the classes in C++ multiple inheritance clauses and member initializers under each other. E.g: @example @group Foo::Foo (int a, int b): Cyphr (a), Bar (b) // c-lineup-multi-inher @end group @end example @noindent and @example @group class Foo : public Cyphr, public Bar // c-lineup-multi-inher @end group @end example @noindent and @example @group Foo::Foo (int a, int b) : Cyphr (a) , Bar (b) // c-lineup-multi-inher @end group @end example @workswith @code{inher-cont}, @code{member-init-cont}. @findex c-lineup-java-inher @findex lineup-java-inher (c-) @item c-lineup-java-inher Line up Java implements and extends declarations. If class names follows on the same line as the @samp{implements}/@samp{extends} keyword, they are lined up under each other. Otherwise, they are indented by adding @code{c-basic-offset} to the column of the keyword. E.g: @example @group class Foo extends Bar // c-lineup-java-inher <--> c-basic-offset @end group @end example @noindent and @example @group class Foo extends Cyphr, Bar // c-lineup-java-inher @end group @end example @workswith @code{inher-cont}. @findex c-lineup-java-throws @findex lineup-java-throws (c-) @item c-lineup-java-throws Line up Java throws declarations. If exception names follows on the same line as the throws keyword, they are lined up under each other. Otherwise, they are indented by adding @code{c-basic-offset} to the column of the @samp{throws} keyword. The @samp{throws} keyword itself is also indented by @code{c-basic-offset} from the function declaration start if it doesn't hang. E.g: @example @group int foo() throws // c-lineup-java-throws Bar // c-lineup-java-throws <--><--> c-basic-offset @end group @end example @noindent and @example @group int foo() throws Cyphr, Bar, // c-lineup-java-throws Vlod // c-lineup-java-throws @end group @end example @workswith @code{func-decl-cont}. @findex c-indent-one-line-block @findex indent-one-line-block (c-) @item c-indent-one-line-block Indent a one line block @code{c-basic-offset} extra. E.g: @example @group if (n > 0) @{m+=n; n=0;@} // c-indent-one-line-block <--> c-basic-offset @end group @end example @noindent and @example @group if (n > 0) @{ // 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. @findex c-indent-multi-line-block @findex indent-multi-line-block (c-) @item c-indent-multi-line-block Indent a multi line block @code{c-basic-offset} extra. E.g: @example @group int *foo[] = @{ NULL, @{17@}, // c-indent-multi-line-block @end group @end example @noindent and @example @group int *foo[] = @{ NULL, @{ // c-indent-multi-line-block 17 @}, <--> c-basic-offset @end group @end example The block may be surrounded by any kind of parenthesis characters. @code{nil} is returned if the line doesn't start with a multi line block, which makes the function usable in list expressions. @workswith Almost all syntactic symbols, but most useful on the @code{-open} symbols. @findex c-lineup-C-comments @findex lineup-C-comments (c-) @item c-lineup-C-comments Line up C block comment continuation lines. Various heuristics are used to handle most of the common comment styles. Some examples: @example @group /* /** /* * text * text text */ */ */ @end group @group /* text /* /** text ** text ** text */ */ */ @end group @group /************************************************** * text *************************************************/ @end group @vindex comment-start-skip @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. @findex c-lineup-comment @findex lineup-comment (c-) @item c-lineup-comment Line up a comment-only line according to the style variable @code{c-comment-only-line-offset}. If the comment is lined up with a comment starter on the previous line, that alignment is preserved. @vindex c-comment-only-line-offset @vindex comment-only-line-offset (c-) @code{c-comment-only-line-offset} specifies the extra offset for the line. It can contain an integer or a cons cell of the form @example (@r{<non-anchored-offset>} . @r{<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{<value>} . -1000)}. @workswith @code{comment-intro}. @findex c-lineup-runin-statements @findex lineup-runin-statements (c-) @item c-lineup-runin-statements Line up statements for coding standards which place the first statement in a block on the same line as the block opening brace@footnote{Run-in style doesn't really work too well. You might need to write your own custom indentation functions to better support this style.}. E.g: @example @group int main() @{ puts (\"Hello world!\"); return 0; // c-lineup-runin-statements @} @end group @end example If there is no statement after the opening brace to align with, @code{nil} is returned. This makes the function usable in list expressions. @workswith The @code{statement} syntactic symbol. @findex c-lineup-math @findex lineup-math (c-) @item c-lineup-math Line up the current line after the equal sign on the first line in the statement. If there isn't any, indent with @code{c-basic-offset}. If the current line contains an equal sign too, try to align it with the first one. @workswith @code{statement-cont}. @findex c-lineup-template-args @findex lineup-template-args (c-) @item c-lineup-template-args Line up the arguments of a template argument list under each other, but only in the case where the first argument is on the same line as the opening @samp{<}. To allow this function to be used in a list expression, @code{nil} is returned if there's no template argument on the first line. @workswith @code{template-args-cont}. @findex c-lineup-ObjC-method-call @findex lineup-ObjC-method-call (c-) @item c-lineup-ObjC-method-call For Objective-C code, line up selector args as @code{elisp-mode} does with function args: go to the position right after the message receiver, and if you are at the end of the line, indent the current line c-basic-offset columns from the opening bracket; otherwise you are looking at the first character of the first method call argument, so lineup the current line with it. @workswith @code{objc-method-call-cont}. @findex c-lineup-ObjC-method-args @findex lineup-ObjC-method-args (c-) @item c-lineup-ObjC-method-args For Objective-C code, line up the colons that separate args. The colon on the current line is aligned with the one on the first line. @workswith @code{objc-method-args-cont}. @findex c-lineup-ObjC-method-args-2 @findex lineup-ObjC-method-args-2 (c-) @item c-lineup-ObjC-method-args-2 Similar to @code{c-lineup-ObjC-method-args} but lines up the colon on the current line with the colon on the previous line. @workswith @code{objc-method-args-cont}. @findex c-lineup-inexpr-block @findex lineup-inexpr-block (c-) @item c-lineup-inexpr-block This can be used with the in-expression block symbols to indent the whole block to the column where the construct is started. E.g. for Java anonymous classes, this lines up the class under the @samp{new} keyword, and in Pike it lines up the lambda function body under the @samp{lambda} keyword. Returns @code{nil} if the block isn't part of such a construct. @workswith @code{inlambda}, @code{inexpr-statement}, @code{inexpr-class}. @findex c-lineup-whitesmith-in-block @findex lineup-whitesmith-in-block (c-) @item c-lineup-whitesmith-in-block Line up lines inside a block in Whitesmith style. It's done in a way that works both when the opening brace hangs and when it doesn't. E.g: @example @group something @{ foo; // c-lineup-whitesmith-in-block @} @end group @end example @noindent and @example @group something @{ foo; // c-lineup-whitesmith-in-block @} <--> c-basic-offset @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{block-close}, @code{brace-list-close}, @code{brace-list-intro}, @code{statement-block-intro}, @code{inclass}, @code{inextern-lang}, @code{innamespace}. @findex c-lineup-dont-change @findex lineup-dont-change (c-) @item c-lineup-dont-change This lineup function returns the indentation of the current line. Think of it as an identity function for lineups; it is used for @code{cpp-macro-cont} lines. @workswith Any syntactic symbol. @end table @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @node Performance Issues, Frequently Asked Questions, Indentation Functions, Top @comment node-name, next, previous, up @chapter Performance Issues @cindex performance issues @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! C and its derivative languages are highly complex creatures. Often, ambiguous code situations arise that require @ccmode{} to scan large portions of the buffer to determine syntactic context. Such pathological code@footnote{such as the output of @code{lex(1)}!} can cause @ccmode{} to perform fairly badly. This section identifies some of the coding styles to watch out for, and suggests some workarounds that you can use to improve performance. Because @ccmode{} has to scan the buffer backwards from the current insertion point, and because C's syntax is fairly difficult to parse in the backwards direction, @ccmode{} often tries to find the nearest position higher up in the buffer from which to begin a forward scan. The farther this position is from the current insertion point, the slower the mode gets. Some coding styles can even force @ccmode{} to scan from the beginning of the buffer for every line of code! @findex beginning-of-defun @findex defun-prompt-regexp One of the simplest things you can do to reduce scan time, is make sure any brace that opens a top-level construct@footnote{E.g. a function in C, or outermost class definition in C++ or Java.} always appears in the leftmost column. This is actually an Emacs constraint, as embodied in the @code{beginning-of-defun} function which @ccmode{} uses heavily. If you insist on hanging top-level open braces on the right side of the line, then you might want to set the variable @code{defun-prompt-regexp} to something reasonable, however that ``something reasonable'' is difficult to define, so @ccmode{} doesn't do it for you. @vindex c-Java-defun-prompt-regexp @vindex Java-defun-prompt-regexp (c-) A special note about @code{defun-prompt-regexp} in Java mode: while much of the early sample Java code seems to encourage a style where the brace that opens a class is hung on the right side of the line, this is not a good style to pursue in Emacs. @ccmode{} comes with a variable @code{c-Java-defun-prompt-regexp} which tries to define a regular expression usable for this style, but there are problems with it. In some cases it can cause @code{beginning-of-defun} to hang@footnote{This has been observed in Emacs 19.34 and XEmacs 19.15.}. For this reason, it is not used by default, but if you feel adventurous, you can set @code{defun-prompt-regexp} to it in your mode hook. In any event, setting and rely on @code{defun-prompt-regexp} will definitely slow things down anyway because you'll be doing regular expression searches for every line you indent, so you're probably screwed either way! @vindex c-enable-xemacs-performance-kludge-p @vindex enable-xemacs-performance-kludge-p (c-) Another alternative for XEmacs users, is to set the variable @code{c-enable-xemacs-performance-kludge-p} to non-@code{nil}. This tells @ccmode{} to use XEmacs-specific built-in functions which, in some circumstances, can locate the top-most opening brace much quicker than @code{beginning-of-defun}. Preliminary testing has shown that for styles where these braces are hung (e.g. most JDK-derived Java styles), this hack can improve performance of the core syntax parsing routines from 3 to 60 times. However, for styles which @emph{do} conform to Emacs' recommended style of putting top-level braces in column zero, this hack can degrade performance by about as much. Thus this variable is set to @code{nil} by default, since the Emacs-friendly styles should be more common (and encouraged!). Note that this variable has no effect in Emacs since the necessary built-in functions don't exist (in Emacs 20.2 or 20.3 as of this writing 27-Apr-1998). You will probably notice pathological behavior from @ccmode{} when working in files containing large amounts of C preprocessor macros. This is because Emacs cannot skip backwards over these lines as quickly as it can comments. @vindex c-recognize-knr-p @vindex recognize-knr-p (c-) Previous versions of @ccmode{} had potential performance problems when recognizing K&R style function argument declarations. This was because there are ambiguities in the C syntax when K&R style argument lists are used@footnote{It is hard to distinguish them from top-level declarations.}. @ccmode{} has adopted BOCM's convention for limiting the search: it assumes that argdecls are indented at least one space, and that the function headers are not indented at all. With current versions of @ccmode{}, user customization of @code{c-recognize-knr-p} is deprecated. Just don't put argdecls in column zero! @cindex @file{cc-lobotomy.el} file @vindex cc-lobotomy-pith-list You might want to investigate the speed-ups contained in the file @file{cc-lobotomy.el}, which comes as part of the @ccmode{} distribution, but is completely unsupported. As mentioned previous, @ccmode{} always trades speed for accuracy, however it is recognized that sometimes you need speed and can sacrifice some accuracy in indentation. The file @file{cc-lobotomy.el} contains hacks that will ``dumb down'' @ccmode{} in some specific ways, making that trade-off of accurancy for speed. I won't go into details of its use here; you should read the comments at the top of the file, and look at the variable @code{cc-lobotomy-pith-list} for details. @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @node Frequently Asked Questions, Getting the Latest CC Mode Release, Performance Issues, Top @comment node-name, next, previous, up @chapter Frequently Asked Questions @cindex frequently asked questions @cindex FAQ @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @kindex C-x h @kindex C-M-\ @kindex C-M-x @kindex C-M-q @kindex C-M-u @kindex RET @kindex C-j @quotation @strong{Q.} @emph{How do I re-indent the whole file?} @strong{A.} Visit the file and hit @kbd{C-x h} to mark the whole buffer. Then hit @kbd{C-M-\}. @sp 1 @strong{Q.} @emph{How do I re-indent the entire function? @kbd{C-M-x} doesn't work.} @strong{A.} @kbd{C-M-x} is reserved for future Emacs use. To re-indent the entire function hit @kbd{C-c C-q}. @sp 1 @strong{Q.} @emph{How do I re-indent the current block?} @strong{A.} First move to the brace which opens the block with @kbd{C-M-u}, then re-indent that expression with @kbd{C-M-q}. @sp 1 @strong{Q.} @emph{Why doesn't the @kbd{RET} key indent the new line?} @strong{A.} Emacs' convention is that @kbd{RET} just adds a newline, and that @kbd{C-j} adds a newline and indents it. You can make @kbd{RET} do this too by adding this to your @code{c-mode-common-hook}: @example (define-key c-mode-base-map "\C-m" 'c-context-line-break) @end example This is a very common question. If you want this to be the default behavior, don't lobby me, lobby RMS! @t{:-)} @sp 1 @strong{Q.} @emph{I put @code{(c-set-offset 'substatement-open 0)} in my @file{.emacs} file but I get an error saying that @code{c-set-offset}'s function definition is void.} @strong{A.} This means that @ccmode{} wasn't loaded into your Emacs session by the time the @code{c-set-offset} call was reached, mostly likely because @ccmode{} is being autoloaded. Instead of putting the @code{c-set-offset} line in your top-level @file{.emacs} file, put it in your @code{c-mode-common-hook}, or simply modify @code{c-offsets-alist} directly: @example (setq c-offsets-alist '((substatement-open . 0))) @end example @sp 1 @strong{Q.} @emph{My style settings works in all the @ccmode{} language modes except for Java, where I still get e.g. 4 column indentation.} @strong{A.} Java mode switches to the @samp{java} style by default for historical reasons. You can override it by putting an association list on @code{c-default-style}: @example (setq c-default-style '((other . "my-style"))) @end example @noindent The @samp{other} symbol says that @ccmode{} should use "my-style" in all modes not explicitly listed. Since there's nothing else on the list this causes "my-style" to be used in every mode. @sp 1 @strong{Q.} @emph{How do I make strings, comments, keywords, and other constructs appear in different colors, or in bold face, etc.?} @strong{A.} ``Syntax Colorization'' is a standard Emacs feature, controlled by @code{font-lock-mode}. @ccmode{} does not contain font-lock definitions for any of its supported languages. @sp 1 @strong{Q.} @emph{@kbd{M-a} and @kbd{M-e} used to move over entire balanced brace lists, but now they move into blocks. How do I get the old behavior back?} @strong{A.} Use @kbd{C-M-f} and @kbd{C-M-b} to move over balanced brace blocks. Use @kbd{M-a} and @kbd{M-e} to move by statements, which will also move into blocks. @sp 1 @strong{Q.} @emph{Whenever I try to indent a line or type an ``electric'' key such as @kbd{;}, @kbd{@{}, or @kbd{@}}, I get an error that look like this: @code{Invalid function: (macro . #[...}. What gives?} @strong{A.} This is a common error when @ccmode{} hasn't been compiled correctly, especially under Emacs 19.34@footnote{Technically, it's because some macros wasn't defined during the compilation, so the byte compiler put in function calls instead of the macro expansions. Later, when the interpreter tries to call the macros as functions, it shows this (somewhat cryptic) error message.}. If you are using the standalone @ccmode{} distribution, try recompiling it according to the instructions in the @file{README} file. @end quotation @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @node Getting the Latest CC Mode Release, Sample .emacs File, Frequently Asked Questions, Top @comment node-name, next, previous, up @chapter Getting the Latest CC Mode Release @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @ccmode{} is standard with all versions of Emacs since 19.34 and of XEmacs since 19.16. Due to release schedule skew, it is likely that all of these Emacsen have old versions of @ccmode{} and so should be upgraded. Access to the @ccmode{} source code, as well as more detailed information on Emacsen compatibility, etc. are all available via the Web at: @example @group @uref{http://cc-mode.sourceforge.net/} @end group @end example @emph{Old URLs, including the FTP URLs, should no longer be used.} There are many files under these directories; you can pick up the entire distribution (named @code{cc-mode.tar.gz}; a gzip'd tar file), or any of the individual files, including PostScript documentation. @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @node Sample .emacs File, Limitations and Known Bugs, Getting the Latest CC Mode Release, Top @comment node-name, next, previous, up @chapter Sample .emacs file @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @example ;; Here's a sample .emacs file that might help you along the way. Just ;; copy this region and paste it into your .emacs file. You may want to ;; change some of the actual values. (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") ;; offset customizations not in my-c-style (setq c-offsets-alist '((member-init-intro . ++))) ;; Customizations for all modes in CC Mode. (defun my-c-mode-common-hook () ;; add my personal style and set it for the current buffer (c-add-style "PERSONAL" my-c-style t) ;; other customizations (setq tab-width 8 ;; this will make sure spaces are used instead of tabs indent-tabs-mode nil) ;; we like auto-newline and hungry-delete (c-toggle-auto-hungry-state 1) ;; keybindings for all supported languages. We can put these in ;; c-mode-base-map because c-mode-map, c++-mode-map, objc-mode-map, ;; java-mode-map, idl-mode-map, and pike-mode-map inherit from it. (define-key c-mode-base-map "\C-m" 'c-context-line-break) ) (add-hook 'c-mode-common-hook 'my-c-mode-common-hook) @end example @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @node Limitations and Known Bugs, Mailing Lists and Submitting Bug Reports, Sample .emacs File, Top @comment node-name, next, previous, up @chapter Limitations and Known Bugs @cindex limitations @cindex bugs @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @itemize @bullet @item Re-indenting large regions or expressions can be slow. @findex c-indent-exp @findex indent-exp (c-) @item @code{c-indent-exp} has not been fully optimized. It essentially equivalent to hitting @kbd{TAB} (@code{c-indent-command}) on every line. Some information is cached from line to line, but such caching invariable causes inaccuracies in analysis in some bizarre situations. @vindex signal-error-on-buffer-boundary @item XEmacs versions from 19.15 until (as of this writing 12-Mar-1998) 20.4 contain a variable called @code{signal-error-on-buffer-boundary}. This was intended as a solution to user interface problems associated with buffer movement and the @code{zmacs-region} deactivation on errors. However, setting this variable to a non-default value had the deleterious side effect of breaking many built-in primitive functions. Most users will not be affected since they never change the value of this variable. @strong{Do not set this variable to @code{nil}}; you will cause serious problems in @ccmode{} and probably other XEmacs packages! As of at least XEmacs 20.4, the effects this variable tried to correct have been fixed in other, better ways. @end itemize @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @node Mailing Lists and Submitting Bug Reports, Concept Index, Limitations and Known Bugs, Top @comment node-name, next, previous, up @chapter Mailing Lists and Submitting Bug Reports @cindex mailing lists @cindex reporting bugs @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @kindex C-c C-b @findex c-submit-bug-report @findex submit-bug-report (c-) To report bugs, use the @kbd{C-c C-b} (@code{c-submit-bug-report}) command. This provides vital information we need to reproduce your problem. Make sure you include a concise, but complete code example. Please try to boil your example down to just the essential code needed to reproduce the problem, and include an exact recipe of steps needed to expose the bug. Be especially sure to include any code that appears @emph{before} your bug example, if you think it might affect our ability to reproduce it. Please try to produce the problem in an Emacs instance without any customizations loaded (i.e. start it with the @code{-q -no-site-file} arguments). If it works correctly there, the problem might be caused by faulty customizations in either your own or your site configuration. In that case, we'd appreciate if you isolate the Emacs Lisp code that trigs the bug and include it in your report. Bug reports are now sent to the following email addresses: @email{bug-cc-mode@@gnu.org} and @email{bug-gnu-emacs@@gnu.org}; the latter is mirrored on the Usenet newsgroup @code{gnu.emacs.bug}. You can send other questions and suggestions (kudos? @t{;-)} to @email{bug-cc-mode@@gnu.org}, or @email{help-gnu-emacs@@gnu.org} which is mirrored on newsgroup @code{gnu.emacs.help}. @cindex beta testers mailing list @cindex announcement mailing list If you want to get announcements of new @ccmode{} releases, send the word @emph{subscribe} in the body of a message to @email{cc-mode-announce-request@@lists.sourceforge.net}. Announcements will also be posted to the Usenet newsgroups @code{gnu.emacs.sources}, @code{comp.emacs}, @code{comp.emacs.xemacs}, and possibly some of the language oriented newsgroups. @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @node Concept Index, Command Index, Mailing Lists and Submitting Bug Reports, Top @comment node-name, next, previous, up @unnumbered Concept Index @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @printindex cp @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @node Command Index, Key Index, Concept Index, Top @comment node-name, next, previous, up @unnumbered Command 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 Key Index, Variable Index, Command Index, Top @comment node-name, next, previous, up @unnumbered Key Index @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @printindex ky @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @node Variable Index, , Key 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 @page @summarycontents @contents @bye